rollup-plugin-scss

4.0.1 verified Mon Apr 27 auth: no javascript

A Rollup plugin for compiling .scss, .sass, and .css files into a single CSS file, with support for source maps, custom processors (e.g., PostCSS), and prefix injection. Version 4.0.1 is stable and actively maintained. It automatically uses the 'sass' package over 'node-sass', is written in TypeScript, and integrates seamlessly with Rollup's asset pipeline. Compared to alternatives like rollup-plugin-postcss, it focuses solely on Sass/SCSS compilation without additional CSS processing by default, offering a leaner setup for pure SCSS projects.

Common errors

error Error: Cannot find module 'rollup-plugin-scss' ↓

cause Package not installed or ESM-only package loaded with require in Node < 12.

fix

Install: npm install --save-dev rollup-plugin-scss. For CJS, use dynamic import: const scss = (await import('rollup-plugin-scss')).default;

error TypeError: scss is not a function ↓

cause Named import { scss } used instead of default import.

fix

Use default import: import scss from 'rollup-plugin-scss'

error Error: Options.output must be of type function or false, got object ↓

cause Passing an object to the 'output' option; it expects a function or boolean false.

fix

Set 'output' to a callback function or false: output: (styles, styleNodes) => { ... }

error Error: Cannot find module 'sass' ↓

cause Missing Sass compiler dependency.

fix

Install sass or node-sass: npm install --save-dev sass

Warnings

breaking v3 removed node-sass from optionalDependencies; you must install sass or node-sass explicitly. ↓

fix Add 'sass' (or 'node-sass') to your devDependencies: npm install --save-dev sass

breaking v3 switched to ESM-only; CommonJS require no longer works. ↓

fix Use dynamic import if needed: const scss = (await import('rollup-plugin-scss')).default;

breaking The 'output' callback signature changed in v3: second parameter is an array of style objects instead of a single string. ↓

fix Update callback: function(styles, styleNodes) where styleNodes is Array<{filename: string, content: string}>

deprecated The 'name' option is deprecated in favor of 'fileName' since v3. ↓

fix Use 'fileName' instead of 'name' to set the output CSS filename.

gotcha If both 'sass' and 'node-sass' are installed, 'sass' is preferred; this may cause unexpected behavior if your project depends on node-sass specifics. ↓

fix Explicitly set the 'sass' option to the compiler you want: sass: require('node-sass')

Install

npm install rollup-plugin-scss

yarn add rollup-plugin-scss

pnpm add rollup-plugin-scss

Imports

default

wrong

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

correct

import scss from 'rollup-plugin-scss'

ESM-only since v3. CommonJS require will fail.

scss
wrong
```
import { scss } from 'rollup-plugin-scss'
```
correct
```
import scss from 'rollup-plugin-scss'
```
The plugin is exported as default, not a named export. Named import will yield undefined.
SassPluginOptions (TypeScript)
```
import type { SassPluginOptions } from 'rollup-plugin-scss'
```
TypeScript users can import the options type for type-safe configuration. Available in v3+.

Quickstart

Example Rollup config using rollup-plugin-scss with options: custom output filename, source maps, include/exclude patterns, error handling, and output callback.

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

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'esm',
    assetFileNames: '[name][extname]'
  },
  plugins: [
    scss({
      fileName: 'bundle.css',
      sourceMap: true,
      output: (styles, styleNodes) => {
        console.log(`Generated ${styles.length} bytes of CSS`);
      },
      include: ['**/*.scss'],
      exclude: ['**/vendor/**'],
      failOnError: true,
      verbose: false
    })
  ]
};