README.md

rollup-plugin-lit-css

Rollup plugin to import css files as JavaScript tagged-template literal objects.

The "Lit" stands for "Literal"

You can use it to import CSS for various libraries like lit-element, @microsoft/fast-element, or others.

Do I Need This?

No. This is an optional package who's sole purpose is to make it easier to write CSS-in-CSS while working on lit-element projects. You can just as easily write your CSS in some 'styles.css.js' modules a la:

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

And this may actually be preferred.

Hopefully this package will become quickly obsolete when the CSS Modules Proposal (or something like it) is accepted and implemented.

In the mean time, enjoy importing your CSS into your component files.

Options

Name	Accepts	Default
include	Array of glob of files to include.	['**/*.css']
exclude	Array of glob of files to exclude.	undefined
native	Boolean switch, when true, plugin constructs a native CSSStyleSheet object.	false
uglify	Boolean or Object of uglifycss options.	false
specifier	Package to import css from	lit
tag	Name of the template-tag function	css
transform	Optional function (sync or async) which transforms css sources (e.g. postcss)	x => x

Usage

import config from './rollup.config.rest.js'
import litcss from 'rollup-plugin-lit-css';

export default {
  ...config,
  plugins: [
    litcss({ include, exclude, uglify })
  ]
}

Then import your CSS:

:host {
  display: block;
}

h1 {
  color: hotpink;
}

import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';

import style from './css-in-css.css';

@customElement('css-in-css')
class CSSInCSS extends LitElement {
  static readonly styles = [style];

  render() {
    return html`<h1>It's Lit!</h1>`;
  }
}

Native Constructible StyleSheets

If you would like to try the experimental native Constructible StyleSheets feature, set the native: true option. Then this plugin becomes a build-time prollyfill for native CSS modules. You must use the acorn-import-assertions acorn plugin, or rollup will choke on your import assertions:

import { importAssertions } from 'acorn-import-assertions';
import litcss from 'rollup-plugin-lit-css';

export default {
  // ... other rollup options here ...
  acornInjectPlugins: [importAssertions],
  plugins: [
    litcss({ include: 'components/**/*.css', native: true })
  ]
}

Then be sure to assert your import types in your source files.

import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';

import style from './css-in-css.css' assert { type: 'css' };

@customElement('css-in-css')
class CSSInCSS extends LitElement {
  static readonly styles = [style];

  render() {
    return html`<h1>It's Lit!</h1>`;
  }
}

Usage with FAST

plugins: [
  litcss({ specifier: '@microsoft/fast-element' })
]

import { FASTElement, customElement, html } from '@microsoft/fast-element';

import styles from './css-in-css.css';

const template = html<CSSinCSS>`<h1>It's Lit!</h1>`;

@customElement({ name: 'css-in-css', template, styles })
class CSSinCSS extends FASTElement {}

Looking for webpack? lit-css-loader Looking for esbuild? esbuild-plugin-lit-css

Usage with Sass, Less, PostCSS, etc.

To load scss files:

1. Specify an include option which includes scss files (i.e. a glob or regexp)
2. Define a transform function in the plugin options.

// rollup.config.js
import litcss from 'rollup-plugin-lit-css';
import Sass from 'sass';

export default {
  plugins: [
    litcss({
      include: '/**/*.scss',
      transform: (data, { filePath }) =>
        Sass.renderSync({ data, file: filePath })
          .css.toString(),
    }),
  ]
}

Similarly, to transform sources using PostCSS, specify a transform function:

// rollup.config.js
import litcss from 'rollup-plugin-lit-css';
import postcss from 'postcss';
import postcssNesting from 'postcss-nesting';

const processor = postcss(postcssNesting());

export default {
  plugins: [
    litcss({
      transform: (css, { filePath }) =>
        processor.process(css, { from: filePath })
          .css,
    }),
  ]
}

Usage with rollup-plugin-styles

rollup-plugin-styles does all the CSS-loading and -transformations in one single plugin (including Sass, PostCss, and so on). It works very well together with rollup-plugin-lit-css.

// rollup.config.js
import litcss from "rollup-plugin-lit-css";
import styles from "rollup-plugin-styles";

export default {
  plugins: [
    styles({ 
      mode: "emit" // emit pure CSS, so that litcss can consume it.
    }),

    // Make sure to list litcss *after* the styles-plugin.
    litcss(),
  ]
};

Upgrade from version 2.x

Starting with version 3.x, the default import used when transforming the CSS files is lit (see specifier option above) which is LitElement 3.x. If you need this package to work with LitElement 2.x, you have to set the specifier to lit-element like so:

import config from './rollup.config.rest.js'
import litcss from 'rollup-plugin-lit-css';

export default {
  ...config,
  plugins: [
    litcss({ specifier: 'lit-element' })
  ]
}