prantlf/rollup-plugin-scss-lit

README

rollup-plugin-scss-lit

Rollup plugin for importing Sass sources as constructable stylesheets to projects using lit (lit-html and lit-element) or fast-element.

Faster than the combination of rollup-plugin-styles and rollup-plugin-lit-css. Uses the standard options of the Sass compiler. Supports minifying by cssnano or fully customisable transformations of the CSS output by PostCSS.

Synopsis

Custom element:

import { LitElement } from 'lit';
import styles from './styles.scss'

class MyElement extends LitElement {
  static styles = styles
  // the rest of the implementation
}

Build configuration:

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

export default {
  plugins: [
    litScss({ minify: process.env.NODE_ENV === 'production' })
  ]
  // the rest of the configuration
}

Installation

Make sure that you use Node.js 14 or newer and Rollup 2 or newer. Use your favourite package manager - NPM, PNPM or Yarn:

npm i -D rollup-plugin-scss-lit
pnpm i -D rollup-plugin-scss-lit
yarn add -D rollup-plugin-scss-lit

Usage

Create a rollup.config.js configuration file and import the plugin:

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

export default {
  input: 'src/index.js',
  output: { file: 'dist/main.js', format: 'iife', sourcemap: true },
  plugins: [
    litScss({
      minify: process.env.NODE_ENV === 'production',
      options: { loadPaths: ['node_modules'] }
    })
  ]
}

Then call rollup either via the command-line or programmatically.

Using with TypeScript

If you are using TypeScript, you may need to create a declaration file to allow TypeScript to import the SCSS files (otherwise you will see error messages like Cannot find module './styles.scss' or its corresponding type declarations.).

Create a file src/styles.d.ts with the following content:

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

If you have configured typescript to use a different outDir than the default of ./, you will also need to copy your SCSS files into that directory. You can use rollup-plugin-copy for this, by adding the following to your Rollup configuration file:

import copy from "rollup-plugin-copy";

export default {
  plugins: [
    copy({
      targets: [{ src: "src/**/*.scss", dest: "build" }], // build is configured as outDir in tsconfig.json
      flatten: false, // important - preserves folder structure
      hook: "buildStart", // important - needs to run before other plugins
    }),
    // ...
  ]
}

Options

The following options can be passed in an object to the plugin function to change the default values.

`include`

Type: Array<String>
Default: ['**/*.scss']

Pattern to match files which will be processed by the plugin.

`exclude`

Type: Array<String>
Default: []

Pattern to match files which will be ignored by the plugin.

`options`

Type: Object
Default: undefined

Options for the Sass compiler. Use any options supported by the compileString method from the Sass package.

`minify`

Type: Boolean | Object
Default: false

Enables minifying of the compiled CSS output. If an object is specified, it will be passed to the cssnano plugin.

Experimental feature: if the object is set to { fast: true }, esbuild will be used instead of postcss.

`plugins`

Type: Array<Object>
Default: undefined

An array of PostCSS plugins to fully customise the transformation of the compiled CSS output.

`tag`

Type: String
Default: 'css'

The tag used for the tagged template literal exported from the generated module. Use 'css' (default) with both lit-html and fast-element.

export default css`...`

`specifier`

Type: String
Default: 'lit'

The import specifier used in the imnport declaration of the tag above. Use 'lit' (default) with lit-html and '@microsoft/fast-element' with fast-element.

import { css } from 'lit'

import { css } from '@microsoft/fast-element'

How It Works

Let us have a stylesheet called src/styles.scss:

:host { display: block }

And import it for a custom element in src/index.js:

import { LitElement } from 'lit';
import styles from './styles.scss'

class MyElement extends LitElement {
  static styles = styles
  // the rest of the implementation
}

The stylesheet will be converted to the following script on-the-fly during the build and bundled into dist/browser.js:

import { css } from 'lit'
export default css`:host { display: block }`

Optimisation

Before converting to the tagged template literal, the CSS output can be optimised by PostCSS. The minifying is performed by the cssnano plugin. If an error occurs during the transformation, the whole bundling operation will fail, using the postcss-fail-on-warn plugin.

Passing a boolean to the litScss plugin - { minify: true } - will use the defaults. You can override them by passing an object with options for cssnano to minify instead of true:

{
  minify: {
    preset: ['default', { discardComments: { removeAll: true } }]
  }
}

Experimental feature: if the minify object is set to { fast: true }, esbuild will be used instead of postcss.

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Lint and test your code.

License

Licensed under the MIT License.