Replace and Manage Tailwind CSS Colors with Tailwind Alchemist CLI

Tailwind Alchemist is a command-line interface (CLI) tool designed to help you manage and replace Tailwind CSS colors within your projects.

This tool It allows you to scan your project for specific Tailwind colors, even default ones, and replace them with alternatives. It supports bulk changes as well.

Features

Use Cases

• Starter Kit Refactoring: Imagine you’ve chosen a starter kit for your project, only to find that all the Tailwind colors are hardcoded directly into the templates. Tailwind Alchemist lets you quickly identify and replace these colors, moving them to a custom CSS file or your Tailwind configuration for easier management.
• Design System Enforcement: Your team has established a design system with a specific color palette, and you need to ensure that all components adhere to it. Use Tailwind Alchemist to scan for any deviations and bring them in line with the defined standards.
• Project-Wide Color Updates: Your client requests a change to the primary color scheme across the entire application. Instead of manually updating each instance, you can use Tailwind Alchemist to make a global replacement.
• Legacy Project Cleanup: You may be working with older projects with inconsistent color use. Run the tool to refactor color usage quickly.
• Theme Switching: If you need to generate multiple themes that use the same layout with different color. You can do it with this tool.

Installation

There is no need for installation. You can run the tool directly with npx as follows:

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

You can also scan for specific colors or replace colors without installing the tool:

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

Usage

Scanning for Tailwind Colors

To scan your project for all Tailwind default colors:

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

You can specify multiple patterns to search in various directories:

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

For more detailed output, use verbosity flags:

# Show files where colors are found
npx tw-alchemist scan -p 'resources/views/**' -v
# Show files and specific matches
npx tw-alchemist scan -p 'resources/views/**' -vv

Searching for Specific Colors

To find occurrences of a particular color:

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

This works for both Tailwind default colors and custom colors defined in your project.

Replacing Colors

To replace one color with another across your project:

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

To preview changes without modifying files, use the dry run option:

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

When replacing Tailwind default colors, the tool uses their OKLCH values to ensure accurate color matching. If your replacement color doesn’t exist in your Tailwind configuration, the tool will generate the necessary CSS for you to add.

FAQs

Q: Can I use Tailwind Alchemist with older versions of Tailwind?
A: Tailwind Alchemist is fully compatible with Tailwind CSS 4.x. It should work reasonably well with 3.x, but full compatibility isn’t guaranteed.

Q: What if the new color I want to use isn’t in my Tailwind config?
A: Tailwind Alchemist will detect this and print out the CSS you need to add to your configuration.

Q: Can I see what changes will be made before applying them?
A: Yes, use the --dry-run option with the replace command to preview the changes.

Q: Will replacing colors affect my application’s performance?
A: No, Tailwind Alchemist only modifies the color class names in your source files. It doesn’t impact the compiled CSS or application performance.