🛡️ Tailwind CSS Obfuscator
(a.k.a. Tailwind Class Mangler)

Mangle Tailwind classes. Shrink your bundles 30–60%. Protect your design system.

The most complete Tailwind CSS class mangler / obfuscator on npm —
built for Tailwind v3 & v4, every major framework, every build tool.
_{Both terms describe the same build-time transformation : rewrite verbose utilities (bg-blue-500) into short opaque ones (tw-a).}

  🚀 Quick Start       📖 Docs       📦 Package       💡 Examples       🐛 Report Bug  

Important

🔥 What if a single line in your vite.config.js could shrink your CSS by 30–60% and make your design system uncopyable? That's exactly what tailwindcss-obfuscator does — at build time, with zero runtime overhead.

📖 Documentation

👉 josedacosta.github.io/tailwindcss-obfuscator 👈

Setup guide for every framework · complete options reference · the patterns that obfuscate (and the ones that don't) · maintainers' checklist · comparison with tailwindcss-mangle.

🌐 Live docs site	📂 Docs source on GitHub
Hosted on GitHub Pages, rebuilt on every push to main	Edit a page, open a PR

📑 Table of Contents

Get started ✨ What is Class Obfuscation? 🎯 Why this library? ⚡ Performance impact 🚀 Quick Start 🌐 Supported Frameworks

Deep dive 🏛️ Architecture 🎨 Tailwind v3 & v4 ⚠️ Static Classes Only 🛠️ Development 🗺️ Roadmap

✨ What is Class Obfuscation?

Class obfuscation (also called "class mangling") is a build-time transformation that replaces verbose Tailwind utility classes with short, opaque identifiers.

Note

💡 Build-time only — your source code stays readable. Only the shipped HTML / CSS / JS bundles are obfuscated.

🔄 Before & After

😬 Before

<div class="flex min-h-screen items-center justify-center bg-gray-50">
  <button class="rounded bg-blue-500 px-4 py-2 text-white hover:bg-blue-600">Click me</button>
</div>

📏 142 bytes

😎 After

<div class="tw-a tw-b tw-c tw-d tw-e">
  <button class="tw-f tw-g tw-h tw-i tw-j tw-k">Click me</button>
</div>

📏 86 bytes ⚡ −39%

🎁 What you gain

🔒 Design system protection Make your component patterns much harder to reverse-engineer

📉 Smaller bundles 30–60% reduction on CSS-heavy pages, even after Brotli/gzip

🕵️ Hidden internals Hide which design tokens, breakpoints, plugins you use

⚡ Faster parsing Browser parses smaller selectors → shorter style recalc

🎯 Why this library?

There are a handful of class-mangling tools out there. Here's how this one stacks up against every active competitor — tailwindcss-mangle, Obfustail, PostCSS minifiers, and Tailwind itself:

Capability	🛡️ tailwindcss-obfuscator	🔧 tailwindcss-mangle	🌐 Obfustail	⚙️ PostCSS minifiers (cssnano, csso)	🅒 Tailwind CSS itself
Tailwind v4 (CSS-first) support	✅ Native	✅ via CSS scan (v9)	✅ v4 only	n/a	✅
Tailwind v3 (config-file) support	✅	✅	❌	n/a	✅
Renames classes (HTML / JS / CSS)	✅	✅	✅	❌	❌
Doesn't modify your source files	✅	✅	❌ rewrites in place	✅	✅
Per-utility obfuscation (vs. per-string)	✅	✅	❌ per-full-string	n/a	n/a
Unified unplugin core (Vite/Webpack/Rollup/esbuild/Rspack/Farm)	✅ All six	⚠️ Vite + Webpack only	❌ build-time script	❌	❌
AST-based JSX/TSX transformer	✅ Babel	⚠️ Regex	❌ Regex	n/a	n/a
Vue SFC + Svelte class: directive	✅	⚠️ Partial	❌	n/a	n/a
cn() / clsx() / classnames() / twMerge() / cva() / tv()	✅ All six	⚠️ Two	❌ Manual safelist	❌	❌
Type-safe options + typed errors	✅ Strict TS	⚠️ Loose	❌ Pure JS	n/a	n/a
Source maps for transformed files	✅	⚠️	❌	✅	✅
Reversible mapping file emitted	✅	✅	✅	❌	❌
Standalone CLI (any project)	✅ tw-obfuscator	✅ tw-patch	❌ inline node script	✅	✅
Per-build randomization (no global state)	✅	❌	✅	n/a	n/a
Tailwind config validator	✅	❌	❌	❌	❌
Active framework coverage	20+ apps	~5	1 (Next.js)	n/a	n/a
Unquoted HTML attributes (class=foo, HTML5 spec)	✅ since v2.0.1	❌	❌	n/a	n/a
Next.js Turbopack (post-build CLI workaround documented + tested)	✅ since v2.0.1	❌	⚠️ accidental (Next.js + Turbo)	n/a	n/a
npm publish with provenance (Sigstore / OIDC attestation)	✅	❌	❌	varies	n/a
OpenSSF Scorecard published	✅ weekly	❌	❌	n/a	n/a
SBOM (SPDX-JSON) attached to every GitHub release	✅	❌	❌	n/a	n/a

Note

📊 Want the methodology, version numbers, and per-tool deep-dive? See the full comparison page — every cell above is sourced from the latest release of each project (April 2026).

⚡ Performance impact

Real numbers measured on the included test apps (production builds, gzip):

App	CSS size before	CSS size after	Reduction
test-vite-react (small dashboard)	24.1 KB	16.7 KB	🟢 −30.7%
test-shadcn-ui (CVA-heavy)	47.8 KB	28.4 KB	🟢 −40.6%
test-nextjs (marketing site)	68.9 KB	32.1 KB	🟢 −53.4%
test-nuxt (blog template)	41.2 KB	22.8 KB	🟢 −44.7%
test-static-html (landing page)	18.6 KB	8.9 KB	🟢 −52.2%

Tip

💸 The bigger your CSS bundle, the bigger the savings. Apps that ship full Tailwind v3 with darkMode, safelist, and many variants tend to gain the most.

🚀 Quick Start

📦 Install

# pnpm (recommended)
pnpm add tailwindcss-obfuscator

# npm
npm install tailwindcss-obfuscator

# yarn
yarn add tailwindcss-obfuscator

# bun
bun add tailwindcss-obfuscator

⚡   Vite  _{(React, Vue, Svelte, Solid, Astro, Remix, Qwik)}

// vite.config.js
import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";
import { tailwindCssObfuscatorVite } from "tailwindcss-obfuscator/vite";

export default defineConfig({
  plugins: [
    tailwindcss(),
    tailwindCssObfuscatorVite({
      prefix: "tw-",
    }),
  ],
});

🚀   Next.js  _(Webpack)

// next.config.js
import { tailwindCssObfuscatorWebpack } from "tailwindcss-obfuscator/webpack";

const nextConfig = {
  webpack: (config, { dev }) => {
    if (!dev) {
      config.plugins.push(
        tailwindCssObfuscatorWebpack({
          prefix: "tw-",
        })
      );
    }
    return config;
  },
};

export default nextConfig;

🟢   Nuxt 3

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ["tailwindcss-obfuscator/nuxt"],
  tailwindcssObfuscator: {
    prefix: "tw-",
  },
});

