rollup-plugin-css-only

4.5.5 verified Mon Apr 27 auth: no javascript

A Rollup plugin (v4.5.5, stable) that bundles imported CSS files into a single asset rather than injecting them into the JavaScript bundle. Compared to rollup-plugin-postcss or rollup-plugin-styles, it is minimal—no CSS preprocessor support—and guarantees import order. Released under MIT, maintained by thgh, with compatibility for Rollup 2, 3, and 4 (since v4.4.0).

Common errors

error Error: You must specify output.assetFileNames or use plugin.options.output instead. ↓

cause The plugin cannot determine a default output filename because assetFileNames is not configured.

fix

Set output.assetFileNames or pass an output option to the plugin (e.g., output: 'bundle.css').

error TypeError: css is not a function ↓

cause Importing the plugin incorrectly (e.g., as a named export instead of default).

fix

Use import css from 'rollup-plugin-css-only' (default import).

error (!) Plugin rollup-plugin-css-only: This plugin is not compatible with Rollup 4. Please upgrade to v4.4.0 or later. ↓

cause Using an older version of the plugin (<4.4.0) with Rollup v4.

fix

Upgrade to rollup-plugin-css-only@4.4.0 or later.

error Error: ENOENT: no such file or directory, open 'bundle.css' ↓

cause The plugin wrote CSS via writeFile in an older version, but the directory doesn't exist or output option disabled writing.

fix

For v4+, use the output option to control where and how CSS is emitted.

Warnings

breaking v4.0.0 changed CSS emission from writeFile to asset emission. Custom output behaviors must be updated. ↓

fix If you relied on writeFile, use the `output` option (a function or string) to define custom behavior.

breaking Rollup v4 support requires rollup-plugin-css-only >=4.4.0. Older versions fail with Rollup v4. ↓

fix Upgrade to 4.4.0 or later, or stay on Rollup 3.

gotcha The plugin does not support CSS preprocessors (Sass, Less, etc.) out of the box. For that use rollup-plugin-postcss. ↓

fix Use rollup-plugin-postcss or add a separate preprocessor plugin before this one.

deprecated The `name` and `fileName` options are deprecated in favor of using the `output` option. They may be removed in a future major version. ↓

fix Use the `output` option to specify filename or custom logic.

gotcha If `output` is set to `false`, no CSS output is generated. This can be surprising if you expect a file to appear. ↓

fix Ensure you do not set output: false unless you intentionally want to suppress CSS output.

Install

npm install rollup-plugin-css-only

yarn add rollup-plugin-css-only

pnpm add rollup-plugin-css-only

Imports

css

wrong

const css = require('rollup-plugin-css-only')

correct

import css from 'rollup-plugin-css-only'

The package provides a default export. ESM-only since v4.0.0.

RollupPluginCssOnly
```
import type { RollupPluginCssOnly } from 'rollup-plugin-css-only'
```
TypeScript users can import the plugin options type.

default export

wrong

import { css } from 'rollup-plugin-css-only'

correct

import css from 'rollup-plugin-css-only'

Named export does not exist; must use default import.

Quickstart

Configures Rollup to bundle all imported CSS into a single 'bundle.css' asset, excluding minified files.

// rollup.config.js (ESM)
import css from 'rollup-plugin-css-only';

export default {
  input: 'src/index.js',
  output: {
    dir: 'dist',
    format: 'es',
    assetFileNames: 'assets/[name]-[hash][extname]'
  },
  plugins: [
    css({
      include: ['**/*.css'],
      exclude: ['**/*.min.css'],
      output: 'bundle.css' // Custom output filename
    })
  ]
};