lightningcss

library1.32.0jsnpmunverified

Lightning CSS is an exceptionally fast CSS parser, transformer, and minifier written in Rust, primarily maintained by the Parcel team. Currently at version 1.32.0, it undergoes active development with frequent minor and patch releases, ensuring up-to-date feature support and performance improvements. Its key differentiators include leveraging Rust for unparalleled performance, a browser-grade parser (based on Mozilla's `cssparser` and `selectors` crates), and sophisticated typed property values that ensure consistent and accurate transformations across various CSS features. Beyond basic minification, it performs advanced optimizations such as combining longhand properties into shorthands, merging adjacent rules, and reducing `calc()` expressions. It also provides robust vendor prefixing based on configurable browser targets (integrating with Browserslist) and comprehensive syntax lowering for modern CSS features like CSS Nesting, Custom Media Queries, and advanced Color Level 4/5 functions, enabling developers to write modern CSS while ensuring broad browser compatibility and optimized output size.

web-framework serialization

github ↗package ↗homepage ↗

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.

The `lightningcss` package is primarily distributed as an ESM module, though CJS is available. For modern Node.js and bundler environments, prefer ESM imports. For CJS, ensure your toolchain supports it or use dynamic import.

import { transform } from 'lightningcss';

`bundle` is used for processing `@import` rules, which might require asynchronous operations (e.g., file system access). It can be used directly or passed to a build tool's configuration.

import { bundle } from 'lightningcss';

This utility function converts a Browserslist query into the specific target format expected by `lightningcss` functions like `transform` and `bundle`. It's essential for configuring browser compatibility.

import { browserslistToTargets } from 'lightningcss';

This example demonstrates how to use `lightningcss` to parse, minify, apply vendor prefixes, and lower modern CSS syntax (like nesting, custom media, and advanced color functions) for broad browser compatibility, while generating a source map.

import { transform, browserslistToTargets } from 'lightningcss'; import * as browserslist from 'browserslist'; const cssInput = ` @custom-media --viewport-medium (width <= 800px); :root { --primary-color: oklch(50% 0.2 250); } .container { display: flex; gap: 10px; @media (--viewport-medium) { flex-direction: column; } background-color: color-mix(in srgb, var(--primary-color) 80%, black); font-size: clamp(1rem, 2vw, 1.5rem); } `; async function processCss() { const targets = browserslistToTargets(browserslist('>= 0.25%', 'not dead')); const { code, map } = transform({ filename: 'input.css', code: Buffer.from(cssInput), minify: true, targets, nesting: true, // Enable CSS Nesting syntax lowering customMedia: true, // Enable Custom Media Query syntax lowering drafts: { // Enable experimental draft features like Color Level 5 'nesting': true, 'customMedia': true, 'css-color-5': true }, sourceMap: true }); console.log('Minified CSS:'); console.log(code.toString()); console.log('\nSource Map (first 100 chars):'); console.log(map?.toString().substring(0, 100)); } processCss();

lightningcss --version

Debug

Known footguns

breakingIn v1.30.0, the parsing of relative color syntax was updated to align with the latest CSS spec. This change specifically affects how numbers and percentages are handled in relative color calculations, where percentages might now need to be expressed as numbers. Existing code using relative color calculations with percentages may require updates.

gotchaThe `lightningcss` package has Node.js engine requirements (Node.js >= 12.0.0). Using older Node.js versions may lead to installation failures or runtime errors, as the native Rust binaries might not be compatible.

gotchaDue to its Rust implementation, `lightningcss` ships native binaries. While generally robust, specific environments (e.g., certain Linux distributions, ARM-based systems, or Node.js worker threads) have historically seen isolated installation or runtime issues that required targeted fixes.

gotchaWhen bundling CSS with `@import` rules using the `bundle` function, `lightningcss` needs to resolve these imports. Incorrect `resolver` configuration or missing files will lead to build failures or unresolved `@import` statements in the output.

deprecatedThe `@value` at-rule of CSS Modules has been deprecated and `lightningcss` will issue a warning if it encounters it during processing.

Upgrade

Version history

Breaking-change detection hasn't run for this library yet.

Audit

Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity

0 hits · last 30 days

No traffic data recorded yet.

Resources

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

packagehttps://www.npmjs.com/package/lightningcss ↗

homepagehttps://lightningcss.dev ↗