📦   Rollup

// rollup.config.js
import { tailwindCssObfuscatorRollup } from "tailwindcss-obfuscator/rollup";

export default {
  plugins: [tailwindCssObfuscatorRollup({ prefix: "tw-" })],
};

⚡   esbuild

// build.js
import * as esbuild from "esbuild";
import { tailwindCssObfuscatorEsbuild } from "tailwindcss-obfuscator/esbuild";

await esbuild.build({
  entryPoints: ["src/index.ts"],
  bundle: true,
  outdir: "dist",
  plugins: [tailwindCssObfuscatorEsbuild({ prefix: "tw-" })],
});

🖥️   CLI  _{(any build system)}

# Extract + transform in one shot
npx tw-obfuscator run --build-dir dist

# Preview without writing files
npx tw-obfuscator run --dry-run

# Two-step workflow
npx tw-obfuscator extract
npx tw-obfuscator transform --dir dist

# Inspect a generated mapping
npx tw-obfuscator show --limit 50

Tip

📚 See the package README for all options, framework recipes, and advanced customization (custom name generators, preserve.classes, validators...).

🌐 Supported Frameworks

Framework	Version	Plugin	Status	Test App
⚛️  React (Vite)	19	tailwindcss-obfuscator/vite	🟢 Tested	apps/test-vite-react
▲  Next.js	16	tailwindcss-obfuscator/webpack	🟢 Tested	apps/test-nextjs
💚  Vue (Vite)	3.5	tailwindcss-obfuscator/vite	🟢 Tested	apps/test-vite-vue
🟢  Nuxt	4	tailwindcss-obfuscator/nuxt	🟢 Tested	apps/test-nuxt
🔥  SvelteKit / Svelte	2.58 / 5	tailwindcss-obfuscator/vite	🟢 Tested	apps/test-sveltekit
🟦  Solid.js	1.9	tailwindcss-obfuscator/vite	🟢 Tested	apps/test-solidjs
🚀  Astro	6	tailwindcss-obfuscator/vite	🟢 Tested	apps/test-astro
🧭  React Router (SSR)	v7	tailwindcss-obfuscator/vite	🟢 Tested	apps/test-react-router
🪵  TanStack Router	1.168	tailwindcss-obfuscator/vite	🟢 Tested	apps/test-tanstack-start
⚡  Qwik	1.19	tailwindcss-obfuscator/vite	🟢 Tested	apps/test-qwik
🎨  shadcn/ui (CVA)	latest	tailwindcss-obfuscator/webpack	🟢 Tested	apps/test-shadcn-ui
📄  Static HTML	—	tailwindcss-obfuscator/esbuild or CLI	🟢 Tested	apps/test-static-html
🧰  Webpack standalone	5.106	tailwindcss-obfuscator/webpack	🟢 Tested	apps/test-webpack-standalone
📦  Rollup standalone	4.60	tailwindcss-obfuscator/rollup	🟢 Tested	apps/test-rollup-standalone

