Registry / devops / vite-plugin-optimize-css-modules

vite-plugin-optimize-css-modules

library1.4.0jsnpmunverified

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.

devops

npm install vite-plugin-optimize-css-modules

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-OPTIMI

vite-plugin-optimize-css-modules

devopsjavascriptv1.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

optimizeCssModules

✓ import { optimizeCssModules } from 'vite-plugin-optimize-css-modules'

✗ const optimizeCssModules = require('vite-plugin-optimize-css-modules');

ESM-only package; no default export. Must use named import.

default

✓ import { optimizeCssModules } from 'vite-plugin-optimize-css-modules'

✗ import optimizeCssModules from 'vite-plugin-optimize-css-modules'

The package has no default export. Using a default import will result in `undefined` at runtime.

Type types

✓ import type { OptimizeCssModulesOptions } from 'vite-plugin-optimize-css-modules'

Types are exported if you need to pass options object. Check the source for exact type names.

Add the Vite plugin to your config. No options needed; works out of the box.

// vite.config.ts import { optimizeCssModules } from 'vite-plugin-optimize-css-modules'; import { defineConfig } from 'vite'; export default defineConfig({ plugins: [ optimizeCssModules() ] }); // Then run: npx vite build // Your CSS modules classnames will be minified automatically in production.

Debug

Known issues

gotchaOnly works with CSS modules: files ending with `.module.css` (or configured identically). Do not expect it to minify global CSS classnames.

fix

Ensure your CSS files use the `.module.css` extension or configure Vite's `css.modules` option properly.

affects: >=1.0.0

gotchaProduction-only transformation: The plugin only transforms CSS during `vite build`, not in dev mode (`vite dev`). Classnames appear as original hashes during development.

fix

This is by design. No action needed, but be aware that production CSS differs from dev CSS.

affects: >=1.0.0

breakingPeer dependency version range changed: v1.4.0 supports Vite v2–v8. Previous versions may have different ranges. Ensure your Vite version is compatible.

fix

Update Vite to v2, v3, v4, v5, v6, v7, or v8. Check package.json for exact peer range.

affects: >=1.4.0

gotchaDoes 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.

fix

Use static class references from CSS modules (e.g., `styles.card`) rather than constructing them from strings.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: optimizeCssModules is not a function

Using default import instead of named import.

fix

Change to: import { optimizeCssModules } from 'vite-plugin-optimize-css-modules'

Error: Vite plugin 'optimizeCssModules' requires a valid 'vite' peer dependency.

Missing or incompatible Vite version.

fix

Install Vite v2–v8: npm install vite@^5.0.0 (or matching your project's needs)

CSS classnames not minified in production build

The plugin is not added to Vite config or CSS file is not a CSS module (missing `.module.css` extension).

fix

Add `optimizeCssModules()` to the `plugins` array in `vite.config.ts` and ensure your CSS file is named like `styles.module.css`.

Upgrade

Version history

1.4.0latest on npm

Audit

Dependencies

viterequiredpeer dependency required for plugin to function

Agent activity

5 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/simonwep/vite-plugin-optimize-css-modules ↗

packagehttps://www.npmjs.com/package/vite-plugin-optimize-css-modules ↗