An enterprise-grade AST CLI tool to automatically add, isolate, update, or remove prefixes in Tailwind CSS projects (React, Vue, TSX, JS, SCSS, CSS, HTML).
Designed specifically to isolate Tailwind styles when building micro-frontends, widgets, embeddable calculators, and design systems using shadcn/ui, Radix UI, Class Variance Authority (cva), and helper utilities like cn(), clsx(), and twMerge().
- AST-Driven Precision (Babel & PostCSS): Uses
@babel/parserand@babel/traversefor JavaScript/TypeScript AST analysis andpostcss-scssfor CSS/SCSS parsing. Avoids regular expression pitfalls and preserves code structure. - Automatic CSS Layer Wrapping: Automatically wraps
@tailwinddirectives and imported themes inside@layer calc { ... }to prevent style leaks into host applications. - CSS Variable Prefixing: Option to automatically prefix custom CSS variables (
--primaryβ‘οΈ--calc-primary,var(--primary)β‘οΈvar(--calc-primary)). - Pattern Dictionary Filter (v3 & v4): Ships with comprehensive utility dictionaries for Tailwind v3.4+ and v4.0+. Ensures custom BEM classes, icon names (
lucide), and JS variables are never accidentally prefixed. - Zero-Pollution Git Diffs: Tracks file changes strictly. Files that contain no Tailwind classes remain 100% untouched without line-ending or formatting re-generation.
- shadcn/ui & CVA Support: Intelligently distinguishes variant property keys from class values inside
cva(...)objects andcn(...)calls. - Automatic Config Sync: Updates
prefixandpreflightsettings directly intailwind.config.jsandcomponents.json(shadcn/ui). - Instant Rollback (
revert): Reverses prefix migrations in a single command (tpm revert), restoring clean class names across your entire repository. - Dry-Run Mode: Test and review all planned changes in the console before writing anything to disk.
Install as a development dependency:
npm i -D tailwind-prefix-migratorOr run on-demand via npx:
npx tailwind-prefix-migrator initShort CLI alias available: tpm
Generates prefix-migrator.config.json in your project root:
npx tailwind-prefix-migrator initSimulate migration without modifying any files:
npx tailwind-prefix-migrator apply --dry-runApply prefix changes across your codebase:
npx tailwind-prefix-migrator applyStrip active prefixes and restore original class names:
npx tailwind-prefix-migrator revert| Command | Alias | Description |
|---|---|---|
init |
β | Creates default prefix-migrator.config.json in the target project. |
apply |
run |
Runs prefix migration based on configuration (default command). |
revert |
rollback |
Removes active prefixes and restores original un-prefixed classes. |
eject |
publish-config |
Exports Tailwind utility dictionaries to your project for custom editing. |
-p, --project-path <path>β Path to the target project directory (default: current working directory).--dry-runβ Runs in simulation mode without writing files to disk.--prefix <prefix>β Custom prefix to set duringinit(default:calc-).--tailwind-version <3|4>β Target Tailwind version forinitoreject(default:3).
{
"$schema": "http://json.schemastore.org/prefix-migrator",
"prefix": "calc-",
"oldPrefix": "",
"tailwindVersion": "3",
"versionConfigFile": "tailwind-v3.config.json",
"wrapInLayer": "calc",
"cssVarPrefix": "calc-",
"preflight": false,
"targetDirs": [
"./src"
],
"fileExtensions": [
".tsx",
".jsx",
".ts",
".js",
".scss",
".css",
".html"
],
"ignoreClasses": [
"lucide",
"spa-cntr"
],
"customClassFunctions": [
"cn",
"clsx",
"classNames",
"cva",
"twMerge"
],
"updateTailwindConfig": true,
"updateComponentsJson": true
}| Property | Type | Default | Description |
|---|---|---|---|
prefix |
string |
"calc-" |
The new Tailwind prefix to apply to utility classes. |
oldPrefix |
string |
"" |
Existing prefix to replace (if replacing an old prefix). |
tailwindVersion |
string |
"3" |
Major Tailwind version ("3" or "4"). |
versionConfigFile |
string |
"tailwind-v3.config.json" |
Dictionary file containing utility patterns. |
wrapInLayer |
string | false |
"calc" |
Wraps @tailwind and theme directives inside @layer <layerName>. |
cssVarPrefix |
string |
"calc-" |
Prefixes custom CSS variables (e.g. --primary β‘οΈ --calc-primary). |
preflight |
boolean |
false |
Sets corePlugins.preflight in tailwind.config.js (useful to prevent style leaks). |
targetDirs |
string[] |
["./src"] |
Directories to scan recursively for source files. |
fileExtensions |
string[] |
[".tsx", ".jsx", ...] |
File extensions to process during scan. |
ignoreClasses |
string[] |
["lucide", "spa-cntr"] |
Array of custom class names to exclude from prefixing. |
customClassFunctions |
string[] |
["cn", "clsx", ...] |
Names of helper functions whose string arguments should be transformed. |
updateTailwindConfig |
boolean |
true |
Automatically update prefix and preflight in tailwind.config.js. |
updateComponentsJson |
boolean |
true |
Automatically update tailwind.prefix in components.json (shadcn/ui). |
// Before
<div className="flex items-center hover:bg-card -mt-4 custom-class">
<Button className={cn("px-4 py-2", { "bg-primary": active })} />
</div>
// After
<div className="calc-flex calc-items-center hover:calc-bg-card -calc-mt-4 custom-class">
<Button className={cn("calc-px-4 calc-py-2", { "calc-bg-primary": active })} />
</div>// Before
:root {
--primary: 221.2 83.2% 53.3%;
}
.header {
@apply flex items-center justify-between p-4 -z-50;
}
// After
:root {
--calc-primary: 221.2 83.2% 53.3%;
}
.header {
@apply calc-flex calc-items-center calc-justify-between calc-p-4 -calc-z-50;
}You can also import and use the migrator programmatically in custom Node.js build scripts:
import { MigratorRunner, ClassTransformer, CodeMigrator } from 'tailwind-prefix-migrator';
// 1. Run migration programmatically
const runner = new MigratorRunner({
projectPath: './projects/my-app',
dryRun: false,
revert: false,
});
runner.run();
// 2. Transform individual class strings
const transformer = new ClassTransformer('calc-', '', ['ignore-me'], ['flex', 'items-']);
console.log(transformer.transformClassString('flex items-center ignore-me'));
// Output: "calc-flex calc-items-center ignore-me"- GitHub: https://github.com/Maks-T/tailwind-prefix-migrator
- Issues: https://github.com/Maks-T/tailwind-prefix-migrator/issues
MIT License Β© Maksim Tsatsura