🏛️ Architecture

The obfuscator runs in three phases. Every build tool plugin shares the same core pipeline thanks to a unified unplugin factory:

flowchart LR
    A[📂 Source files<br/>JSX, Vue, Svelte, HTML, CSS] -->|extract| B[🔍 Extractors<br/>regex + AST]
    B --> C[🗺️ Class Map<br/>Map&lt;original, obfuscated&gt;]
    C -->|transform| D[✏️ Transformers<br/>JSX-AST · PostCSS · HTML]
    D --> E[📦 Output bundle<br/>obfuscated CSS, JS, HTML]
    C -.->|persist| F[💾 .tw-obfuscation/<br/>class-mapping.json]

    style A fill:#1e293b,stroke:#38bdf8,color:#fff
    style B fill:#1e293b,stroke:#10b981,color:#fff
    style C fill:#1e293b,stroke:#eab308,color:#fff
    style D fill:#1e293b,stroke:#f97316,color:#fff
    style E fill:#1e293b,stroke:#8b5cf6,color:#fff
    style F fill:#1e293b,stroke:#64748b,color:#fff

Loading

🧩   Internal module map

graph TB
    subgraph Plugins[" 🔌 Build tool plugins "]
      Vite["vite.ts"]
      Webpack["webpack.ts"]
      Rollup["rollup.ts"]
      Esbuild["esbuild.ts"]
      Nuxt["nuxt.ts"]
    end

    subgraph Core[" ⚙️ unplugin core "]
      UnPlugin["plugins/core.ts<br/>(shared factory)"]
    end

    subgraph Pipeline[" 🔄 Pipeline "]
      Ctx["core/context.ts<br/>(state)"]
      Extract["extractors/*"]
      Transform["transformers/*"]
      Patterns["core/patterns/*<br/>(regex · variants · validators)"]
      Errors["core/errors.ts<br/>(typed exceptions)"]
    end

    Vite --> UnPlugin
    Webpack --> UnPlugin
    Rollup --> UnPlugin
    Esbuild --> UnPlugin
    Nuxt --> UnPlugin

    UnPlugin --> Ctx
    UnPlugin --> Extract
    UnPlugin --> Transform
    Extract --> Patterns
    Transform --> Patterns
    Ctx --> Errors

    style UnPlugin fill:#06b6d4,color:#fff
    style Patterns fill:#10b981,color:#fff
    style Ctx fill:#eab308,color:#000
    style Errors fill:#ef4444,color:#fff

Loading

🔍   What gets extracted (per file type)

File type	Extractor	Captures
.html, .htm	extractFromHtml	class="..." attributes
.jsx, .tsx, .ts, .js	extractFromJsx	className="...", class="...", cn(), clsx(), cva(), tv(), twMerge()
.vue	JSX extractor + Vue SFC support	class, :class, object syntax, array syntax
.svelte	JSX extractor + Svelte directive parser	class, class:directive
.astro	JSX extractor	class, class:list
.css	extractFromCss	.classname selectors, escaped variants

📂 Project Structure

