Registry / devops / postcss-lightningcss

postcss-lightningcss

library1.1.0jsnpmunverified

PostCSS plugin wrapping lightningcss for CSS compilation, vendor prefixing (replacing autoprefixer), minification, CSS Modules, and more. Current stable version is 1.1.0, released in early 2025, with gradual release cadence. Key differentiators: uses lightningcss which is written in Rust for speed, can replace multiple PostCSS plugins (autoprefixer, cssnano), supports modern CSS drafts like nesting, and ships TypeScript types. Peer dependency on PostCSS 8, requires Node.js >=20.19.

devops

npm install postcss-lightningcss

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · POSTCSS-LIGHTNINGC

postcss-lightningcss

devopsjavascriptv1.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import postcssLightningcss from 'postcss-lightningcss'

✗ const postcssLightningcss = require('postcss-lightningcss')

ESM-only since v1.1.0 (package.json has 'type': 'module'). CommonJS require will fail.

postcssLightningcss

✓ import postcssLightningcss from 'postcss-lightningcss'

✗ import { postcssLightningcss } from 'postcss-lightningcss'

Named export does not exist; must use default import.

PostCSS LightningCSS Plugin

✓ import postcssLightningcss from 'postcss-lightningcss'; postcss([postcssLightningcss(options)])

✗ postcss([postcssLightningcss])

Plugin is a function that must be called with options (even empty object). Calling without parentheses will pass the function reference as a plugin, which will fail.

Shows basic usage of postcss-lightningcss with PostCSS: import, create plugin with options, process CSS, and get minified output.

import postcss from 'postcss'; import postcssLightningcss from 'postcss-lightningcss'; import fs from 'fs/promises'; async function build() { const input = `/* example.css */ .example { color: red; }`; const result = await postcss([ postcssLightningcss({ browsers: '>= 0.5%', lightningcssOptions: { minify: true, sourceMap: false, }, }), ]).process(input, { from: 'input.css', to: 'output.css' }); console.log(result.css); // Output: .example{color:red} } build();

Debug

Known issues

breakingpostcss-lightningcss v1.1.0 is ESM-only; CommonJS require will fail with ERR_REQUIRE_ESM

fix

Use import syntax or dynamic import(). If using CommonJS, stick to v1.0.x or transpile with bundler.

affects: >=1.1.0

breakingNode.js < 20.19.0 is not supported in v1.1.0; engines field requires ^20.19.0 || ^22.12.0 || >= 24

fix

Upgrade Node.js to version 20.19.0 or newer (or 22.12+, 24+).

affects: >=1.1.0

gotchaPlugin must be called as a function (not passed as reference); passing postcssLightningcss without () will not apply options and may cause unexpected behavior or errors

fix

Always invoke with options: postcssLightningcss({...})

affects: >=1.0.0

gotchaWhen cssModules option is enabled, class names are transformed and cssModulesJSON callback is required to get mapping; otherwise transformed class names are lost

fix

Provide cssModulesJSON callback to capture the mapping, e.g., write to JSON file.

affects: >=1.0.0

deprecatedOlder PostCSS plugins like autoprefixer are redundant; lightningcss handles vendor prefixes natively via browserslist targets

fix

Remove autoprefixer from PostCSS config and rely on postcss-lightningcss's browsers option.

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/postcss-lightningcss/dist/index.js from ... not supported.

Trying to require() an ESM-only module in a CommonJS context.

fix

Change to 'import postcssLightningcss from "postcss-lightningcss";' in an ES module, or use dynamic import: 'const postcssLightningcss = (await import("postcss-lightningcss")).default;'

TypeError: postcssLightningcss is not a function

Passing the imported module directly to PostCSS without calling it as a function.

fix

Use postcss([postcssLightningcss({...})]) instead of postcss([postcssLightningcss]).

SyntaxError: Unexpected token 'export'

Using older Node.js (<20.19.0) which does not support ESM by default or package.json missing 'type': 'module'.

fix

Upgrade Node.js to >=20.19.0 and ensure your project is set up for ES modules (e.g., add "type": "module" to package.json or use .mjs files).

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

postcssrequiredpeer dependency: PostCSS plugin system requires PostCSS >=8.0.0

Agent activity

11 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/onigoetz/postcss-lightningcss ↗

packagepostcss-lightningcss ↗

homepagehttps://github.com/onigoetz/postcss-lightningcss#readme ↗