rollup-plugin-sass

1.15.3 verified Mon Apr 27 auth: no javascript

Rollup plugin for compiling Sass/SCSS files into CSS, with support for output to file, insertion into <head>, and custom processors (e.g., PostCSS). Current version 1.15.3, released July 2024, with maintenance releases focused on dependency updates and vulnerability fixes. Key differentiators: supports both legacy `node-sass` and modern `sass` compiler via `api` option (added in v1.15.0), CSS modules via processor, and TypeScript types included. Release cadence is irregular but with periodic maintenance updates.

Common errors

error Error: The 'sass' package is required to use this plugin. Please install it: npm install sass ↓

cause Missing peer dependency `sass`.

fix

npm install sass --save-dev

error [!] Error: Could not resolve './styles.scss' from 'index.js' ↓

cause Rollup cannot resolve the SCSS file; plugin not processing it.

fix

Ensure the plugin is added to the Rollup plugins array and the file extension is included in the import.

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

cause Processor callback returns a promise that resolves to undefined or malformed object.

fix

Ensure processor returns an object with a css property, or a promise that resolves to such an object.

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

cause The `output` option is set to a path where the directory does not exist.

fix

Create the output directory or use a path that exists.

Warnings

gotcha The `insert` option requires the sass compiler to output a utility function that inserts styles into <head>. Ensure you are not using `output: true` together with `insert: true` (they conflict). ↓

fix Use either `output` or `insert`, not both.

gotcha When `api: 'modern'` is set (v1.15.0+), the `sass` package's modern API is used. This changes return types and may break custom processors that expect the legacy API. ↓

fix Ensure processor functions are compatible with both legacy and modern API returns.

gotcha TypeScript users must enable `esModuleInterop` or `allowSyntheticDefaultImports` to use the default import. Otherwise, use `import * as sass from 'rollup-plugin-sass'`. ↓

fix Add `"esModuleInterop": true` to tsconfig.json.

deprecated The `output` option as a function receives `(styles, styleNodes)`. The second argument `styleNodes` may be deprecated in future; prefer the new API. ↓

fix Check the plugin documentation for the latest callback signature.

breaking In v1.13.0, `*.css` file support was added to the default sass file importer. This may cause unexpected imports if you have CSS files alongside SCSS. ↓

fix Use the `include` or `exclude` options to restrict which files are processed.

Install

npm install rollup-plugin-sass

yarn add rollup-plugin-sass

pnpm add rollup-plugin-sass

Imports

default (plugin)
wrong
```
const sass = require('rollup-plugin-sass').default;
```
correct
```
import sass from 'rollup-plugin-sass';
```
ESM default export; CommonJS require returns the default directly, not as .default. TypeScript requires `esModuleInterop` or `allowSyntheticDefaultImports`.
SassOptions
```
import type { SassOptions } from 'rollup-plugin-sass';
```
TypeScript users should use type import for options.
SassPluginOptions
```
import type { SassPluginOptions } from 'rollup-plugin-sass';
```
TypeScript users should use type import for plugin options.

Quickstart

Basic Rollup config that compiles SCSS to CSS, writes to file, and runs PostCSS with autoprefixer.

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

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'cjs',
  },
  plugins: [
    sass({
      output: 'dist/bundle.css',
      processor: (css) =>
        postcss([autoprefixer])
          .process(css, { from: undefined })
          .then((result) => result.css),
    }),
  ],
};