rollup-plugin-postcss-export

1.0.3 verified Mon Apr 27 auth: no javascript

A Rollup plugin that integrates PostCSS processing and bundles processed CSS into a single external file. Version 1.0.3 is the latest stable release. Features include custom PostCSS plugins, source maps, CSS modules support via postcss-modules, and configurable file extensions. Key differentiators: it exports all CSS to one external file rather than inlining or emitting separate chunks, and it supports CSS modules with a getExport callback. The plugin is lightweight and focused, but has low maintenance activity.

Common errors

error TypeError: postcss is not a function ↓

cause Incorrect import: using named import instead of default.

fix

Change to 'import postcss from 'rollup-plugin-postcss-export'

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

cause Missing npm dependencies or incorrect package name.

fix

Run 'npm install rollup-plugin-postcss-export' and ensure no typos.

error Error: The 'export' option is required if you want to output a file. ↓

cause Missing 'export' option in plugin config.

fix

Add 'export: './bundle.css'' to the postcss options.

error TypeError: Cannot read property 'id' of undefined ↓

cause CSS import not resolved or plugin not applied before other plugins.

fix

Ensure plugin is early in the plugins array and imports have correct paths.

Warnings

gotcha The 'export' option must be a path relative to Rollup's output directory, not an absolute path. Misconfigured paths lead to missing CSS output. ↓

fix Use './output.css' instead of '/absolute/path/output.css'.

gotcha The plugin only processes CSS imported via JavaScript (import 'style.css'). It does not include CSS from <link> tags or HTML files. ↓

fix Ensure all CSS is imported in your JS entry points or use additional plugins for HTML.

deprecated The 'postcss' option to pass a PostCSS instance directly is deprecated. Use the 'plugins' array instead. ↓

fix Replace 'postcss: require('postcss')' with 'plugins: [...]'.

gotcha CSS modules (via postcss-modules) require manual export mapping; the plugin does not handle it automatically. ↓

fix Implement 'getJSON' in postcss-modules config and a 'getExport' function in the plugin options.

gotcha The plugin does not support 'use' or 'inject' options; all CSS is exported to an external file only. ↓

fix Use alternative plugins like rollup-plugin-postcss if you need to inject CSS or bundle inline.

Install

npm install rollup-plugin-postcss-export

yarn add rollup-plugin-postcss-export

pnpm add rollup-plugin-postcss-export

Imports

postcss

wrong

const postcss = require('rollup-plugin-postcss-export');

correct

import postcss from 'rollup-plugin-postcss-export'

ESM-only; default export.

postcss (default)

wrong

import { postcss } from 'rollup-plugin-postcss-export'

correct

import postcss from 'rollup-plugin-postcss-export'

Do not use named import; plugin is default-exported.

TypeScript type

wrong

import { PostCSSPluginOptions } from 'rollup-plugin-postcss-export'

correct

import type { PostCSSPluginOptions } from 'rollup-plugin-postcss-export'

Type imports are available; avoid runtime import of types.

Quickstart

Minimal Rollup config using rollup-plugin-postcss-export to process CSS and export a single external CSS file with autoprefixer and source maps.

import postcss from 'rollup-plugin-postcss-export';

export default {
  input: 'src/main.js',
  output: { dir: 'dist', format: 'es' },
  plugins: [
    postcss({
      plugins: [require('autoprefixer')],
      sourceMap: true,
      export: './dist/bundle.css',
    }),
  ],
};