Tailwind Alchemist 🪄

A CLI tool to manage and replace Tailwind CSS colors in your project.
Built for developers who want to keep their Tailwind color usage clean and consistent.

A common use case:

• You find a great starter kit for your project, but then you realize that all the Tailwind colors are hardcoded into the templates.
• You want to extract them into a custom CSS file so you can easily change them in the future and maintain consistency. However, doing so can be time-consuming.

Tailwind Alchemist has you covered! ✨

---

Installation

No need to install it, you can run it with npx.

Usage

All commands require at least one option -p or --pattern to know where to look for.

• Example with one pattern: -p 'resources/views/**'
• Example with multiple patterns: -p 'resources/views/**' -p 'my/other/folder/**'

Scan for Tailwind Default Colors

To scan your project for Tailwind default colors:

npx tw-alchemist scan -p 'resources/views/**' -p 'some/other/folder/**'

Options:

• -v: Display the files where the colors are found.

npx tw-alchemist scan -p 'resources/views/**' -v

• -vv: Display the files and matches where the colors are found.

npx tw-alchemist scan -p 'resources/views/**' -vv

Scan for a specific color (even a custom one)

npx tw-alchemist scan indigo-800 -p 'resources/views/**' -vv

Replace Colors

To replace an existing color with another one:

npx tw-alchemist replace oldColor newColor -p 'resources/views/**'

To check what would be done without touching files, use --dry-run:

npx tw-alchemist replace oldColor newColor -p 'resources/views/**' --dry-run

Notes:

• If newColor doesn’t exist in your Tailwind config, the tool will print the necessary CSS for you to add.
• If oldColor is one of Tailwind’s default colors, the tool will use its OKLCH value for accurate replacement.

Compatibility

Only compatible with TailwindCSS 4.x.

Should work more or less on TailwindCSS 3.x.

Tested with Node 18.x, 20.x, and 22.x.

Disclaimer

This tool is not affiliated with Tailwind CSS or its creators. It’s a personal project built to help developers manage their Tailwind CSS colors.

Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

Tests

After installing the project locally (npm install), you can run the tests with:

npm run test

Author

Yann Rabiller (@einenlum). You can check my blog and my book From PHP to Python.

License

This project is licensed under the MIT License. See the LICENSE file for details.