Rollup plugin for importing CSS 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. Supports minifying by cssnano, inlining by postcss-import and [postcss-ulrl] or fully customisable transformations of the CSS input by PostCSS.
Custom element:
import { LitElement } from 'lit';
import styles from './styles.css'
class MyElement extends LitElement {
static styles = styles
// the rest of the implementation
}
Build configuration:
import { litCss } from 'rollup-plugin-css-lit'
export default {
plugins: [
litCss({ minify: process.env.NODE_ENV === 'production' })
]
// the rest of the configuration
}
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-css-lit
pnpm i -D rollup-plugin-css-lit
yarn add -D rollup-plugin-css-lit
Create a rollup.config.js
configuration file and import the plugin:
import { litCss } from 'rollup-plugin-css-lit'
export default {
input: 'src/index.js',
output: { file: 'dist/main.js', format: 'iife', sourcemap: true },
plugins: [
litCss({
minify: process.env.NODE_ENV === 'production',
inline: { assets: {} }
})
]
}
Then call rollup
either via the command-line or programmatically.
The following options can be passed in an object to the plugin function to change the default values.
Type: Array<String>
Default: ['**/*.css']
Pattern to match files which will be processed by the plugin.
Type: Array<String>
Default: []
Pattern to match files which will be ignored by the plugin.
Type: Object
Default: undefined
Options for the Sass compiler. Use any [options] supported by the [compileString] method from the Sass package.
Type: Boolean | Object
Default: false
Enables minifying of the transformed 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.
Type: Boolean | Object
Default: false
Enables inlining of stylesheets and other assets. If an object is specified, it will have to include two properties pointing to objects: { stylesheets, assets }
. The stylesheets
objects will be passed to the postcss-import plugin. The assets
objects will be passed to the postcss-url plugin.
Experimental feature: if the object is set to { fast: true }
, esbuild will be used instead of postcss.
Type: Array<Object>
Default: undefined
An array of PostCSS plugins to fully customise the transformation of the CSS input.
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`...`
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'
Let us have a stylesheet called src/styles.css
:
:host { display: block }
And import it for a custom element in src/index.js
:
import { LitElement } from 'lit';
import styles from './styles.css'
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 }`
Before converting to the tagged template literal, the CSS output can be optimised by PostCSS. The minifying is performed by the cssnano plugin. Inlining of other stylesheets imported by the @import
directives is performed by the postcss-import plugin. Inlining of other assets like pictures referred to by absolute or relative URLs is performed by the postcss-url plugin. If an error occurs during the transformation, the whole bundling operation will fail, using the postcss-fail-on-warn plugin.
Passing a booleans to the litCss
plugin - { minify: true, inline: true }
- will use the defaults. You can override them by passing an object instead of true
:
{
minify: {
preset: ['default', { discardComments: { removeAll: true } }]
},
inline: {
stylesheets: {},
assets: { url: 'inline' }
}
}
Pass options for cssnano to minify
, options for postcss-import to inline.stylesheets
and options for postcss-url to inline.assets
.
Experimental feature: if the minify
or inline
object is set to { fast: true }
, esbuild will be used instead of postcss.
In lieu of a formal styleguide, take care to maintain the existing coding style. Lint and test your code.
Copyright (C) 2022-2024 Ferdinand Prantl
Licensed under the MIT License.