{"id":22765,"library":"vite-plugin-optimize-css-modules","title":"vite-plugin-optimize-css-modules","description":"A Vite plugin that minifies CSS modules classnames in production builds by replacing long generated hashes with the shortest possible identifiers (a, b, c, ...). v1.4.0, actively maintained, supports Vite v2–v8. Reduces CSS file size by up to 30% and build time by up to 94% (benchmarked on Bootstrap and Materialize). Ships TypeScript types. Alternative to generic CSS minifiers because it targets classname mangling specifically for CSS modules, preserving functionality while maximizing compression.","status":"active","version":"1.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/simonwep/vite-plugin-optimize-css-modules","tags":["javascript","vite","vite-plugin","css-modules","css","minify","typescript"],"install":[{"cmd":"npm install vite-plugin-optimize-css-modules","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-optimize-css-modules","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-optimize-css-modules","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency required for plugin to function","package":"vite","optional":false}],"imports":[{"note":"ESM-only package; no default export. Must use named import.","wrong":"const optimizeCssModules = require('vite-plugin-optimize-css-modules');","symbol":"optimizeCssModules","correct":"import { optimizeCssModules } from 'vite-plugin-optimize-css-modules'"},{"note":"The package has no default export. Using a default import will result in `undefined` at runtime.","wrong":"import optimizeCssModules from 'vite-plugin-optimize-css-modules'","symbol":"default","correct":"import { optimizeCssModules } from 'vite-plugin-optimize-css-modules'"},{"note":"Types are exported if you need to pass options object. Check the source for exact type names.","wrong":"","symbol":"Type types","correct":"import type { OptimizeCssModulesOptions } from 'vite-plugin-optimize-css-modules'"}],"quickstart":{"code":"// vite.config.ts\nimport { optimizeCssModules } from 'vite-plugin-optimize-css-modules';\nimport { defineConfig } from 'vite';\n\nexport default defineConfig({\n  plugins: [\n    optimizeCssModules()\n  ]\n});\n\n// Then run: npx vite build\n// Your CSS modules classnames will be minified automatically in production.","lang":"typescript","description":"Add the Vite plugin to your config. No options needed; works out of the box."},"warnings":[{"fix":"Ensure your CSS files use the `.module.css` extension or configure Vite's `css.modules` option properly.","message":"Only works with CSS modules: files ending with `.module.css` (or configured identically). Do not expect it to minify global CSS classnames.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"This is by design. No action needed, but be aware that production CSS differs from dev CSS.","message":"Production-only transformation: The plugin only transforms CSS during `vite build`, not in dev mode (`vite dev`). Classnames appear as original hashes during development.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update Vite to v2, v3, v4, v5, v6, v7, or v8. Check package.json for exact peer range.","message":"Peer dependency version range changed: v1.4.0 supports Vite v2–v8. Previous versions may have different ranges. Ensure your Vite version is compatible.","severity":"breaking","affected_versions":">=1.4.0"},{"fix":"Use static class references from CSS modules (e.g., `styles.card`) rather than constructing them from strings.","message":"Does not handle dynamic classnames: If you use template literals or concatenation to build classnames, the plugin cannot guarantee correct minification because it only knows about static CSS module imports.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Change to: import { optimizeCssModules } from 'vite-plugin-optimize-css-modules'","cause":"Using default import instead of named import.","error":"TypeError: optimizeCssModules is not a function"},{"fix":"Install Vite v2–v8: npm install vite@^5.0.0 (or matching your project's needs)","cause":"Missing or incompatible Vite version.","error":"Error: Vite plugin 'optimizeCssModules' requires a valid 'vite' peer dependency."},{"fix":"Add `optimizeCssModules()` to the `plugins` array in `vite.config.ts` and ensure your CSS file is named like `styles.module.css`.","cause":"The plugin is not added to Vite config or CSS file is not a CSS module (missing `.module.css` extension).","error":"CSS classnames not minified in production build"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}