rollup-plugin-postcss

1.0.0 verified Mon Apr 27 auth: no javascript

A Rollup plugin that enables seamless CSS processing via PostCSS, supporting CSS modules, custom preprocessors (Sass, Stylus, Less), and automatic extraction or injection of styles. v1.0.0 is the current stable version with a well-documented API and active maintenance from egoist. Key differentiators include built-in support for PostCSS config files, auto CSS modules for .module.* files, and a simple plugin interface that integrates deeply with Rollup's build pipeline. Alternatives like rollup-plugin-css-only offer lighter but less feature-rich integration.

Common errors

error Could not resolve './style.css' from 'src/index.js' ↓

cause Rollup cannot resolve CSS imports without the plugin.

fix

Ensure postcss is added to plugins in rollup.config.js and that the CSS file extension is in the plugin's extensions list (default includes .css).

error You must install postcss in order to use rollup-plugin-postcss ↓

cause PostCSS is a peer dependency that must be installed separately.

fix

Run 'npm install postcss --save-dev' or 'yarn add postcss --dev'.

error TypeError: postcss is not a function ↓

cause Importing the plugin incorrectly, e.g., as a constructor or destructured property.

fix

Use 'import postcss from 'rollup-plugin-postcss'' then call 'postcss({...})' as a function.

Warnings

breaking v1.0 removed the 'modules' option being a boolean-only value; it now accepts an object for postcss-modules options. ↓

fix Update config: if modules: {} was used, it's still valid; if modules: true was used, it's still valid.

gotcha When extract is false (default), CSS is injected into <head> and also available as default export from the CSS file. This can cause unexpected behaviour if you import CSS for side effects only. ↓

fix Set extract: true to avoid injection and get a CSS file instead, or use inject: false to prevent injection but still get the string.

gotcha The plugin automatically resolves local PostCSS config files (postcss.config.js), which may override options provided in the plugin call. ↓

fix Set config: false in plugin options to disable automatic config loading.

deprecated The 'namedExports' option as a boolean is deprecated; supply a function for custom name transformation. ↓

fix Replace namedExports: true with namedExports: (name) => name.replace(/-/g, '_') or similar.

gotcha If using Sass/Scss imports with '~', ensure the dependency is installed in node_modules and use the correct path (relative to node_modules root). ↓

fix Use @import '~bootstrap/dist/css/bootstrap'; and install bootstrap as a dependency.

Install

npm install rollup-plugin-postcss2

yarn add rollup-plugin-postcss2

pnpm add rollup-plugin-postcss2

Imports

default
wrong
```
const postcss = require('rollup-plugin-postcss')
```
correct
```
import postcss from 'rollup-plugin-postcss'
```
ESM default import. CommonJS require works if the plugin is used with bundlers that support CJS interop, but ESM is recommended.
postcss (function return)
wrong
```
new postcss({ plugins: [] })
```
correct
```
const plugin = postcss({ plugins: [] })
```
It's a factory function, not a constructor.
style (default export from CSS)
wrong
```
import { style } from './style.css'
```
correct
```
import style from './style.css'
```
With CSS modules or extract: false, the default export is a string of compiled CSS. Named exports only occur when namedExports is enabled.

Quickstart

Basic rollup.config.js setup with PostCSS plugin including autoprefixer, minification, CSS extraction, and CSS modules.

// rollup.config.js
import postcss from 'rollup-plugin-postcss'

export default {
  input: 'src/index.js',
  output: { dir: 'dist', format: 'esm' },
  plugins: [
    postcss({
      plugins: [
        require('autoprefixer'),
        require('cssnano')
      ],
      extract: true,
      modules: true
    })
  ]
}