rollup-plugin-css-modules

0.2.0 verified Mon Apr 27 auth: no javascript

A Rollup plugin providing support for standard CSS modules with import attributes (type: 'css'). Current stable version is 0.2.0, with no frequent release cadence yet. Key differentiators: it supports both transforming CSS modules into JavaScript that exports CSSStyleSheet instances (for browsers without native CSS module support) and bundling modules into a single CSS file with @supports sheet() wrappers for native support. It requires Rollup 4+. The plugin is lightweight, has no options besides bundledSheet, and ships TypeScript types.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module from ... not supported. ↓

cause Attempting to use CommonJS require() on an ESM-only package.

fix

Switch to import { cssModules } from 'rollup-plugin-css-modules' in an ESM context, or use dynamic import.

error Module "*.css" does not provide an export named 'default' ↓

cause CSS import without the correct attribute or plugin not processing it.

fix

Use import styles from './file.css' with { type: 'css' }; and ensure plugin is added to config.

error TypeError: cssModules is not a function ↓

cause Incorrect import pattern: either default import instead of named import, or using require().

fix

Use import { cssModules } from 'rollup-plugin-css-modules'.

Warnings

gotcha The plugin only supports CSS modules with {type: 'css'} import attributes. Other CSS imports (e.g., without attributes) are not processed. ↓

fix Ensure your CSS imports include the attribute: import styles from './styles.css' with { type: 'css' };

breaking Package is ESM-only. CommonJS require() throws error. ↓

fix Use import syntax or dynamic import(). For CommonJS projects, consider using rollup-plugin-css-modules with ESM config.

deprecated The @supports sheet(name) syntax is a convention, not a real CSS feature. It may not work with all CSS minifiers or tools. ↓

fix If your toolchain breaks because of unknown @supports, consider using the non-bundled mode (without bundledSheet option).

Install

npm install rollup-plugin-css-modules

yarn add rollup-plugin-css-modules

pnpm add rollup-plugin-css-modules

Imports

cssModules

wrong

const cssModules = require('rollup-plugin-css-modules')

correct

import { cssModules } from 'rollup-plugin-css-modules'

ESM-only package, cannot use CommonJS require(). Named export.

default import (fallback)
wrong
```
import cssModules from 'rollup-plugin-css-modules'
```
correct
```
import pkg from 'rollup-plugin-css-modules'; const { cssModules } = pkg;
```
The package has a default export that is an object containing cssModules. Direct default import of the function is incorrect.

Config usage

wrong

plugins: [cssModules({ fileName: 'styles.css' })]

correct

plugins: [cssModules({ bundledSheet: { fileName: 'styles.css' } })]

Arguments for bundled sheet must be nested under bundledSheet object, not flat.

Quickstart

Basic Rollup config using cssModules() with bundledSheet option to emit a single CSS file.

// rollup.config.js
import { cssModules } from 'rollup-plugin-css-modules';

export default {
  input: 'src/index.js',
  output: { file: 'dist/bundle.js', format: 'es' },
  plugins: [
    cssModules({
      bundledSheet: {
        fileName: 'bundle.css',
      },
    }),
  ],
};