Configuration Options

This page documents every option exposed by tailwindcss-obfuscator.

Core options

`prefix`

Prefix prepended to every obfuscated class name.

Property	Value
Type	`string`
Default	`"tw-"`

TailwindObfuscator({
  prefix: "x-", // bg-blue-500 → x-a8k2
});

TIP

Use a short prefix to keep the bundle small. An empty prefix ("") is allowed but discouraged: it can collide with other classes in the page.

`randomize`

Generate random class names for maximum protection.

Property	Value
Type	`boolean`
Default	`true`

TailwindObfuscator({
  randomize: true, // Different names on every build (recommended)
  randomize: false, // Predictable sequential names (tw-a, tw-b, tw-c…)
});

Comparison:

Mode	Build 1	Build 2	Security
`randomize: true`	`tw-k7x2`	`tw-m9p4`	✅ High
`randomize: false`	`tw-a`	`tw-a`	❌ Low

WARNING

Disabling randomisation makes the obfuscation predictable and therefore easy to reverse.

`randomLength`

Length of the random portion of the generated class name (excluding the prefix).

Property	Value
Type	`number`
Default	`4`

TailwindObfuscator({
  randomLength: 4, // tw-a8k2 (7 chars total)
  randomLength: 6, // tw-a8k2m9 (9 chars total)
});

Combination space:

Length	Combinations	Sufficient for
3	33,696	~500 classes
4	1,213,056	~5,000 classes
5	43,669,816	~50,000 classes

INFO

With randomLength: 4, you have 1.2 million possible combinations — enough for 99.9 % of projects.

`verbose`

Enable verbose logging during the build.

Property	Value
Type	`boolean`
Default	`false`

TailwindObfuscator({
  verbose: true,
});

Sample output:

[tailwindcss-obfuscator] Scanning src/App.tsx...
[tailwindcss-obfuscator] Found 42 classes
[tailwindcss-obfuscator] Transforming styles.css...

`debug`

Enable debug mode with even more detailed logs.

Property	Value
Type	`boolean`
Default	`false`

TailwindObfuscator({
  debug: true,
});

Class filtering

`exclude`

List of classes to exclude from obfuscation. Accepts strings and regular expressions.

Property	Value
Type	`(string \| RegExp)[]`
Default	`[]`

