https://github.com/josedacosta/tailwindcss-obfuscator
Tailwind CSS class obfuscation for Vite, Webpack, Rollup, esbuild, Next.js, Nuxt, SvelteKit, Astro, Remix / React Router 7, Solid, Qwik, Vue & TanStack Router — supports Tailwind v3 + v4. Shrinks bundles, protects your design system.
https://github.com/josedacosta/tailwindcss-obfuscator
astro css esbuild mangle minify nextjs nuxt obfuscator qwik react-router rollup solidjs sveltekit tailwind tailwindcss tanstack-router typescript vite vue webpack
Last synced: 16 days ago
JSON representation
Tailwind CSS class obfuscation for Vite, Webpack, Rollup, esbuild, Next.js, Nuxt, SvelteKit, Astro, Remix / React Router 7, Solid, Qwik, Vue & TanStack Router — supports Tailwind v3 + v4. Shrinks bundles, protects your design system.
- Host: GitHub
- URL: https://github.com/josedacosta/tailwindcss-obfuscator
- Owner: josedacosta
- License: mit
- Created: 2026-04-28T14:34:55.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-01T23:01:32.000Z (24 days ago)
- Last Synced: 2026-06-02T00:23:45.364Z (24 days ago)
- Topics: astro, css, esbuild, mangle, minify, nextjs, nuxt, obfuscator, qwik, react-router, rollup, solidjs, sveltekit, tailwind, tailwindcss, tanstack-router, typescript, vite, vue, webpack
- Language: TypeScript
- Homepage: https://github.com/josedacosta/tailwindcss-obfuscator#readme
- Size: 1.43 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 26
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Maintainers: docs/maintainers.md
Awesome Lists containing this project
README
🛡️ 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**](https://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**](https://josedacosta.github.io/tailwindcss-obfuscator/) | 📂 [Docs source on GitHub](./docs/) |
| ------------------------------------------------------------------------------ | ----------------------------------- |
| 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?](#-what-is-class-obfuscation)
- [🎯 Why this library?](#-why-this-library)
- [⚡ Performance impact](#-performance-impact)
- [🚀 Quick Start](#-quick-start)
- [🌐 Supported Frameworks](#-supported-frameworks)
**Deep dive**
- [🏛️ Architecture](#️-architecture)
- [🎨 Tailwind v3 & v4](#-tailwind-css-version-support)
- [⚠️ Static Classes Only](#️-important-static-classes-only)
- [🛠️ Development](#️-development)
- [🗺️ Roadmap](#️-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
```html
Click me
```
📏 **142 bytes**
#### 😎 After
```html
Click me
```
📏 **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](https://github.com/sonofmagic/tailwindcss-mangle) | 🌐 [Obfustail](https://github.com/ui-layouts/Obfuscated-tailwindcss) | ⚙️ PostCSS minifiers ([cssnano](https://github.com/cssnano/cssnano), [csso](https://github.com/css/csso)) | 🅒 [Tailwind CSS](https://github.com/tailwindlabs/tailwindcss) 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](https://josedacosta.github.io/tailwindcss-obfuscator/research/comparison) — 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
```bash
# 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)
```javascript
// 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)
```javascript
// 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
```javascript
// nuxt.config.ts
export default defineNuxtConfig({
modules: ["tailwindcss-obfuscator/nuxt"],
tailwindcssObfuscator: {
prefix: "tw-",
},
});
```
📦 Rollup
```javascript
// rollup.config.js
import { tailwindCssObfuscatorRollup } from "tailwindcss-obfuscator/rollup";
export default {
plugins: [tailwindCssObfuscatorRollup({ prefix: "tw-" })],
};
```
⚡ esbuild
```javascript
// 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)
```bash
# 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](./packages/tailwindcss-obfuscator/README.md) 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`](./apps/test-vite-react) |
| ▲ **Next.js** | 16 | `tailwindcss-obfuscator/webpack` | 🟢 Tested | [`apps/test-nextjs`](./apps/test-nextjs) |
| 💚 **Vue** (Vite) | 3.5 | `tailwindcss-obfuscator/vite` | 🟢 Tested | [`apps/test-vite-vue`](./apps/test-vite-vue) |
| 🟢 **Nuxt** | 4 | `tailwindcss-obfuscator/nuxt` | 🟢 Tested | [`apps/test-nuxt`](./apps/test-nuxt) |
| 🔥 **SvelteKit / Svelte** | 2.58 / 5 | `tailwindcss-obfuscator/vite` | 🟢 Tested | [`apps/test-sveltekit`](./apps/test-sveltekit) |
| 🟦 **Solid.js** | 1.9 | `tailwindcss-obfuscator/vite` | 🟢 Tested | [`apps/test-solidjs`](./apps/test-solidjs) |
| 🚀 **Astro** | 6 | `tailwindcss-obfuscator/vite` | 🟢 Tested | [`apps/test-astro`](./apps/test-astro) |
| 🧭 **React Router** (SSR) | v7 | `tailwindcss-obfuscator/vite` | 🟢 Tested | [`apps/test-react-router`](./apps/test-react-router) |
| 🪵 **TanStack Router** | 1.168 | `tailwindcss-obfuscator/vite` | 🟢 Tested | [`apps/test-tanstack-start`](./apps/test-tanstack-start) |
| ⚡ **Qwik** | 1.19 | `tailwindcss-obfuscator/vite` | 🟢 Tested | [`apps/test-qwik`](./apps/test-qwik) |
| 🎨 **shadcn/ui** (CVA) | latest | `tailwindcss-obfuscator/webpack` | 🟢 Tested | [`apps/test-shadcn-ui`](./apps/test-shadcn-ui) |
| 📄 **Static HTML** | — | `tailwindcss-obfuscator/esbuild` or CLI | 🟢 Tested | [`apps/test-static-html`](./apps/test-static-html) |
| 🧰 **Webpack** standalone | 5.106 | `tailwindcss-obfuscator/webpack` | 🟢 Tested | [`apps/test-webpack-standalone`](./apps/test-webpack-standalone) |
| 📦 **Rollup** standalone | 4.60 | `tailwindcss-obfuscator/rollup` | 🟢 Tested | [`apps/test-rollup-standalone`](./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`](https://github.com/unjs/unplugin) factory:
```mermaid
flowchart LR
A[📂 Source files
JSX, Vue, Svelte, HTML, CSS] -->|extract| B[🔍 Extractors
regex + AST]
B --> C[🗺️ Class Map
Map<original, obfuscated>]
C -->|transform| D[✏️ Transformers
JSX-AST · PostCSS · HTML]
D --> E[📦 Output bundle
obfuscated CSS, JS, HTML]
C -.->|persist| F[💾 .tw-obfuscation/
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
```
🧩 Internal module map
```mermaid
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
(shared factory)"]
end
subgraph Pipeline[" 🔄 Pipeline "]
Ctx["core/context.ts
(state)"]
Extract["extractors/*"]
Transform["transformers/*"]
Patterns["core/patterns/*
(regex · variants · validators)"]
Errors["core/errors.ts
(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
```
🔍 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
```bash
# 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
```bash
# 🎯 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
```css
@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
```javascript
// 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
```jsx
```
### ❌ Bad — Will NOT be obfuscated
```jsx
// Dynamic from variable — opaque to the scanner
const cls = generateClassName();
```
### 🧰 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](./packages/tailwindcss-obfuscator/README.md)**
Complete API reference, every option, advanced customization
### 📁
**[Documentation site](https://josedacosta.github.io/tailwindcss-obfuscator/)**
Framework guides, migration tips, FAQ
### 💡
**[Example apps](./apps/)**
13+ working examples, one per supported framework
## 🤝 Contribute to this project — every PR is read
[](https://github.com/josedacosta/tailwindcss-obfuscator/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
[](https://github.com/josedacosta/tailwindcss-obfuscator/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)
[](https://github.com/josedacosta/tailwindcss-obfuscator/discussions)
[](https://github.com/josedacosta/tailwindcss-obfuscator/graphs/contributors)
> **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](https://github.com/josedacosta/tailwindcss-obfuscator/issues/new?template=bug_report.yml) with a minimal repro (CodeSandbox or a tiny GitHub repo). Repros are gold.
### 💡
**Suggest a feature**
10 minutes
[Start a discussion](https://github.com/josedacosta/tailwindcss-obfuscator/discussions/new?category=ideas) before sending a big PR. Small features can go straight to a [feature request](https://github.com/josedacosta/tailwindcss-obfuscator/issues/new?template=feature_request.yml).
### 📝
**Polish the docs**
15 minutes
Spotted a typo, an unclear sentence, an outdated framework version? Edit any page on [the live docs site](https://josedacosta.github.io/tailwindcss-obfuscator/) — 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](https://github.com/josedacosta/tailwindcss-obfuscator/blob/main/CONTRIBUTING.md#-adding-a-new-framework-adapter).
### 🔧
**Fix a `good first issue`**
30 min – 2 hours
[Browse issues tagged `good first issue`](https://github.com/josedacosta/tailwindcss-obfuscator/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — 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`](./CONTRIBUTING.md)** — reviewed and updated for clarity. Read this before opening your first PR.
Contribution checklist (run before pushing)
```bash
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](https://www.conventionalcommits.org/) (`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-/` 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](https://github.com/sponsors/josedacosta) 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:
```ts
// 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](#-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 `
` instead of ``. 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](#-quick-start) section above and in the [framework guides](https://josedacosta.github.io/tailwindcss-obfuscator/guide/getting-started).
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](https://github.com/tailwindlabs/tailwindcss/discussions/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](https://josedacosta.github.io/tailwindcss-obfuscator/research/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](#-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](#-performance-impact) table above for measurements on the 14 included test apps.
How is this different from tailwindcss-mangle?
[`tailwindcss-mangle`](https://github.com/sonofmagic/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](#-why-this-library) 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/`](./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](#-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:
```javascript
tailwindCssObfuscatorVite({
classGenerator: (index, originalClass) => `c${index.toString(36)}`,
});
```
How do I keep certain classes un-obfuscated?
```javascript
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`](./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](#️-important-static-classes-only) section.
My bundler isn't listed — can I still use it?
Yes! The package exposes the underlying [`unplugin`](https://github.com/unjs/unplugin) factory at `tailwindcss-obfuscator/internals`:
```javascript
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](https://github.com/sponsors/josedacosta) 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](./LICENSE) © [José DA COSTA](https://github.com/josedacosta)
### 💖 Star History
---
Built with ❤️ for the Tailwind community
⭐ **If this library helps you protect your design system, give it a star!** ⭐