rollup-plugin-postcss

4.0.2 verified Mon Apr 27 auth: no javascript

Rollup plugin providing seamless integration with PostCSS. The current stable version is v4.0.2 (released Nov 2021, engines node >=10). It requires PostCSS 8.x as a peer dependency. Key differentiators: supports CSS modules, automatic PostCSS config loading, inject CSS into <head> or extract to file, and works with Sass, Less, Stylus via dependencies. Breaking change in v3: only supports Rollup v2, and extract path must be absolute. v4 upgraded to PostCSS 8. Also provides TypeScript types.

Common errors

error Error: The `extract` option must be a boolean or an absolute path. ↓

cause In v3+, relative paths for extract are not allowed; only absolute or boolean.

fix

Use path.resolve(__dirname, 'dist/styles.css') instead of 'dist/styles.css'.

error Error: PostCSS plugin postcss-xxx requires PostCSS 8. ↓

cause Installed v4 of rollup-plugin-postcss with PostCSS 7.x plugin.

fix

Update PostCSS to 8.x and ensure all PostCSS plugins are compatible.

error Cannot find module 'rollup-plugin-postcss'. ↓

cause Package not installed or missing in node_modules.

fix

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

error Error: You must specify a PostCSS plugin. ↓

cause The plugin options object is empty or plugins array is omitted.

fix

Provide at least one PostCSS plugin in the plugins array, even if empty.

Warnings

breaking v3.0 only supports Rollup v2, and extract path must be absolute. Relative paths in extract option will break. ↓

fix Use absolute paths for extract option, or stay on v2.x if using Rollup 1.x.

breaking v4.0.0 upgrade to PostCSS 8.x. PostCSS 7.x is no longer supported. ↓

fix Upgrade PostCSS to version 8.x. Update any PostCSS plugins to be compatible with PostCSS 8.

deprecated In v2, extract: true or a relative path generates file relative to bundle.js. In v3+, extract path should be absolute or resolve via path.resolve. ↓

fix When upgrading to v3+, change extract option to an absolute path using path.resolve().

gotcha When using Sass, this plugin prioritizes dart-sass over node-sass. If both are installed, dart-sass will be used. ↓

fix Ensure the desired Sass implementation is installed; to use node-sass, uninstall dart-sass.

gotcha CSS modules are automatically enabled for `.module.css` files by default (autoModules: true). This may unintentionally process files you expect to be global. ↓

fix Set autoModules: false to disable automatic CSS modules, or adjust file naming conventions.

Install

npm install rollup-plugin-postcss

yarn add rollup-plugin-postcss

pnpm add rollup-plugin-postcss

Imports

postcss
wrong
```
const postcss = require('rollup-plugin-postcss')
```
correct
```
import postcss from 'rollup-plugin-postcss'
```
Default export is the plugin factory function. CJS require works in v4 but ESM is recommended.
PostCSSPluginConfig
```
import type { PostCSSPluginConfig } from 'rollup-plugin-postcss'
```
Type-only import available since v4.0.0 with shipped TypeScript types.
postcss (CommonJS)
wrong
```
const postcss = require('rollup-plugin-postcss')
```
correct
```
const postcss = require('rollup-plugin-postcss').default
```
In CJS, the default export is under .default. Simple require() without .default returns an object if transpiled incorrectly.

Quickstart

Basic Rollup config using rollup-plugin-postcss with Autoprefixer, CSS modules, extraction, and minimization.

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

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