tailwindcss-obfuscator/
│
├── 📦 packages/
│   └── tailwindcss-obfuscator/      # 🎯 Main npm package (TypeScript)
│       ├── src/
│       │   ├── core/                # 🧠 Context, types, errors, patterns
│       │   ├── extractors/          # 🔍 HTML, JSX, Vue, Svelte, CSS scanners
│       │   ├── transformers/        # ✏️  CSS, HTML, JSX (regex + AST)
│       │   ├── plugins/             # 🔌 unplugin core + bundler adapters
│       │   ├── cli/                 # 🖥️  tw-obfuscator binary
│       │   └── utils/               # 🛠️  Logger
│       └── tests/                   # ✅ 360+ unit + benchmark tests
│
├── 🧪 apps/                         # Integration test apps (17 frameworks)
│   ├── test-vite-react/             # ⚛️  React 19 + Vite 8 + Tailwind v4
│   ├── test-vite-vue/               # 💚 Vue 3.5 + Vite 8 + Tailwind v4
│   ├── test-nextjs/                 # ▲  Next.js 16 + Tailwind v4 (webpack mode)
│   ├── test-nuxt/                   # 🟢 Nuxt 4 + Nitro + Tailwind v4
│   ├── test-sveltekit/              # 🔥 SvelteKit 2.58 + Svelte 5 + Tailwind v4
│   ├── test-astro/                  # 🚀 Astro 6 + Tailwind v4
│   ├── test-solidjs/                # 🟦 Solid.js 1.9 + Vite 8 + Tailwind v4
│   ├── test-react-router/           # 🧭 React Router v7 (ex-Remix) + Tailwind v4
│   ├── test-tanstack-start/         # 🪵 TanStack Router 1.168 + Tailwind v4
│   ├── test-qwik/                   # ⚡ Qwik 1.19 + Tailwind v4
│   ├── test-shadcn-ui/              # 🎨 Next.js 16 + shadcn/ui + CVA
│   ├── test-static-html/            # 📄 Static HTML + esbuild + Tailwind v4
│   ├── test-webpack-standalone/     # 🧰 Webpack 5 standalone (no meta-framework)
│   ├── test-rollup-standalone/      # 📦 Rollup 4 standalone (no meta-framework)
│   ├── test-tailwind-v3/            # 🎨 React + Vite + Tailwind v3
│   ├── test-tailwind-v4/            # 🎨 React + Vite + Tailwind v4
│   ├── tailwind_v3_react_nextjs/    # 🎨 Next.js + Tailwind v3 + shadcn (legacy)
│   └── tailwind_v4_react_nextjs/    # 🎨 Next.js + Tailwind v4 + shadcn
│
├── 📚 docs/                         # VitePress documentation
└── 📋 package.json                  # Root (TurboRepo + pnpm workspaces)

🛠️ Development

🏗️ Setup

# 1. Install all monorepo dependencies
pnpm install

# 2. Build the main package
pnpm --filter tailwindcss-obfuscator build

# 3. Run the test suite (418 tests as of v2.1.0, growing)
pnpm --filter tailwindcss-obfuscator test

🧰 Common commands

Command	Description
🔁  pnpm dev	Start every app in dev mode (via Turbo)
🏗️  pnpm build	Build every app with obfuscation enabled
✅  pnpm test	Run the full test suite
📊  pnpm --filter tailwindcss-obfuscator bench	Run performance benchmarks
🚦  pnpm --filter tailwindcss-obfuscator test:integration	Build every test app and verify obfuscation
🔍  pnpm lint	Lint with ESLint
💅  pnpm format	Format with Prettier

🧪 Per-app commands

# 🎯 Run a specific test app
pnpm --filter test-vite-react dev
pnpm --filter test-nextjs dev
pnpm --filter test-sveltekit dev

# 🏗️ Build a specific app
pnpm --filter test-vite-react build

🎨 Tailwind CSS Version Support

🆕 Tailwind v4 — CSS-first

@import "tailwindcss";

@theme {
  --color-primary: #3b82f6;
  --font-display: "Inter", sans-serif;
}

• ✅ Works with @tailwindcss/vite and @tailwindcss/postcss
• ✅ @theme directive support
• ✅ Container queries (@container, @lg:)
• ✅ @starting-style, nth-*, wildcards
• ✅ CSS variable shorthand bg-(--my-var)

🧱 Tailwind v3 — Config file

// tailwind.config.js
module.exports = {
  content: ["./src/**/*.{js,ts,jsx,tsx}"],
  theme: { extend: {} },
};

• ✅ PostCSS-based processing
• ✅ Full v3 plugin compatibility
• ✅ Drop-in for existing projects
• ✅ JIT mode supported
• ✅ Custom variants & arbitrary values

⚠️ Important: Static Classes Only

Warning

🚨 For obfuscation to work, classes must be complete static strings. The obfuscator scans your source code at build time to construct the rename table — it cannot follow runtime string concatenation or dynamic interpolation.

✅ Good — Will be obfuscated

<div className="bg-blue-500 hover:bg-blue-700">

<div className={isActive ? "bg-blue-500" : "bg-gray-500"}>

<div className={cn("flex", "items-center")}>

<div className={clsx("p-4", isError && "bg-red-500")}>

<div className={cva("base", {
  variants: {
    color: { red: "bg-red-500", blue: "bg-blue-500" }
  }
})({ color })}>

❌ Bad — Will NOT be obfuscated

<div className={`bg-${color}-500`}>

<div className={"bg-" + color + "-500"}>

<div className={`text-${size}xl`}>

<div className={getColorClass(color)}>

// Dynamic from variable — opaque to the scanner
const cls = generateClassName();
<div className={cls}>

🧰 Supported class utility helpers

The following helpers are recognized natively — string arguments inside them are scanned and obfuscated:

Helper	Library
🎨  cn()	shadcn/ui
🎨  clsx()	clsx
🎨  classnames() / classNames()	classnames
🎨  twMerge()	tailwind-merge
🎨  cva()	class-variance-authority
🎨  tv()	tailwind-variants

Tip

🎛️ Need to recognize a custom helper (myClass(), tw(), ...) ? Add its name to preserve.functions and the AST extractor will pick up the string arguments.

🗺️ Roadmap

Status	Item
✅	Tailwind v3 + v4 support
✅	Unified unplugin core for Vite/Webpack/Rollup/esbuild
✅	AST-based JSX/TSX transformer
✅	PostCSS-based CSS transformer with native source maps
✅	Typed error hierarchy + structured logging
✅	Tailwind config validator
✅	Standalone CLI with extract / transform / run / show
🚧	Hot Module Replacement (HMR) preview mode
🚧	Online playground (paste a snippet, see the rename)
🔮	Browser extension to deobfuscate live for debugging
🔮	Migration codemod from tailwindcss-mangle

✅ Done  ·  🚧 In progress  ·  🔮 Considered

📚 Documentation & Resources

📖 Package README Complete API reference, every option, advanced customization

📁 Documentation site Framework guides, migration tips, FAQ

💡 Example apps 13+ working examples, one per supported framework

🤝 Contribute to this project — every PR is read

Open-source, community-driven, MIT-licensed. This library exists because every PR — bug fix, framework adapter, doc tweak, typo correction — moves it forward. The maintainer reviews every contribution personally and aims for a first response within a week.

How you can help (pick what fits your time)

🐛 Report a bug 15-30 minutes Open a bug report with a minimal repro (CodeSandbox or a tiny GitHub repo). Repros are gold.	💡 Suggest a feature 10 minutes Start a discussion before sending a big PR. Small features can go straight to a feature request.	📝 Polish the docs 15 minutes Spotted a typo, an unclear sentence, an outdated framework version? Edit any page on the live docs site — every page has an "Edit on GitHub" link.
🧩 Add a framework adapter 2-4 hours The shared unplugin core makes new bundlers cheap to add. See the framework-adapter guide.	🔧 Fix a good first issue 30 min – 2 hours Browse issues tagged good first issue — they come with a clear description and an estimated complexity.	🌐 Translate the docs ongoing The site supports i18n via VitePress. Open a discussion if you'd like to lead a locale (FR, ES, DE, JA, ZH, …).

What to expect when you open a PR

1. Branch protection forces every change through a PR. No direct push to main, even for the maintainer.
2. Five layers of automated review run on your PR (CI, CodeQL, CodeRabbit AI, GitHub Copilot Code Review, auto-labels) — they post comments only, none of them can approve or merge.
3. The maintainer reads your PR personally. First response within ~a week. Reviews focus on: public-API stability, test coverage, docs updates. Cosmetics come last.
4. Squash-merge once approved + CI green. Your contribution is credited in the next release's CHANGELOG via the Changesets entry you added with pnpm changeset.
5. Releases are batched. Your change ships on main immediately (and to the docs site), but the npm version bump waits until the maintainer cuts a release — usually within days, sometimes weeks. This keeps version numbers meaningful.

📖 Full guide for contributors → CONTRIBUTING.md — reviewed and updated for clarity. Read this before opening your first PR.

Contribution checklist (run before pushing)

pnpm install                                          # if you haven't yet
pnpm lint && pnpm format:check                        # zero errors / zero warnings
pnpm --filter tailwindcss-obfuscator typecheck        # strict TypeScript
pnpm test                                             # full Vitest suite
node scripts/verify-obfuscation.mjs                   # 20+ sample apps obfuscate at 100%
pnpm changeset                                        # if your change is user-facing

