@gustcss/vite 0.9.2 → 0.10.0

package/README.md

@@ -70,6 +70,46 @@ Create `gustcss.config.json` in your project root:
 }
 ```
 
+### Production Class-Name Mangling
+
+Enable `mangleClassNames` to shorten generated selectors and matching source references during `vite build`.
+
+Development mode keeps readable class names.
+
+```javascript
+export default defineConfig({
+  plugins: [
+    gustcss({
+      output: 'src/styles/utility.css',
+      mangleClassNames: true,
+      mangleExclude: ['public-hook'],
+    }),
+  ],
+})
+```
+
+The manifest defaults to `<output>.classes.json`; set `mangleMap` to use another path. A path inside Vite's `outDir` is fine: the plugin writes the manifest again after `emptyOutDir` runs.
+
+Treat the manifest as generated output and ignore it in Git unless your workflow intentionally pins class mappings.
+
+The transformer supports HTML, JavaScript, TypeScript, JSX, and TSX. It rewrites static `class` and `className` attributes, static template segments, direct string arguments to `classList`, and `setAttribute('class', ...)`. Code examples inside HTML `<code>` and `<pre>` bodies are neither rewritten nor inspected; classes on the elements themselves are still rewritten. An unclosed `<code>` or `<pre>` fails the build instead of masking the remainder of the document.
+
+JavaScript, TypeScript, JSX, and TSX transforms emit Source Map v3 mappings back to the original source. Comments and ordinary strings containing `class="..."` are not treated as JSX attributes. An ordinary string that still references a mapped class fails closed as ambiguous.
+
+Conditional expressions, nested calls, selectors, and other ambiguous references fail the build. The plugin restores readable CSS after a failed transform.
+
+Add dynamically or externally referenced class names, including production E2E selectors, to `mangleExclude`.
+
+Vue, Astro, and Svelte templates are not supported by this option yet. A mapped class in one of these files fails the build instead of emitting mismatched output.
+
+Files under `node_modules` are neither rewritten nor inspected.
+
+Short names avoid every class token found in the scanned `content` files, `safelist`, and `mangleExclude`. One- or two-letter classes defined outside `content` can still collide; add them to `mangleExclude`.
+
+`el.className = '...'` assignments are not rewritten and fail the build when they contain a mapped class. Use `setAttribute('class', ...)` or `classList` instead.
+
+This optimization is not available through the PostCSS plugin because PostCSS cannot rewrite application markup and JavaScript.
+
 ## Features
 
 ### ⚡️ Development Mode
@@ -83,6 +123,7 @@ Create `gustcss.config.json` in your project root:
 - Generates optimized CSS at build time
 - Only includes utilities used in your code
 - No runtime overhead
+- Optional production-only class-name mangling with no runtime overhead
 
 ## How It Works