Registry / devops / lightningcss-wasm

lightningcss-wasm

library1.32.0jsnpmunverified

Lightning CSS (v1.32.0) is an extremely fast CSS parser, transformer, and minifier written in Rust, distributed as a WebAssembly module for Node.js and the browser. It provides typed property values, browser-grade parsing via Mozilla's cssparser and selectors, automatic vendor prefixing based on browser targets (including browserslist support), syntax lowering for modern CSS (nesting, logical properties, color functions, selectors, math functions), and advanced minification (shorthand merging, gradient minification, calc reduction). It is a standalone library used by Parcel and can be integrated with any build tool. It ships TypeScript types and supports both ESM and CommonJS. Compared to alternatives like cssnano or postcss, it offers significantly faster performance and more comprehensive value-level optimizations.

devops

npm install lightningcss-wasm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LIGHTNINGCSS-WASM

lightningcss-wasm

devopsjavascriptv1.32.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.

transform

✓ import { transform } from 'lightningcss-wasm'

✗ const transform = require('lightningcss-wasm').transform

All exports are ESM and also available as named exports; require() works but is not recommended

bundle

✓ import { bundle } from 'lightningcss-wasm'

✗ import { Bundle } from 'lightningcss-wasm'

The function is lowercase 'bundle', not uppercase

browserslistToTargets

✓ import { browserslistToTargets } from 'lightningcss-wasm'

Converts a browserslist query to Lightning CSS targets; requires browserslist package installed

ComposeVisitor

✓ import { ComposeVisitor } from 'lightningcss-wasm'

Type for custom visitors, exported as a class constructor

CustomAtRule

✓ import { CustomAtRule } from 'lightningcss-wasm'

Type for custom at-rule visitors

Minifies a CSS string with Lightning CSS, converting rgba to hex shorthand, shortening transition duration, and removing vendor prefixes not needed for target browsers.

import { transform, browserslistToTargets } from 'lightningcss-wasm'; const code = ` .example { color: rgba(255, 0, 0, 0.5); background: linear-gradient(45deg, red 0%, blue 50%); transition: all 200ms; } `; const { code: minified } = transform({ code: new TextEncoder().encode(code), minify: true, targets: browserslistToTargets('>= 0.25%'), }); console.log(new TextDecoder().decode(minified)); // Output: .example{color:rgba(255,0,0,.5);background:linear-gradient(45deg,red,blue 50%);transition:all .2s}

Debug

Known issues

breakingIn v1.0.0, the API changed from accepting a string to a Uint8Array for the `code` option in `transform` and `bundle`.

fix

Encode your CSS string to a Uint8Array using `new TextEncoder().encode(code)` before passing.

affects: >=1.0.0

deprecatedThe `css_modules` option has been deprecated since v1.10.0; use `cssModules` instead (camelCase).

fix

Use `cssModules: true` instead of `css_modules: true`.

affects: >=1.10.0

gotchaThe WASM file is large (~3-4 MB) and must be loaded synchronously or asynchronously; using the package in a browser requires manual instantiation or a bundler.

fix

In browsers, use a bundler that supports WASM (e.g., webpack with asyncWasm) or load via `@parcel/wasm` helper.

affects: >=0.1.0

gotchaCustom visitors (like `@custom-selector`) require the `customAtRules` option and are not available in the simple `transform` call; you must use `bundle` or lower-level API.

fix

Use the `bundle` function with `resolver` for custom at-rules, or use the `visitor` option in `transform`.

affects: >=0.5.0

Errors

Common errors & fixes

TypeError: options.code is not an array-like or an ArrayBuffer

Passing a string to `code` instead of a Uint8Array in v1+.

fix

Encode the string: `new TextEncoder().encode(cssString)`

Error: Lightning CSS failed to parse stylesheet due to unknown at-rule `@custom-selector`

Using `@custom-selector` without specifying custom at-rules in the options.

fix

Add `customAtRules: { customSelector: { prelude: '<custom-selector>', body: '<declaration-list>' } }` to the transform options.

ReferenceError: require is not defined in ES module scope, you can use import instead

Using CommonJS require in an ESM project.

fix

Use `import { transform } from 'lightningcss-wasm'` instead of `require('lightningcss-wasm')`.

Error: Cannot find module 'lightningcss-wasm'

Package not installed or path incorrect.

fix

Run `npm install lightningcss-wasm` and ensure your import is `from 'lightningcss-wasm'`.

Upgrade

Version history

1.32.0latest on npm

Audit

Dependencies

browserslistoptionalOptional, used for reading browserslist configuration if no targets provided

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/parcel-bundler/lightningcss ↗

packagelightningcss-wasm ↗

homepagehttps://github.com/parcel-bundler/lightningcss#readme ↗