rollup-plugin-scss-lit

2.1.0 verified Mon Apr 27 auth: no javascript

Rollup plugin that imports Sass/SCSS sources as constructable stylesheets for Lit (lit-html/lit-element) and FAST Element projects. Version 2.1.0, released 2024-12-10, supports Node >=18 and peer dependencies lit ^2||^3 and rollup ^2||^3||^4. Replaces rollup-plugin-styles + rollup-plugin-lit-css with a single step. Uses the official Sass compileString API, supports minification via cssnano or esbuild, custom PostCSS transforms, include/exclude patterns, and TypeScript declarations. Faster and simpler than alternative multi-plugin setups.

Common errors

error Cannot find module './styles.scss' or its corresponding type declarations. ↓

cause TypeScript cannot resolve SCSS imports without a module declaration.

fix

Create src/styles.d.ts: declare module '*.scss' { import { CSSResultGroup } from 'lit'; const styles: CSSResultGroup; export default styles; }

error Error: Could not resolve entry module (src/index.js) or similar Rollup errors. ↓

cause Plugin may not be installed or not added to plugins array.

fix

Ensure rollup-plugin-scss-lit is installed (npm i -D rollup-plugin-scss-lit) and added to plugins: [litScss()] in rollup.config.js.

error TypeError: Cannot destructure property 'litScss' of ... as it is undefined. ↓

cause Attempted default import instead of named import.

fix

Use import { litScss } from 'rollup-plugin-scss-lit' (curly braces).

Warnings

breaking Minimum Node.js version is 18 since v2.0.0. ↓

fix Upgrade Node.js to >=18.

breaking Peer dependency changes: lit ^2 || ^3, rollup ^2 || ^3 || ^4 in v2.0.1+. Older versions may not support Rollup 4 or Lit 3. ↓

fix Update to v2.0.1+ for Lit 3 and Rollup 4 support.

deprecated The undocumented 'fast' option in minify object (e.g., { fast: true }) uses esbuild for minification; this is experimental and currently not recommended. ↓

fix Use plain minify: true with cssnano, or configure PostCSS plugins explicitly.

gotcha TypeScript requires a module declaration for *.scss imports; otherwise you get 'Cannot find module' errors. ↓

fix Create src/styles.d.ts declaring module '*.scss' with default export of type CSSResultGroup from 'lit'.

gotcha Plugin uses compileString from Sass; options are passed directly to it. Unsupported Sass options may break silently. ↓

fix Check Sass compileString documentation for valid options. Avoid importer or syntax options meant for legacy API.

gotcha When using TypeScript with a custom outDir, SCSS files must be copied to that directory (e.g., using rollup-plugin-copy with hook 'buildStart'). ↓

fix Add a copy plugin in rollup.config.js that copies src/**/*.scss to the outDir before other plugins run.

Install

npm install rollup-plugin-scss-lit

yarn add rollup-plugin-scss-lit

pnpm add rollup-plugin-scss-lit

Imports

litScss

wrong

import litScss from 'rollup-plugin-scss-lit'

correct

import { litScss } from 'rollup-plugin-scss-lit'

The plugin exports a named function `litScss`, not a default export.

default export (type declaration)

wrong

declare module '*.scss' { const content: string; export default content; }

correct

declare module '*.scss' { import { CSSResultGroup } from 'lit'; const styles: CSSResultGroup; export default styles; }

TypeScript declaration must use CSSResultGroup from 'lit', not a plain string type.

CSSResultGroup
wrong
```
import { CSSResult } from 'lit'
```
correct
```
import { CSSResultGroup } from 'lit'
```
The official Lit type for static styles arrays is CSSResultGroup, not CSSResult (though CSSResult is assignable).

Quickstart

Shows Rollup config with litScss plugin and a LitElement component importing a SCSS file as static styles.

// rollup.config.js
import { litScss } from 'rollup-plugin-scss-lit';

export default {
  input: 'src/index.js',
  output: { file: 'dist/bundle.js', format: 'esm' },
  plugins: [
    litScss({
      include: ['**/*.scss'],
      exclude: ['node_modules/**'],
      options: { loadPaths: ['node_modules'] },
      minify: process.env.NODE_ENV === 'production',
      plugins: [] // optional PostCSS plugins
    })
  ]
};

// src/my-element.js
import { LitElement } from 'lit';
import styles from './my-styles.scss';

class MyElement extends LitElement {
  static styles = styles;
  render() {
    return html`<div>Hello</div>`;
  }
}
customElements.define('my-element', MyElement);