tailwindcss-mangle

The toolchain is composed of several specialized packages:

• tailwindcss-patch: Patches Tailwind runtimes, extracts class inventories, and exposes contexts for tooling.
• unplugin-tailwindcss-mangle: Rewrites class usage across various bundlers (Vite, Webpack, Rollup, Esbuild, Nuxt 3) by consuming the generated inventory.
• @tailwindcss-mangle/config: A shared configuration loader that normalizes both legacy and modern option shapes.
• @tailwindcss-mangle/shared: Provides helpers for class generation, filtering, and shared regex utilities.

tailwindcss-mangle is a utility suite designed to mangle (obfuscate) Tailwind CSS classes. It consists of several components:

• tailwindcss-patch: A utility used to patch Tailwind CSS code and retrieve its runtime context.
• unplugin-tailwindcss-mangle: A plugin for webpack and vite that performs the actual obfuscation of Tailwind CSS classes. This plugin depends on tailwindcss-patch.

Use unplugin-tailwindcss-mangle if you want to integrate class obfuscation into your build pipeline via Vite or Webpack.

The tailwindcss-patch package is a utility designed to modify the tailwindcss/lib source code at runtime. Its primary purposes are to:

1. Expose the Tailwind CSS context object to external code.
2. Provide handy tool classes for interacting with Tailwind's internals.

It uses semver to perform internal version checking, ensuring that different versions of tailwindcss are patched using appropriate strategies. This package serves as the foundation for other tools like tailwindcss-mangle (an obfuscator) and weapp-tailwindcss (which enables Tailwind in non-H5 environments).

tailwindcss-patch is a redesigned patching tool for Tailwind CSS designed to manage runtime context, class scanning, and output/caching in a single entry point.

Key features include:

• Tailwind v2/v3 Support: Automatically patches Tailwind to expose runtime context without requiring manual source code modifications.
• Tailwind v4 Support: Generates a complete list of class names by scanning CSS and content sources.
• Flexible Output: Supports writing results to JSON or plain text files, or returning them in-memory for custom integration workflows.
• Centralized Configuration: Manage cache strategies, filters, and custom length units within a single configuration object.
• Modern Architecture: Starting from v9, the tool only accepts modern configuration structures.

The @tailwindcss-mangle/shared package provides core utility functions used by the tailwindcss-mangle ecosystem. Key exported utilities include:

• ClassGenerator: The core class generation logic.
• escapeStringRegexp: Utility for escaping strings for use in regular expressions.
• makeRegex: Utility for creating regular expressions.
• splitCode: Utility for splitting code segments.
• defaultMangleClassFilter: The default filter used to determine which classes should be mangled.

Standard Tailwind CSS plugins and presets can only generate CSS; they cannot modify the underlying HTML or JS files (e.g., for class name obfuscation or escaping special characters like md:text-[20px]). To perform these transformations, you need access to the tailwindcss context object during the build process (e.g., within a Webpack or Vite plugin).

tailwindcss-patch achieves this by patching the Tailwind CSS source code to expose its internal runtime context, allowing packaging tools to intercept and modify code based on the generated utility classes.

To prevent cache pollution in monorepos, tailwindcss-patch uses context fingerprinting for cache isolation. Each cache entry is partitioned by a unique fingerprint calculated during the TailwindcssPatcher construction.

Fingerprint Components:

• Normalized process.cwd() (realpath).
• Normalized project root / cache directory (realpath).
• Absolute path and mtime of the Tailwind config (if present).
• Tailwind package root and version.
• tailwindcss-patch version.
• Deterministic hash of stable serialized patch options.

Cache Drivers: If you encounter permission issues, you can switch the cache.driver to:

• file (default)
• memory (in-memory cache)
• noop (no operation/disable cache)

HMR (Hot Module Replacement) state preservation is disabled by default in this template due to unpredictable behavior in svelte-hmr and @sveltejs/vite-plugin-svelte.

To ensure important data is not lost when a component reloads during development, move that state into an external Svelte store. External stores are not replaced by HMR, allowing the data to persist.

// store.ts
// An extremely simple external store
import { writable } from 'svelte/store'

export default writable(0)

Starting from version 5.1.0, unplugin-tailwindcss-mangle supports precise class name mangling for framework-specific files using AST-based transformations. This is more accurate than standard text replacement because it uses the framework's own compilers to parse the files.

Supported frameworks and their mechanisms:

• Vue SFC: Uses @vue/compiler-sfc to parse and transform classes within <template>, <script>, and <style> sections.
• Svelte: Uses svelte/compiler to parse components, including support for class directives.
• JSX/TSX: Uses Babel jsx and typescript plugins to ensure proper transformation for React and other JSX-based libraries.

The plugin uses a compiler-aware approach to dispatch files to specific handlers based on file extension, query hints (like type=script|style|template), and source-shape heuristics. This ensures high precision during the transformation process.

Handlers:

• jsHandler: Handles JS, TS, JSX, and TSX files.
• vueHandler: Handles full .vue Single File Components (SFCs).
• svelteHandler: Handles full .svelte files.
• cssHandler: Handles CSS requests and style sub-requests.
• htmlHandler: Handles HTML files and markup-like templates.

Webpack-specific behavior:

• HTML file requests are excluded from the transform loader to prevent child-compiler parse conflicts.
• The CSS pipeline is scoped around postcss-loader and post-process asset rewriting.

Because standard TypeScript cannot natively process type information for .vue files, this template uses vue-tsc instead of the standard tsc CLI for type checking.

To ensure your editor recognizes types within .vue imports, you must use the TypeScript Vue Plugin (Volar).