Mangle Tailwind v4 Issues

Technical issues with tailwindcss-patch and unplugin-tailwindcss-mangle on Tailwind CSS v4

Date: December 8, 2025 Project: tailwindcss-obfuscation App: tailwind_v4_react_nextjs Tailwind Version: 4.1.17 Next.js Version: 15.5.7

Executive Summary

CSS class obfuscation for Tailwind CSS v4 is currently not functional due to fundamental incompatibilities between the existing obfuscation tools and Tailwind v4's new architecture. This document details the technical issues encountered and their root causes.

1. Background: How CSS Obfuscation Works

CSS class obfuscation replaces human-readable class names with short, meaningless identifiers to:

Reduce CSS/HTML file size
Make reverse-engineering more difficult
Obfuscate design system implementation

Example transformation:

html

<!-- Before -->
<div class="flex min-h-screen items-center justify-center bg-gray-50">
  <!-- After -->
  <div class="tw-a tw-b tw-c tw-d tw-e"></div>
</div>

For this to work, the obfuscation tool must:

Extract all CSS class names used in the project
Generate a mapping (original → obfuscated)
Replace class names in both CSS selectors and HTML/JSX class attributes
Do this at build time to ensure consistency

2. Tool Tested: unplugin-tailwindcss-mangle

2.1 Overview

Package: unplugin-tailwindcss-mangle v5.0.0
Dependency: tailwindcss-patch v3.0.1
Configuration: @tailwindcss-mangle/config v6.1.0
Documentation: https://mangle.icebreaker.top/

This is the primary obfuscation tool for Tailwind CSS, supporting webpack and Vite.

2.2 How It Works (Tailwind v3)

tailwindcss-patch patches the Tailwind CSS compiler to extract generated class names
During build, it creates .tw-patch/tw-class-list.json with all classes
unplugin-tailwindcss-mangle uses this list to transform classes in:
- JavaScript/TypeScript files (className attributes)
- CSS files (selectors)
- HTML files

2.3 The Problem with Tailwind v4

Tailwind CSS v4 uses a completely new architecture:

Feature	Tailwind v3	Tailwind v4
Configuration	`tailwind.config.js` (JavaScript)	`@import "tailwindcss"` (CSS-first)
CSS Processing	PostCSS plugin	Native CSS with `@tailwindcss/postcss`
Class Generation	JIT compiler with JS API	Rust-based core engine (Oxide)
Layer System	`@layer` hijacking	Native CSS cascade layers

Root Cause: tailwindcss-patch cannot patch Tailwind v4's Rust-based engine to extract class names.

3. Error Analysis

3.1 Error When Using unplugin-tailwindcss-mangle with Tailwind v4

Configuration in next.config.ts:

typescript

import TailwindcssMangle from "unplugin-tailwindcss-mangle/webpack";

const nextConfig: NextConfig = {
  webpack: (config, { dev }) => {
    if (!dev) {
      config.plugins.push(TailwindcssMangle({}));
    }
    return config;
  },
};

Build Error:

Module not found: Can't resolve 'm-0":{"name":"tw-kia","usedBy":{}},"card":{"name":"tw-lia"...

3.2 Technical Explanation

The plugin adds a custom webpack loader before postcss-loader to transform CSS:

javascript

// From plugin source code
webpack(compiler) {
  compiler.hooks.compilation.tap(pluginName, (compilation) => {
    NormalModule.getCompilationHooks(compilation).loader.tap(pluginName, (_, module) => {
      const idx = module.loaders.findIndex((x) => x.loader.includes("postcss-loader"));
      if (idx > -1) {
        module.loaders.splice(idx, 0, {
          loader: WEBPACK_LOADER,
          options: { ctx }
        });
      }
    });
  });
}

The Bug: When processing CSS with Tailwind v4's @import "tailwindcss" syntax, the loader's context object (ctx) gets dumped as a module path string. Webpack then tries to resolve this JSON-like string as an actual module path, causing the "Module not found" error.

Error String Analysis:

Can't resolve 'm-0":{"name":"tw-kia","usedBy":{}}...'

This is a fragment of the internal class mapping JSON being incorrectly treated as a require/import path.

4. Alternative Approach: Post-Build Obfuscation

4.1 Strategy

Since build-time integration doesn't work, I attempted post-build text replacement:

Run next build normally
After build completes, run a script that:
- Reads the extracted class list
- Generates a mapping
- Replaces classes in .next/static/ and .next/server/ files

4.2 Implementation

typescript

// scripts/obfuscate-classes.ts
function replaceClasses(content: string, mapping: Map<string, string>) {
  for (const [original, obfuscated] of mapping) {
    // Replace in CSS selectors: .classname
    // Replace in HTML/JSX: class="classname"
    content = content.replace(pattern, obfuscated);
  }
  return content;
}

4.3 Why This Failed

The Problem: Tailwind class names overlap with JavaScript identifiers.

Examples of problematic class names:

grid - Also a CSS Grid property and potential variable name
flex - Also a flexbox property and potential variable name
top - Also a CSS position property and window.top
left, right, bottom - CSS properties
block, inline - CSS display values
hidden - Common boolean variable name

What Happened:

javascript

// Original compiled code
const grid = useGrid();

// After obfuscation (BROKEN)
const tw-abc = useGrid(); // Invalid JavaScript syntax!

The regex-based replacement cannot distinguish between:

