rollup-plugin-postcss-modules

2.1.1 verified Mon Apr 27 auth: no javascript

A Rollup plugin that wraps rollup-plugin-postcss with built-in CSS Modules and TypeScript support. Stable version 2.1.1, released September 2023. Provides automatic generation of .d.ts files for CSS modules, enabling type-safe imports in TypeScript projects. The only maintained fork with TypeScript integration after rollup-plugin-postcss v2 dropped CSS Modules support. Differentiator: handles named exports with class name mangling (e.g., hyphenated names become camelCase with $ prefix) and generates default export objects alongside named exports.

Common errors

error Error: Cannot find module 'rollup-plugin-postcss' ↓

cause Missing peer dependency; rollup-plugin-postcss-modules does not automatically install it.

fix

Run npm install rollup-plugin-postcss --save-dev

error TypeError: postcss is not a function ↓

cause Using rollup-plugin-postcss-modules without calling it as a function in Rollup config.

fix

Correct usage: plugins: [postcss({...})] (call the imported function)

error 'className' is declared but its value is never read. ↓

cause TypeScript lint warning due to generated named exports not being used; default export is used instead.

fix

Suppress lint rule or use default export (import style from './file.css') and access via style.className.

Warnings

breaking Version 2.x requires postcss@8 and rollup-plugin-postcss 4.x; incompatible with postcss 7. ↓

fix Upgrade postcss to v8 and ensure rollup-plugin-postcss peer dependency is satisfied.

gotcha Named exports from CSS modules are mangled: hyphenated class names become camelCase with '$' prefix (e.g., 'my-class' becomes '$myClass$'). ↓

fix Use default export object for dynamic access, or enable camelCase option in postcss-modules options.

deprecated The plugins option in rollup-plugin-postcss-modules is deprecated; use the plugins option inside the modules object instead. ↓

fix Move PostCSS plugins to modules.plugins rather than top-level plugins.

gotcha writeDefinitions: true overwrites existing .d.ts files without warning. ↓

fix Ensure .css.d.ts files are not edited manually; consider version control exclusion.

Install

npm install rollup-plugin-postcss-modules

yarn add rollup-plugin-postcss-modules

pnpm add rollup-plugin-postcss-modules

Imports

default (postcss function)
wrong
```
const postcss = require('rollup-plugin-postcss-modules')
```
correct
```
import postcss from 'rollup-plugin-postcss-modules'
```
ESM default export; CommonJS require works but may break type inference. TypeScript types are bundled.

RollupPluginPostcssModulesOptions

wrong

import { RollupPluginPostcssModulesOptions } from 'rollup-plugin-postcss-modules'

correct

import type { RollupPluginPostcssModulesOptions } from 'rollup-plugin-postcss-modules'

Use type import to avoid runtime import; types are only exported for TypeScript.

postcss (named require)
wrong
```
const postcss = require('rollup-plugin-postcss-modules').default
```
correct
```
const postcss = require('rollup-plugin-postcss-modules')
```
In CommonJS, the default export is the entire module.exports, so you should not access .default.

Quickstart

Shows basic Rollup config with CSS modules, TypeScript definition generation, and autoprefixer.

// rollup.config.js
import postcss from 'rollup-plugin-postcss-modules';
import typescript from '@rollup/plugin-typescript';
import autoprefixer from 'autoprefixer';

export default {
  input: 'src/index.ts',
  output: { file: 'dist/bundle.js', format: 'es' },
  plugins: [
    postcss({
      extract: true,
      writeDefinitions: true,
      modules: { generateScopedName: '[name]__[local]___[hash:base64:5]' },
      plugins: [autoprefixer()],
    }),
    typescript(),
  ],
};