Skip to content

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

Β 

History

10 Commits

Folders and files

Repository files navigation

Tailwind CSS Prefix Migrator

npm version License: MIT Node.js Version

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().


πŸš€ Key Features

  • AST-Driven Precision (Babel & PostCSS): Uses @babel/parser and @babel/traverse for JavaScript/TypeScript AST analysis and postcss-scss for CSS/SCSS parsing. Avoids regular expression pitfalls and preserves code structure.
  • Automatic CSS Layer Wrapping: Automatically wraps @tailwind directives 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 and cn(...) calls.
  • Automatic Config Sync: Updates prefix and preflight settings directly in tailwind.config.js and components.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.

πŸ“¦ Installation

Install as a development dependency:

npm i -D tailwind-prefix-migrator

Or run on-demand via npx:

npx tailwind-prefix-migrator init

Short CLI alias available: tpm


🚦 Quick Start

1. Initialize Configuration

Generates prefix-migrator.config.json in your project root:

npx tailwind-prefix-migrator init

2. Preview Changes (Dry-Run)

Simulate migration without modifying any files:

npx tailwind-prefix-migrator apply --dry-run

3. Run Migration

Apply prefix changes across your codebase:

npx tailwind-prefix-migrator apply

4. Revert / Rollback (If needed)

Strip active prefixes and restore original class names:

npx tailwind-prefix-migrator revert

πŸ“– CLI Commands & Options

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.

Command Options

  • -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 during init (default: calc-).
  • --tailwind-version <3|4> β€” Target Tailwind version for init or eject (default: 3).

πŸ›  Configuration (prefix-migrator.config.json)

{
  "$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
}

Configuration Options Explained

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).

🎯 Transformation Examples

JSX / TSX Attributes

// 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>

SCSS / CSS Directives & Variables

// 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;
}

πŸ’» Programmatic Node.js API

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"

πŸ”— Repository


πŸ“„ License

MIT License Β© Maksim Tsatsura

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages