unplugin-lightningcss

0.4.5 verified Mon Apr 27 auth: no javascript

Unplugin Lightning CSS is a build tool plugin that integrates Lightning CSS into Vite, Rollup, esbuild, Webpack, Rspack, Farm, and Vue CLI via the unplugin interface. Version 0.4.5 is the latest stable release, published under an MIT license and maintained by the unplugin team. It offers CSS transformation, CSS modules, and minification with full TypeScript support. Key differentiators include zero-config setup, support for multiple bundlers from a single codebase, and the ability to opt-in to experimental CSS features via the `include` option. The package dropped Node.js 18 and CJS builds in recent major versions, requiring Node >=20.19.0 and ESM-only usage.

Common errors

error ERR_REQUIRE_ESM: require() of ES Module /node_modules/unplugin-lightningcss/... not supported ↓

cause Package is ESM-only since v0.3.0; require() cannot load ESM modules

fix

Use dynamic import: const LightningCSS = (await import('unplugin-lightningcss/vite')).default

error Cannot find module 'unplugin-lightningcss/vite' or its corresponding type declarations ↓

cause Root import used instead of bundler-specific subpath

fix

Change import to 'unplugin-lightningcss/vite' (or /rollup, /webpack, etc.)

error Unexpected token 'export' (in webpack config with require) ↓

cause Webpack config using CommonJS require() on an ESM-only package

fix

Set your webpack config file type to 'module' or use dynamic import

error TypeError: LightningCSS is not a function ↓

cause Importing the default export incorrectly (e.g., using named import instead of default)

fix

Use default import: import LightningCSS from 'unplugin-lightningcss/vite'

Warnings

breaking Node.js 18 dropped in v0.4.0; requires Node >=20.19.0 ↓

fix Upgrade Node.js to version 20.19.0 or later

breaking CJS build removed in v0.3.0; package is ESM-only ↓

fix Use ESM imports (import) or dynamic import() in CommonJS contexts

deprecated Options property 'minify' defaults to a function of process.env.NODE_ENV; may not be obvious ↓

fix Explicitly set minify: true or false to avoid unexpected behavior

gotcha Must use bundler-specific subpath import (/vite, /rollup, /webpack, etc.); importing from root 'unplugin-lightningcss' does not export plugin factory ↓

fix Use correct subpath, e.g., 'unplugin-lightningcss/vite'

gotcha In Webpack, require() will fail because package is ESM-only; must use dynamic import or configure webpack to handle ESM ↓

fix Use `const { default: LightningCSS } = await import('unplugin-lightningcss/webpack')`

gotcha Rollup requires an additional CSS plugin (like rollup-plugin-css-only) because Rollup doesn't handle CSS natively ↓

fix Add 'rollup-plugin-css-only' to your Rollup config alongside unplugin-lightningcss

Install

npm install unplugin-lightningcss

yarn add unplugin-lightningcss

pnpm add unplugin-lightningcss

Imports

default (LightningCSS plugin factory)
wrong
```
const LightningCSS = require('unplugin-lightningcss/vite')
```
correct
```
import LightningCSS from 'unplugin-lightningcss/vite'
```
Package is ESM-only since v0.3.0; use dynamic import or ESM in Node >=20.19.0
Rollup plugin
wrong
```
import LightningCSS from 'unplugin-lightningcss'
```
correct
```
import LightningCSS from 'unplugin-lightningcss/rollup'
```
Must use the specific bundler subpath export (e.g., /vite, /rollup, /webpack, /esbuild, /rspack, /farm, /vue-cli)
Webpack plugin
wrong
```
const LightningCSS = require('unplugin-lightningcss/webpack')
```
correct
```
const { default: LightningCSS } = await import('unplugin-lightningcss/webpack')
```
Webpack configs often use CommonJS, but this package is ESM-only — use dynamic import or set your webpack config as ES module

Quickstart

Configures unplugin-lightningcss in Vite with nesting, custom media, minification, and CSS modules.

import { defineConfig } from 'vite';
import LightningCSS from 'unplugin-lightningcss/vite';

export default defineConfig({
  plugins: [
    LightningCSS({
      options: {
        // Enable CSS nesting and custom media queries
        include: Features.Nesting | Features.CustomMediaQueries,
        // Minify output (default: false in dev, true in prod)
        minify: true,
        // CSS modules configuration
        cssModules: {
          pattern: '[name]_[local]_[hash:base64:5]',
        },
      },
    }),
  ],
});