rollup-plugin-css-chunks

2.0.3 verified Mon Apr 27 auth: no javascript

A Rollup plugin that extracts imported CSS files into separate output chunks, enabling code splitting of stylesheets alongside JavaScript. Version 2.0.3 requires Rollup >=2.29.0. Key differentiators include support for CSS sourcemaps, configurable chunk naming, and optional CSS @import injection for dependency ordering. It works with Rollup's code-splitting output to produce CSS files per entry or async chunk, complementing rollup-plugin-extract-bundle-tree for JS/CSS chunk dependency mapping.

Common errors

error Error: Cannot find module 'rollup-plugin-css-chunks' ↓

cause Package not installed or misconfigured in Node.js require resolution (CJS instead of ESM).

fix

Install the package: npm install --save-dev rollup-plugin-css-chunks. Ensure rollup.config.js uses ESM (e.g., type: module in package.json or .mjs extension).

error TypeError: css is not a function ↓

cause Using CommonJS require() on an ESM-only package; the default export is not available via require().

fix

Switch rollup.config.js to ESM syntax: import css from 'rollup-plugin-css-chunks';

error Error: Unexpected token (Note that you need plugins to import files that are not JavaScript) ↓

cause CSS is being imported in JavaScript but rollup-plugin-css-chunks is not added to the plugins array.

fix

Add the plugin to the rollup.config.js: import css from 'rollup-plugin-css-chunks'; and include it in the plugins array.

Warnings

breaking Requires Rollup >=2.29.0 due to plugin API changes; older Rollup versions will fail. ↓

fix Upgrade Rollup to version 2.29.0 or later.

gotcha CSS imports must be default imports; named imports (e.g., import { url } from './home.css') are not supported. ↓

fix Use import url from './home.css' instead of named imports.

gotcha The plugin does not handle CSS preprocessing (Sass, Less); those must be handled by separate plugins (e.g., rollup-plugin-sass) before this plugin. ↓

fix Chain a CSS preprocessor plugin before rollup-plugin-css-chunks in the Rollup plugins array.

deprecated The option 'injectImports' defaults to false since v2; setting it to true may cause duplicate @imports. ↓

fix Leave injectImports as false unless you are certain about the import ordering behavior.

Install

npm install rollup-plugin-css-chunks

yarn add rollup-plugin-css-chunks

pnpm add rollup-plugin-css-chunks

Imports

default
wrong
```
const css = require('rollup-plugin-css-chunks');
```
correct
```
import css from 'rollup-plugin-css-chunks';
```
ESM-only package; requires Rollup to run in ESM mode or using @rollup/plugin-node-resolve
css_chunk_url
wrong
```
const { default: css_chunk_url } = require('./home.css');
```
correct
```
import css_chunk_url from './home.css';
```
The plugin transforms CSS imports to return the chunk URL as a default string export
RollupPluginCssChunksOptions
```
import type { RollupPluginCssChunksOptions } from 'rollup-plugin-css-chunks';
```
TypeScript type export available for configuration options

Quickstart

Basic Rollup configuration using rollup-plugin-css-chunks to emit CSS files per entry and async chunks.

// rollup.config.js
import css from 'rollup-plugin-css-chunks';

export default {
  input: 'src/main.js',
  output: {
    dir: 'public',
    format: 'esm'
  },
  plugins: [
    css({
      chunkFileNames: '[name]-[hash].css',
      entryFileNames: '[name].css',
      sourcemap: false,
      emitFiles: true
    })
  ]
};