rollup-plugin-postcss-lit

2.2.0 verified Mon Apr 27 auth: no javascript

A Rollup plugin (v2.2.0, 2023) that transforms PostCSS-processed stylesheets (CSS, SCSS, Less, Stylus) into Lit templated `css` tagged template literals. It integrates with rollup-plugin-postcss and Vite's CSS handling, allowing direct CSS imports in LitElement components without runtime injection. Key differentiators: supports multiple preprocessors, works with both Rollup and Vite, and offers an `importPackage` option to target either `lit` or `lit-element`. Released under MIT, actively maintained.

Common errors

error Error: The plugin 'postcss-lit' transformed the asset 'styles.css' to a 'css' module but 'css' module type is not supported. ↓

cause The plugin is not properly registered or is placed before CSS handling plugins.

fix

Ensure postcssLit is placed after rollup-plugin-postcss in the plugins array.

error SyntaxError: Unexpected token export (or similar when importing the plugin in CommonJS) ↓

cause The package is ESM-only and cannot be required() in Node.js without ES module support.

fix

Use import syntax or set { type: 'module' } in package.json; avoid require().

error Module not found: Can't resolve 'lit' (or 'lit-element') ↓

cause The specified importPackage is not installed as a dependency.

fix

Install the corresponding package: npm install lit or npm install lit-element.

Warnings

breaking v2.0.0 switched the default import package from 'lit-element' to 'lit'. Existing projects using 'lit-element' must set importPackage: 'lit-element'. ↓

fix Add importPackage: 'lit-element' to plugin options if not using the 'lit' package.

gotcha When using Vite, CSS imports without ?inline suffix cause duplicate CSS injection (once as Lit styles, once as global styles). ↓

fix Append ?inline to CSS imports: import styles from './styles.css?inline'.

gotcha The plugin must be placed after rollup-plugin-postcss in the Rollup plugins array, otherwise styles won't be processed. ↓

fix Ensure postcss is before postcssLit: plugins: [postcss(...), postcssLit(...)].

gotcha If using Light DOM or not ShadowDOM, disable the 'inject: false' option in rollup-plugin-postcss to avoid style duplication. ↓

fix Set inject: false in postcss options unless you need global CSS injection.

Install

npm install rollup-plugin-postcss-lit

yarn add rollup-plugin-postcss-lit

pnpm add rollup-plugin-postcss-lit

Imports

default (plugin function)

wrong

const postcssLit = require('rollup-plugin-postcss-lit')

correct

import postcssLit from 'rollup-plugin-postcss-lit'

ESM default export; CommonJS require is not supported (v2.x+ is ESM-only).

importPackage option

wrong

postcssLit({ importPackage: 'lit-element' }) // correct usage; wrong would be omitting it when using lit-element

correct

postcssLit({ importPackage: 'lit-element' })

Defaults to 'lit'. Change to 'lit-element' if your project uses that package.

Vite CSS import with ?inline
wrong
```
import myStyles from './styles.css'
```
correct
```
import myStyles from './styles.css?inline'
```
Without ?inline suffix, Vite will also bundle the CSS separately, causing duplication.

Quickstart

Complete Rollup configuration with postcss and postcss-lit, plus a minimal Lit component importing transformed CSS.

// rollup.config.js
import postcss from 'rollup-plugin-postcss';
import postcssLit from 'rollup-plugin-postcss-lit';

export default {
  input: 'src/index.js',
  output: { dir: 'dist', format: 'es' },
  plugins: [
    postcss({ inject: false }), // disable injection for ShadowDOM
    postcssLit({ importPackage: 'lit' }),
  ],
};

// src/my-component.js
import { LitElement, css } from 'lit';
import myStyles from './styles.css';

export class MyComponent extends LitElement {
  static styles = myStyles;
  render() {
    return html`<p>Hello</p>`;
  }
}