vite-css-modules

1.15.0 verified Mon Apr 27 auth: no javascript

Current stable version is 1.15.0, actively maintained with frequent releases (latest March 2026). Vite plugin that fixes multiple CSS Modules bugs in Vite by integrating CSS Modules properly into the build pipeline instead of delegating everything to postcss-modules. Key differentiators vs Vite's built-in CSS Modules: deduplicates composed styles, applies PostCSS plugins to composes dependencies, throws errors on missing composes classes, and generates accurate TypeScript declarations. Supports Vite 5, 6, 7, and 8, works with both postcss and lightningcss, and generates inline source maps for CSS Modules declarations.

Common errors

error [vite:css] Cannot find class 'nonexistent' in './utils.css' ↓

cause Typo or missing class name in a composes declaration.

fix

Ensure the class exists in the referenced CSS file and the import path is correct.

error TypeError: viteCssModules is not a function ↓

cause Using default import instead of named import, or importing from wrong path.

fix

Use import { viteCssModules } from 'vite-css-modules' instead of default import.

error Error: Vite plugin 'vite-css-modules' requires Vite version ^5.0.0. Current Vite version is 4.x ↓

cause Using an unsupported Vite major version.

fix

Upgrade Vite to 5.x or later, or install a compatible version of the plugin.

Warnings

breaking Before v1.9.2, duplicated styles when a CSS module was directly imported and composed elsewhere could cause style duplication. ↓

fix Upgrade to v1.9.2 or later.

gotcha peerDependencies include Vite 5, 6, 7, and 8, but not Vite 4 or earlier. Plugin will fail silently or throw if used with unsupported Vite versions. ↓

fix Use Vite >=5 or upgrade the plugin.

gotcha The plugin does not support CommonJS for consumer code; exports are ESM-only. Using require() incorrectly will lead to runtime errors. ↓

fix Use dynamic import or destructured require with .cjs extension if needed.

deprecated The option 'defaultExport' was deprecated in v1.15.0 in favor of 'exportMode'. ↓

fix Rename 'defaultExport' to 'exportMode' in plugin configuration.

Install

npm install vite-css-modules

yarn add vite-css-modules

pnpm add vite-css-modules

Imports

viteCssModules

wrong

import viteCssModules from 'vite-css-modules'

correct

import { viteCssModules } from 'vite-css-modules'

Named export only; default import is not available.

viteCssModules

wrong

const viteCssModules = require('vite-css-modules')

correct

const { viteCssModules } = require('vite-css-modules')

In CommonJS, use destructured require to get the named export.

type Options
```
import type { Options } from 'vite-css-modules'
```
TypeScript types are shipped; import type for Options.

Quickstart

Adds the viteCssModules plugin to a Vite config, fixing CSS Modules bugs like missing PostCSS on composes dependencies, duplicated shared styles, and silent failures on missing classes.

import { defineConfig } from 'vite'
import { viteCssModules } from 'vite-css-modules'

export default defineConfig({
  plugins: [
    viteCssModules({
      // Optional: configure export mode, defaults to 'default'
      exportMode: 'default', // 'default' | 'named' | 'mixed'
      // Optional: customize the generated TypeScript declarations file
      dts: './src/css-modules.d.ts'
    })
  ]
})