TailwindObfuscator({
  exclude: [
    "dark", // Exclude the exact class "dark"
    "light", // Exclude the exact class "light"
    /^prose/, // Exclude every class starting with "prose"
    /^data-\[/, // Exclude arbitrary data attributes
  ],
});

Common patterns:

Pattern	Matches
`'dark'`	`dark` (dark mode)
`/^prose/`	`prose`, `prose-lg`, `prose-invert`…
`/^animate-/`	`animate-spin`, `animate-pulse`…

`include`

List of classes to include (whitelist). When set, only these classes are obfuscated.

Property	Value
Type	`(string \| RegExp)[]`
Default	`[]` (everything)

TailwindObfuscator({
  include: [
    /^bg-/, // Only bg-* classes
    /^text-/, // Only text-* classes
  ],
});

WARNING

include skips obfuscation for everything else. Use it carefully.

`filter`

Custom predicate that decides whether a class should be obfuscated.

Property	Value
Type	`(className: string) => boolean`
Default	`null`

TailwindObfuscator({
  filter: (className) => {
    // Skip debug-prefixed classes
    if (className.startsWith("debug-")) return false;
    // Skip very short classes
    if (className.length <= 3) return false;
    // Obfuscate everything else
    return true;
  },
});

Source files

`content`

Glob patterns for files scanned to extract classes.

Property	Value
Type	`string[]`
Default	`["*/.{html,jsx,tsx,vue,svelte,astro}"]`

TailwindObfuscator({
  content: ["src/**/*.{js,ts,jsx,tsx}", "components/**/*.vue", "pages/**/*.astro"],
});

`css`

Glob patterns for the CSS files to transform.

Property	Value
Type	`string[]`
Default	`["*/.css"]`

TailwindObfuscator({
  css: ["src/**/*.css", "styles/**/*.css"],
});

Mapping and cache

`mapping`

Mapping file output options. The mapping file stores the correspondence between original and obfuscated class names.

Property	Value
Type	`object`

TailwindObfuscator({
  mapping: {
    enabled: true, // Emit the mapping file
    file: ".tw-obfuscation/class-mapping.json", // Output path
    pretty: true, // Pretty-print JSON (or pass an indent number)
    format: "json", // 'json' or 'text'
  },
});

Sample emitted file:

json

{
  "version": "1.0.0",
  "generatedAt": "2024-01-15T10:30:00.000Z",
  "classes": {
    "bg-blue-500": {
      "original": "bg-blue-500",
      "obfuscated": "tw-k7x2",
      "usedIn": ["src/App.tsx", "src/Button.tsx"],
      "occurrences": 5
    }
  }
}

`cache`

Cache settings to speed up subsequent builds.

Property	Value
Type	`object`

TailwindObfuscator({
  cache: {
    enabled: true, // Enable the cache
    directory: ".tw-obfuscation/cache", // Cache folder
    strategy: "merge", // 'merge' or 'overwrite'
  },
});

Strategy	Description
`merge`	Merge with the existing cache
`overwrite`	Replace the cache wholesale

Advanced options

`tailwindVersion`

Tailwind CSS major version to target.

Property	Value
Type	`'3' \| '4' \| 'auto'`
Default	`'auto'`

TailwindObfuscator({
  tailwindVersion: "auto", // Auto-detect (recommended)
  tailwindVersion: "4", // Force Tailwind v4
  tailwindVersion: "3", // Force Tailwind v3
});

`sourcemap`

Generate source maps for debugging.

Property	Value
Type	`boolean`
Default	`true`

TailwindObfuscator({
  sourcemap: true, // Emit .map files
  sourcemap: false, // No source maps (smaller production bundle)
});

`refresh`

Re-extract the class list on every build instead of relying on the cache.

Property	Value
Type	`boolean`
Default	`true` in dev, `false` in prod

TailwindObfuscator({
  refresh: true, // Always rescan source files
  refresh: false, // Use the cache when present
});

`classGenerator`

Custom function that generates the obfuscated class name from the index and the original.

Property	Value
Type	`(index: number, originalClass: string) => string`
Default	Random generator

TailwindObfuscator({
  // Sequential short names: a, b, c, …, aa, ab, …
  classGenerator: (index) => {
    const chars = "abcdefghijklmnopqrstuvwxyz";
    let result = "";
    let n = index;
    do {
      result = chars[n % 26] + result;
      n = Math.floor(n / 26) - 1;
    } while (n >= 0);
    return result;
  },
});

WARNING

Using a custom classGenerator disables the automatic randomisation.

`preserve`

Classes and functions to keep out of the obfuscator's reach.

Property	Value
Type	`object`

TailwindObfuscator({
  preserve: {
    // String arguments to these functions are left as-is
    functions: ["debugClass", "analyticsTrack", "testId"],

    // These classes are never obfuscated
    classes: ["no-obfuscate", "keep-visible"],
  },
});

Example:

tsx

// Arguments to debugClass() are NOT obfuscated
const debug = debugClass("debug-border debug-bg");

// cn() is transformed normally
const styles = cn("bg-blue-500", "text-white"); // → cn('tw-a', 'tw-b')

`ignoreVueScoped`

Preserve Vue scoped selectors ([data-v-*]).

Property	Value
Type	`boolean`
Default	`true`

TailwindObfuscator({
  ignoreVueScoped: true, // Preserve [data-v-xxxxx]
});

`useAst`

Use the AST extractor for more accurate class detection in JS/TS files.

Property	Value
Type	`boolean`
Default	`true`

TailwindObfuscator({
  useAst: true, // More accurate, slightly slower
  useAst: false, // Regex-only (faster)
});

`usePostcss`

Use PostCSS for more accurate CSS file transformation.

Property	Value
Type	`boolean`
Default	`true`

TailwindObfuscator({
  usePostcss: true, // More accurate, slightly slower
  usePostcss: false, // Regex-only (faster)
});

Complete examples

Minimal configuration

import { TailwindObfuscator } from "tailwindcss-obfuscator/vite";

export default defineConfig({
  plugins: [
    TailwindObfuscator(), // All defaults
  ],
});

Recommended production configuration

TailwindObfuscator({
  prefix: "tw-",
  randomize: true,
  randomLength: 4,
  exclude: ["dark", "light"],
  mapping: {
    enabled: true,
    pretty: false, // Compact JSON in production
  },
});

Development configuration

TailwindObfuscator({
  verbose: true,
  debug: true,
  refresh: true,
  mapping: {
    pretty: 2, // Pretty-printed JSON for readability
  },
});

Project using Tailwind Typography

TailwindObfuscator({
  exclude: [
    /^prose/, // prose-* classes
    /^not-prose/, // not-prose classes
  ],
});

Strict whitelist

TailwindObfuscator({
  include: [/^bg-/, /^text-/, /^p-/, /^m-/, /^flex/, /^grid/],
});

In-source directives

Ignore comment

Use tw-obfuscate-ignore to skip a single line:

tsx

{
  /* tw-obfuscate-ignore */
}
<div className="debug-class analytics-tracker">Unobfuscated content</div>;

`twIgnore` tag

Use the twIgnore tagged template literal:

tsx

const twIgnore = String.raw;

const classes = `${twIgnore`debug-info`} bg-blue-500`;
// Result: "debug-info tw-a8k2"

Defaults summary

Option	Default
`prefix`	`"tw-"`
`randomize`	`true`
`randomLength`	`4`
`verbose`	`false`
`debug`	`false`
`exclude`	`[]`
`include`	`[]`
`tailwindVersion`	`"auto"`
`sourcemap`	`true`
`refresh`	`true` (dev) / `false` (prod)
`ignoreVueScoped`	`true`
`useAst`	`true`
`usePostcss`	`true`

Configuration Options ​

Core options ​

prefix ​

randomize ​

randomLength ​

verbose ​

debug ​

Class filtering ​

exclude ​

include ​

filter ​

Source files ​

content ​

css ​

Mapping and cache ​

mapping ​

cache ​

Advanced options ​

tailwindVersion ​

sourcemap ​

refresh ​

classGenerator ​

preserve ​

ignoreVueScoped ​

useAst ​

usePostcss ​

Complete examples ​

Minimal configuration ​

Recommended production configuration ​

Development configuration ​

Project using Tailwind Typography ​

Strict whitelist ​

In-source directives ​

Ignore comment ​

twIgnore tag ​

Defaults summary ​

Configuration Options

Core options

`prefix`

`randomize`

`randomLength`

`verbose`

`debug`

Class filtering

`exclude`

`include`

`filter`

Source files

`content`

`css`

Mapping and cache

`mapping`

`cache`

Advanced options

`tailwindVersion`

`sourcemap`

`refresh`

`classGenerator`

`preserve`

`ignoreVueScoped`

`useAst`

`usePostcss`

Complete examples

Minimal configuration

Recommended production configuration

Development configuration

Project using Tailwind Typography

Strict whitelist

In-source directives

Ignore comment

`twIgnore` tag

Defaults summary