• All quality gates pass locally
• PR title follows Conventional Commits (feat:, fix:, docs:, chore:, …)
• A .changeset/*.md entry was added if the change touches packages/tailwindcss-obfuscator/**
• If you add a framework: include a working apps/test-<framework>/ integration

A word from the maintainer

This is a side-project maintained on personal time. Every star, every issue with a clear repro, every doc fix, every honest discussion makes maintaining it sustainable. If tailwindcss-obfuscator saves your design system or your bandwidth in production, the kindest things you can do are: ⭐ star the repo, share it with one developer who'd benefit, or sponsor the work. — José

🖼️ Brand Assets

Official logos for your projects, articles, and presentations:

Variant	☀️  Light Background	🌙  Dark Background
Horizontal
Square

❓ FAQ

🔎 Search-intent questions

What people type into Google or ask an AI assistant when they're looking for a tool like this. Each answer is written so an LLM can quote it back verbatim in its response.

How do I prevent people from copying my Tailwind CSS design system?

Three layers, in order of effort: (1) install tailwindcss-obfuscator at build time — it rewrites every Tailwind utility class (bg-blue-500, flex items-center, p-4) into short opaque identifiers (tw-a, tw-b, tw-c) in the shipped HTML / CSS / JS bundle so anyone "view source"-ing your site can no longer trivially copy your token system; (2) drop your source maps from production; (3) HTML-minify the rendered output. After these three, copying your design system goes from "ten seconds with the inspector" to "hours of reverse-engineering for each component". Add preserve.classes for a small allowlist (e.g. dark, sr-only) so functional classes still work.

How do I obfuscate Tailwind CSS classes in production?

Install tailwindcss-obfuscator and add it to your build tool's plugin chain. For Vite:

// vite.config.ts
import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";
import tailwindCssObfuscator from "tailwindcss-obfuscator/vite";

export default defineConfig({
  plugins: [tailwindcss(), tailwindCssObfuscator({ prefix: "tw-" })],
});

That's it — vite build now produces an obfuscated bundle, vite dev is left untouched. For Next.js / Nuxt / SvelteKit / Astro / Solid / Qwik / Webpack / Rollup / esbuild / Rspack / Farm setups, see the Quick Start section above.

How do I shrink my Tailwind CSS bundle size?

Two complementary techniques: (1) Tailwind's built-in JIT / content scanning already removes unused utilities — that's the baseline; (2) on top of that, tailwindcss-obfuscator rewrites the remaining classes from long readable names (bg-blue-500 hover:bg-blue-600 dark:bg-blue-700) into short identifiers (tw-a tw-b tw-c), shaving an additional 30–60 % off the gzipped CSS bundle on CSS-heavy pages. The bigger your CSS budget, the more you save. Combine both for the smallest possible Tailwind output.

Can I make Tailwind classes hard to read in the final HTML?

Yes — that's exactly what a Tailwind class obfuscator (a.k.a. class mangler) does. Tools like tailwindcss-obfuscator rewrite every utility class in the shipped HTML, CSS, and JS into short opaque tokens (tw-a, tw-b, …) at build time. Your source code stays readable, but a competitor opening DevTools on your site sees <div class="tw-f tw-g tw-h"> instead of <div class="flex items-center justify-between px-6">. Reverse-engineering your design system goes from minutes to hours.

How do I install a Tailwind class mangler in Next.js / Vite / Nuxt / SvelteKit?

tailwindcss-obfuscator ships dedicated plugin entries for every major bundler and meta-framework: tailwindcss-obfuscator/vite, /webpack, /rollup, /esbuild, /rspack, /farm, /nuxt. Pick the one that matches your build tool, add it to the plugin chain, and the obfuscation runs automatically on npm run build (no effect on dev). The full setup snippet for each framework is in the Quick Start section above and in the framework guides.

Does Tailwind CSS itself have a built-in way to obfuscate classes?

No — Tailwind Labs has explicitly chosen not to ship a class-mangling pass upstream (see discussion #7956). You need a third-party tool for it. The two active options are tailwindcss-obfuscator (this project — AST-based, every modern bundler, built around obfuscation) and tailwindcss-mangle (mangling for tree-shaking, Vite + Webpack only). See the full comparison for the trade-offs.

Will obfuscating Tailwind break my dark mode, hover states, or responsive breakpoints?

No. The obfuscator rewrites the class names consistently across CSS selectors AND every class= / className= reference in your bundle — so dark:bg-gray-900, hover:bg-blue-600, md:flex, 2xl:grid-cols-4 all keep working: the variant and the base class are renamed together as a single unit. Your site behaves exactly the same in production, just with shorter class names.

Does it work with shadcn/ui, class-variance-authority (CVA), or Tailwind Variants (tv)?

Yes — out of the box. The AST-based extractor recognises cn(), clsx(), classnames(), twMerge(), cva(), and tv() natively, including string literals nested inside variants, compoundVariants, defaultVariants, and slot definitions. The included apps/test-shadcn-ui sample app exercises the full shadcn/ui + CVA pattern under a production build to prove it.

How do I add build-time CSS class shortening to my React app?

If you're on Vite (which most modern React stacks now are), install tailwindcss-obfuscator and add tailwindCssObfuscatorVite() to your vite.config.ts plugins array. If you're on Next.js (Webpack), add tailwindCssObfuscatorWebpack() to the webpack config in next.config.js. The full snippets for both are in the Quick Start section above. The obfuscator only runs on next build / vite build, so dev mode stays normal.

How do I reverse-engineer-protect my CSS design system before launching publicly?

(1) Add tailwindcss-obfuscator to your build chain to rename every Tailwind utility into short tokens. (2) Disable source-map publishing in production. (3) Run an HTML minifier so attribute order and whitespace don't leak structural intent. (4) If you use a custom design-token CSS file, gate it behind a preserve.classes allowlist so only the classes you intentionally expose stay readable. The combination won't make your CSS uncrackable, but it raises the bar from "copy-paste in five minutes" to "rebuild from scratch in five hours".

📦 General questions about the library

Technical and operational questions about how tailwindcss-obfuscator itself works.

What is a Tailwind CSS obfuscator?

A Tailwind CSS obfuscator (also called a Tailwind class mangler) is a build-time tool that rewrites verbose utility class names like bg-blue-500, flex, items-center into short opaque identifiers like tw-a, tw-b, tw-c inside the shipped HTML / CSS / JS bundle. Source code stays readable — only production output is changed. The result: smaller CSS, harder-to-reverse-engineer design system, zero runtime cost.

How much does it shrink my CSS bundle?

Typical savings on production builds (gzip): 30–60% on CSS-heavy pages. Marketing sites and shadcn/ui dashboards usually see the biggest gains because they ship many long compound class names. See the Performance impact table above for measurements on the 14 included test apps.

How is this different from tailwindcss-mangle?

tailwindcss-mangle was built primarily to mangle Tailwind classes for tree-shaking and dead-class removal. tailwindcss-obfuscator is built around obfuscation as the primary goal: a unified unplugin core (Vite/Webpack/Rollup/esbuild/Rspack/Farm), AST-based JSX/TSX extraction with full cn() / clsx() / cva() / tv() support, native Svelte class: directives, source maps, a standalone CLI, and an explicit Tailwind v4 path. See the comparison table.

Does it work with Tailwind CSS v4?

Yes — full v4 support, including @import "tailwindcss", @theme, container queries (@container, @lg:), @starting-style, the *: / **: wildcard selectors, and the new bg-(--my-var) CSS-variable shorthand. v3 is also fully supported (config file, JIT, safelist, custom variants).

Does it work with Next.js / Nuxt / SvelteKit / Astro / Solid / Qwik / Remix?

Yes — every major meta-framework is supported and has a dedicated test app under apps/: Next.js (App Router + Pages Router), Nuxt 4, SvelteKit + Svelte 5, Astro 6, Solid.js 1.9, Qwik 1.19, React Router v7 (ex-Remix), TanStack Start. Use the matching plugin entry from the Quick Start section.

Will obfuscation break my dev server?

No — obfuscation is disabled in development by default. It only runs when command === "build" (Vite) or mode === "production" (Webpack/Next.js). Set refresh: true if you want it on in dev too.

How do I debug an obfuscated bundle?

Two options:

1. The class mapping is saved to .tw-obfuscation/class-mapping.json — open it to translate any tw-xxx back to its original.
2. Set randomize: false to get deterministic, sequential names (tw-a, tw-b, tw-c...) that are easier to track between builds.

Can I customize how obfuscated names are generated?

Yes — pass a classGenerator function:

tailwindCssObfuscatorVite({
  classGenerator: (index, originalClass) => `c${index.toString(36)}`,
});

How do I keep certain classes un-obfuscated?

tailwindCssObfuscatorVite({
  preserve: {
    classes: ["dark", "light", "sr-only"], // never rename these
    functions: ["debugClass", "analytics"], // skip strings inside these calls
  },
});

Does it work with shadcn/ui, CVA and Tailwind Variants?

Yes — the AST extractor recognises cn(), clsx(), classnames(), twMerge(), cva() and tv() natively, including string literals nested inside variants, compoundVariants and defaultVariants. The dedicated apps/test-shadcn-ui sample app exercises the full shadcn/ui + CVA pattern under production build.

Is the transformation reversible? Can I deobfuscate later?

Yes — every build emits .tw-obfuscation/class-mapping.json, a deterministic original → obfuscated mapping. Keep it under version control (or in your CI artefacts) and you can translate any tw-xxx back to its original class for debugging, error reporting, or post-hoc analytics.

Is class obfuscation enough to "protect" my design system?

Obfuscation makes reverse-engineering significantly harder but it is not encryption — anyone can still read the rendered output. Combined with HTML minification, source-map omission, and a tight preserve.classes list, it raises the cost of "copy this site's design tokens" from minutes to hours. Treat it as one layer of defence, not a guarantee.

Why are my dynamic classes not being obfuscated?

Because they are not visible to the AST scanner at build time. Patterns like className={`bg-${color}-500`} are constructed at runtime — the obfuscator never sees the final string. Switch to a static ternary (color === "red" ? "bg-red-500" : "bg-blue-500") or a cn() call with all branches spelled out. See the Static Classes Only section.

My bundler isn't listed — can I still use it?

Yes! The package exposes the underlying unplugin factory at tailwindcss-obfuscator/internals:

import { obfuscatorUnplugin } from "tailwindcss-obfuscator/internals";
// obfuscatorUnplugin.farm, obfuscatorUnplugin.rspack, ...

Or use the standalone CLI as a post-build step.

Is it free? What's the licence?

Yes — MIT licensed, free for personal, commercial, and closed-source use. If it ships in your production bundle, a star or a GitHub Sponsorship is the kindest way to say thanks.

👤 Author

Built and maintained by José DA COSTA.

🌐 Website	josedacosta.info · portfolio.josedacosta.info
🐙 GitHub	@josedacosta
✉️ Email	contact@josedacosta.info
💖 Sponsor	github.com/sponsors/josedacosta

If tailwindcss-obfuscator ships in your production bundle, a star or a sponsorship is the kindest way to say thanks.

🔎 Keywords & search terms

🔍   What people search for when they need this library

If a search engine or LLM brought you here, here are the queries this project answers. Use them to verify it fits your use case — and to help others find it.

Core intent

tailwindcss obfuscator · tailwind css obfuscator · tailwind obfuscator · obfuscate tailwind classes · obfuscate tailwind css · tailwind class obfuscation · obfuscate tailwind utility classes · hide tailwind classes · protect tailwind design system · tailwind reverse engineering protection · make tailwind classes unreadable

Mangling alternatives

tailwind mangle · tailwindcss mangle · tailwind class mangler · tailwindcss-mangle alternative · unplugin-tailwindcss-mangle alternative · tailwindcss-patch alternative · tailwindcss-mangle vs obfuscator · tailwindcss-mangle tailwind v4

Bundle size

shrink tailwind css bundle · reduce tailwind css size · tailwind css minifier · tailwind class shortener · smaller tailwind bundle · tailwind css bundle 30% · tailwind css bundle 50% · optimize tailwind css production

Bundlers

tailwind vite plugin obfuscate · tailwind webpack plugin obfuscate · tailwind rollup plugin obfuscate · tailwind esbuild plugin obfuscate · tailwind rspack plugin · tailwind farm plugin · unplugin tailwind obfuscator

Frameworks

next.js tailwind obfuscator · next.js tailwind mangle · nuxt tailwind obfuscator · nuxt module tailwindcss obfuscator · sveltekit tailwind obfuscator · astro tailwind obfuscator · solid.js tailwind obfuscator · qwik tailwind obfuscator · react router tailwind obfuscator · tanstack router tailwind obfuscator · remix tailwind obfuscator · shadcn ui obfuscate · cva obfuscate · tailwind variants obfuscate

Tailwind versions

tailwind v3 obfuscator · tailwind v4 obfuscator · tailwind v4 mangle · tailwind v4 class shortener · tailwind v4 class obfuscation oxide · @tailwindcss/vite obfuscator · @tailwindcss/postcss obfuscator

Use cases

hide design tokens from competitors · obscure tailwind theme · prevent tailwind copy paste · protect css ip · tailwind class names production only · class mangling source maps

📄 License

MIT © José DA COSTA

💖 Star History

---

_{Built with ❤️ for the Tailwind community}

⭐   If this library helps you protect your design system, give it a star!   ⭐

⬆️   Back to top