Tailwind CSS v4 ClassName Parser & CLI Tool

A ts-morph AST transformation tool, CLI, and Vite plugin designed for Tailwind CSS v4.

It works as:

1. 💻 A CLI Tool: Run from your terminal to transform and write changes directly to disk across any directory.
2. 🔌 A Vite Plugin: Automatically transforms className and cn() utility calls during development (npm run dev) and production bundling (npm run build) while keeping source files on disk clean.
3. 📦 A Node Package / AST Tool: Run programmatically in scripts or custom pipelines.

💻 Running From Command Line (CLI)

You can run the transformer directly from your terminal on any directory. By default, it writes all changes to disk.

Basic Usage

# Transform all files in ./src using default prefix "tw" (writes to disk)
npx tailwind-classname-parser ./src

Or within this repository:

npm run cli -- ./src

Specifying Starting Directory & Prefix

# Specify target directory and custom prefix (e.g. "ui")
npx tailwind-classname-parser ./src --prefix ui

# Short flag: -p
npx tailwind-classname-parser ./components -p ui

Excluding Specific Classes

# Exclude classes like "container" or "prose"
npx tailwind-classname-parser ./src -p ui --exclude container,prose

Previewing Without Modifying Files (Dry Run)

# Use --dry-run or -d to preview changes in terminal without writing to disk
npx tailwind-classname-parser ./src -p ui --dry-run

🛠️ CLI Options Reference

Usage:
  npx tailwind-classname-parser <directory> [options]
  npm run cli -- <directory> [options]

Arguments:
  <directory>            Starting directory to scan for .ts / .tsx / .js / .jsx files
                         (default: "./src")

Options:
  -p, --prefix <string>  Prefix to prepend to Tailwind utilities (default: "tw")
  -e, --exclude <list>   Comma-separated list of classes to exclude (e.g. "container,prose")
  -d, --dry-run          Preview changes without saving to disk
  -q, --quiet            Suppress detailed replacement logs
  -h, --help             Show help documentation

🔌 Vite Plugin Usage (dev & build)

If you prefer to keep your source files on disk clean and let Vite handle transformations in memory:

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";
import { tailwindPrefixVitePlugin } from "tailwind-classname-parser";

export default defineConfig({
  plugins: [
    tailwindPrefixVitePlugin({
      prefix: "ui",
      verbose: true,
    }),
    react(),
    tailwindcss(),
  ],
});

📦 Programmatic Usage (Node.js API)

import { transformClassNames, createTailwindV4PrefixTransform } from "tailwind-classname-parser";

async function run() {
  const replacements = await transformClassNames({
    rootDir: "./src",
    transform: createTailwindV4PrefixTransform({
      prefix: "ui",
      exclude: ["container", "prose"],
    }),
    save: true,     // Writes changes to disk
    verbose: true,
  });

  console.log(`Transformed ${replacements.length} class names.`);
}

run();

Running Tests

npm test