class="grid" (should be replaced)
const grid = (should NOT be replaced)
.grid { in CSS (should be replaced)

Result: SyntaxError: Invalid left-hand side in assignment

5. Why Build-Time Integration is Required

CSS class obfuscation requires AST-level understanding of the code:

5.1 For JavaScript/TypeScript

The tool must use a JavaScript parser (like Babel or SWC) to:

Identify className prop values
Distinguish string literals from variable references
Handle dynamic class names (cn(), clsx(), template literals)

5.2 For CSS

The tool must use a CSS parser to:

Identify class selectors (.classname)
Avoid replacing property values that look like class names
Handle complex selectors ([class*="prefix-"])

5.3 For HTML

The tool must parse HTML to:

Find class attribute values
Split multiple classes correctly
Preserve non-class attributes

Text replacement cannot reliably do this.

6. Tailwind v4 Architectural Changes

6.1 CSS-First Configuration

Tailwind v3:

javascript

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

Tailwind v4:

css

/* app/globals.css */
@import "tailwindcss";

@theme {
  --color-primary: #3490dc;
}

6.2 Oxide Engine

Tailwind v4 uses a Rust-based engine called "Oxide" for:

Faster compilation
Native CSS parsing
Built-in content detection

This engine doesn't expose the same hooks that tailwindcss-patch used to extract class names.

6.3 Native Cascade Layers

Tailwind v3:

css

@layer utilities {
  .custom-class { ... }
}

Tailwind hijacked @layer for its own purposes.

Tailwind v4: Uses native CSS cascade layers, so the @layer syntax has different semantics.

7. Current Status

Component	Status	Notes
Class Extraction	✅ Working	Custom script extracts 1058 classes
Mapping Generation	✅ Working	1017 classes mapped to obfuscated names
CSS Transformation	❌ Broken	Plugin crashes with Tailwind v4
JS Transformation	❌ Broken	Post-build replacement breaks code
HTML Transformation	❌ Broken	Same issues as JS

8. Recommended Solutions

8.1 Short-Term: Use Tailwind v3

For projects requiring obfuscation now, use Tailwind CSS v3.4.x where the tooling works properly.

8.2 Medium-Term: Wait for Plugin Update

The unplugin-tailwindcss-mangle maintainers need to:

Update tailwindcss-patch to work with Tailwind v4's Oxide engine
Fix the CSS loader context serialization bug
Test with @tailwindcss/postcss

GitHub Issue to Watch: https://github.com/sonofmagic/tailwindcss-mangle/issues

8.3 Long-Term: Custom Solution

Build a custom obfuscation pipeline using:

SWC/Babel plugin for JavaScript transformation
PostCSS plugin for CSS transformation
Cheerio/HTMLParser for HTML transformation
Shared class registry for consistent mapping

This is complex but would provide reliable obfuscation.

9. Files Created During Investigation

File	Purpose
`scripts/extract-classes.ts`	Extracts Tailwind classes from React/shadcn components
`scripts/obfuscate-classes.ts`	Failed post-build obfuscation attempt
`.tw-obfuscation/class-list.json`	Extracted class names (1058 unique)
`.tw-obfuscation/class-mapping.json`	Original → obfuscated mapping
`tailwindcss-mangle.config.ts`	Plugin configuration (not used)

10. Conclusion

Tailwind CSS v4's architectural changes break existing obfuscation tools. The primary issue is that tailwindcss-patch cannot hook into the new Rust-based Oxide engine to extract class names, and the webpack loader has a bug that causes it to serialize its internal context as a module path.

Until the maintainers update their tools for Tailwind v4 compatibility, CSS class obfuscation is not reliably possible for Tailwind v4 projects.

References

External Links

Tailwind CSS v4.0 Release - Official blog post
Tailwind v4 Upgrade Guide - Migration documentation
tailwindcss-mangle Documentation - Official mangle docs
unplugin-tailwindcss-mangle GitHub - Source code

Mangle Tailwind v4 Issues ​

Executive Summary ​

1. Background: How CSS Obfuscation Works ​

2. Tool Tested: unplugin-tailwindcss-mangle ​

2.1 Overview ​

2.2 How It Works (Tailwind v3) ​

2.3 The Problem with Tailwind v4 ​

3. Error Analysis ​

3.1 Error When Using unplugin-tailwindcss-mangle with Tailwind v4 ​

3.2 Technical Explanation ​

4. Alternative Approach: Post-Build Obfuscation ​

4.1 Strategy ​

4.2 Implementation ​

4.3 Why This Failed ​

5. Why Build-Time Integration is Required ​

5.1 For JavaScript/TypeScript ​

5.2 For CSS ​

5.3 For HTML ​

6. Tailwind v4 Architectural Changes ​

6.1 CSS-First Configuration ​

6.2 Oxide Engine ​

6.3 Native Cascade Layers ​

7. Current Status ​

8. Recommended Solutions ​

8.1 Short-Term: Use Tailwind v3 ​

8.2 Medium-Term: Wait for Plugin Update ​

8.3 Long-Term: Custom Solution ​

9. Files Created During Investigation ​

10. Conclusion ​

References ​

Mangle Tailwind v4 Issues

Executive Summary

1. Background: How CSS Obfuscation Works

2. Tool Tested: unplugin-tailwindcss-mangle

2.1 Overview

2.2 How It Works (Tailwind v3)

2.3 The Problem with Tailwind v4

3. Error Analysis

3.1 Error When Using unplugin-tailwindcss-mangle with Tailwind v4

3.2 Technical Explanation

4. Alternative Approach: Post-Build Obfuscation

4.1 Strategy

4.2 Implementation

4.3 Why This Failed

5. Why Build-Time Integration is Required

5.1 For JavaScript/TypeScript

5.2 For CSS

5.3 For HTML

6. Tailwind v4 Architectural Changes

6.1 CSS-First Configuration

6.2 Oxide Engine

6.3 Native Cascade Layers

7. Current Status

8. Recommended Solutions

8.1 Short-Term: Use Tailwind v3

8.2 Medium-Term: Wait for Plugin Update

8.3 Long-Term: Custom Solution

9. Files Created During Investigation

10. Conclusion

References