rollup-plugin-styles

4.0.0 verified Mon Apr 27 auth: no javascript

Universal Rollup CSS processing plugin that supports PostCSS, Sass, Less, Stylus, CSS Modules, URL resolving, and assets. v4.0.0 requires Rollup ^2.63.0 and drops Node 12. Ships TypeScript types. Active development as of 2022. Differentiators: supports multiple preprocessors out-of-the-box, CSS Modules without extra config, and multiple modes (inject, extract, emit).

Common errors

error Error: Must use import to load ES Module: /project/node_modules/rollup-plugin-styles/dist/index.js ↓

cause Using CommonJS require() instead of ESM import.

fix

Change const styles = require('rollup-plugin-styles') to import styles from 'rollup-plugin-styles'.

error TypeError: Cannot read properties of undefined (reading 'modules') ↓

cause Missing or incorrect Rollup configuration referencing plugin options.

fix

Ensure the plugin is invoked with proper options object: styles({ modules: true }).

error Error: The 'sass' option 'fibers' is no longer supported in rollup-plugin-styles v4. ↓

cause Using deprecated `fibers` option for Sass synchronization.

fix

Remove fibers from sass options; use dart-sass with async compilation.

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

cause Rollup not configured to handle CSS imports or plugin not added.

fix

Add styles() to plugins array in rollup.config.js.

Warnings

breaking v4.0.0 dropped support for `sass` package's `fibers` option. Only dart-sass is supported. ↓

fix Remove `fibers` option; use dart-sass (default).

breaking v4.0.0 requires Rollup ^2.63.0. Older Rollup versions are incompatible. ↓

fix Upgrade Rollup to ^2.63.0.

breaking v4.0.0 dropped Node 12 support. Minimum Node version is ^14.13.1 || >=16.0.0. ↓

fix Upgrade Node to v14.13.1+, v16.0.0+, or later.

deprecated Using `require('rollup-plugin-styles')` is deprecated. Import is the recommended way. ↓

fix Switch to `import styles from 'rollup-plugin-styles'`.

gotcha CSS Modules export class names via default export only in `inject` or `extract` mode; in `emit` mode no exports are available. ↓

fix Use `mode: 'inject'` or `mode: 'extract'` to access class names. For `emit`, use other plugins downstream.

gotcha When using `@import` in Sass/Less, prepend with `~` to resolve from node_modules or it may treat as local file. ↓

fix Use `@import '~package/path'` for node_modules imports in Sass/Less.

Install

npm install rollup-plugin-styles

yarn add rollup-plugin-styles

pnpm add rollup-plugin-styles

Imports

default

wrong

const styles = require('rollup-plugin-styles')

correct

import styles from 'rollup-plugin-styles'

ESM-only since v4; CommonJS require will fail.

styles
wrong
```
import styles from 'rollup-plugin-styles'
```
correct
```
import { styles } from 'rollup-plugin-styles'
```
Both default and named exports available, but default is the plugin factory.

type Options

wrong

import { Options } from 'rollup-plugin-styles'

correct

import type { Options } from 'rollup-plugin-styles'

Options type is exported for TypeScript projects; avoid runtime import.

Quickstart

Basic Rollup configuration with SCSS support and CSS Modules enabled.

// rollup.config.js
import styles from 'rollup-plugin-styles';

export default {
  input: 'src/index.js',
  output: {
    dir: 'dist',
    format: 'esm',
    assetFileNames: '[name]-[hash][extname]'
  },
  plugins: [
    styles({
      mode: 'inject',
      modules: true,
      sass: {
        includePaths: ['node_modules', 'src/styles']
      }
    })
  ]
};

// src/index.js
import style from './styles.scss';
console.log(style); // class names if CSS Modules enabled