@gustcss/vite 0.9.2 → 0.10.1

package/README.md

@@ -70,6 +70,61 @@ 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, TSX, and Astro. 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.
+
+**Astro templates** (`.astro`) are rewritten before the Astro compiler sees them. Astro's own Vite plugins run ahead of user plugins, so the rewrite happens in the plugin's `load` hook on the raw source, guided by the AST that `parse()` from `@astrojs/compiler` returns (the package ships with astro, so nothing extra has to be installed). Attribute kinds, the frontmatter, comments, `<style>` and `<script>` blocks are taken from that AST.
+
+**Rewritten:**
+- Static `class="…"` attributes and `class={"…"}` expressions that consist of a single string literal
+- `class:list` array elements (including the right operand of `cond && "flex"`) and quoted object keys, nested arrays and objects included
+- `classList.add("…")` / `setAttribute("class", "…")` calls in the frontmatter and in `<script>` blocks
+
+**Fail-closed** (the build stops when a mapped class appears in one of these places):
+- Any `class` expression other than a single string literal, such as `class={cond ? "flex" : "x"}` or `` class={`flex ${x}`} ``
+- Inside `class:list`: unquoted keys (`{ flex: on }`), shorthand properties (`{ hidden }`), template literals, comparison operands (`variant === "flex"`), subscripts (`map["flex"]`), function calls, method chains, or an expression that is not an array/object literal
+- Component props other than `class` / `class:list` (`<Card klass="flex" />`), `set:html` / `set:text` values, strings inside `{}` expressions (`{JSON.stringify("flex")}`), and ambiguous strings in the frontmatter or `<script>`. A `class` or `class:list` passed to a component is rewritten as a static value, like JSX `className`; forward `Astro.props.class` unchanged on the receiving side
+- `<style>` selectors (`.flex`, `@scope (.flex)`, `[class~="flex"]`); add hand-written selectors such as `.sr-only { … }` to `mangleExclude`
+
+HTML comments, `<code>` / `<pre>` bodies, ordinary non-class attributes (`<input type="flex">`) and `<style>` declarations (`border: 1px solid`) are neither rewritten nor inspected.
+
+JavaScript, TypeScript, JSX, TSX, and Astro frontmatter 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 and Svelte templates are not supported by this option. 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 +138,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