{"id":16845,"library":"lightningcss","title":"Lightning CSS","description":"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.","status":"active","version":"1.32.0","language":"javascript","source_language":"en","source_url":"https://github.com/parcel-bundler/lightningcss","tags":["javascript","typescript"],"install":[{"cmd":"npm install lightningcss","lang":"bash","label":"npm"},{"cmd":"yarn add lightningcss","lang":"bash","label":"yarn"},{"cmd":"pnpm add lightningcss","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { transform } = require('lightningcss');","symbol":"transform","correct":"import { transform } from 'lightningcss';"},{"note":"`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.","wrong":"const bundle = require('lightningcss').bundle;","symbol":"bundle","correct":"import { bundle } from 'lightningcss';"},{"note":"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.","wrong":null,"symbol":"browserslistToTargets","correct":"import { browserslistToTargets } from 'lightningcss';"}],"quickstart":{"code":"import { transform, browserslistToTargets } from 'lightningcss';\nimport * as browserslist from 'browserslist';\n\nconst cssInput = `\n  @custom-media --viewport-medium (width <= 800px);\n\n  :root {\n    --primary-color: oklch(50% 0.2 250);\n  }\n\n  .container {\n    display: flex;\n    gap: 10px;\n    @media (--viewport-medium) {\n      flex-direction: column;\n    }\n    background-color: color-mix(in srgb, var(--primary-color) 80%, black);\n    font-size: clamp(1rem, 2vw, 1.5rem);\n  }\n`;\n\nasync function processCss() {\n  const targets = browserslistToTargets(browserslist('>= 0.25%', 'not dead'));\n\n  const { code, map } = transform({\n    filename: 'input.css',\n    code: Buffer.from(cssInput),\n    minify: true,\n    targets,\n    nesting: true, // Enable CSS Nesting syntax lowering\n    customMedia: true, // Enable Custom Media Query syntax lowering\n    drafts: { // Enable experimental draft features like Color Level 5\n      'nesting': true,\n      'customMedia': true,\n      'css-color-5': true\n    },\n    sourceMap: true\n  });\n\n  console.log('Minified CSS:');\n  console.log(code.toString());\n  console.log('\\nSource Map (first 100 chars):');\n  console.log(map?.toString().substring(0, 100));\n}\n\nprocessCss();\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Review any relative color calculations (e.g., `lab(from purple calc(l * .8) a b)`) that use percentages and update them to use numbers where appropriate, following the updated CSS Color Level 5 specification.","message":"In 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.","severity":"breaking","affected_versions":">=1.30.0"},{"fix":"Ensure your Node.js environment is version 12.0.0 or higher. You can update Node.js using `nvm` or by installing a newer version directly.","message":"The `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.","severity":"gotcha","affected_versions":"<12.0.0"},{"fix":"If encountering installation or runtime errors on specific platforms, first ensure you are on the latest patch version of `lightningcss`. If issues persist, check the GitHub issues for similar reports or open a new one with your environment details.","message":"Due 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.","severity":"gotcha","affected_versions":"all"},{"fix":"Provide a custom `resolver` function to the `bundle` options if your `@import` paths are not standard file system paths, or if you need to handle external imports. Ensure all imported CSS files exist and are accessible.","message":"When 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.","severity":"gotcha","affected_versions":"all"},{"fix":"Migrate from the deprecated `@value` at-rule to modern CSS Custom Properties or other CSS Module features that align with current specifications.","message":"The `@value` at-rule of CSS Modules has been deprecated and `lightningcss` will issue a warning if it encounters it during processing.","severity":"deprecated","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`) and use `import { ... } from 'lightningcss';`. If you must use CommonJS, ensure your bundler or Node.js version is configured to correctly handle dual CJS/ESM packages, or use dynamic `import('lightningcss')`.","cause":"Attempting to import `lightningcss` using CommonJS `require()` syntax in an environment configured for ESM, or an incorrect package path.","error":"Error: Cannot find module 'lightningcss'"},{"fix":"Check the `lightningcss` documentation and release notes for support of the specific feature. If it's a draft feature, you might need to explicitly enable it via the `drafts` option in `transform` or `bundle` configuration (e.g., `drafts: { 'css-nesting': true }`). If it's not supported, consider a polyfill or waiting for a future release.","cause":"You are using a very new or experimental CSS pseudo-class/element that `lightningcss` doesn't yet support out of the box, or it requires enabling a specific 'draft' feature.","error":"Error: Unknown pseudo-class or pseudo-element '::some-new-pseudo'"},{"fix":"Ensure you are passing a valid `targets` array to the `transform` or `bundle` function. This often involves using `browserslistToTargets(browserslist(YOUR_BROWSERSLIST_QUERY))` to generate the correct targets. Verify your Browserslist query correctly includes the desired browsers and versions.","cause":"The `targets` option, which specifies the target browsers for prefixing and syntax lowering, is either missing, incorrect, or doesn't cover the browsers where the features need to be transformed.","error":"Minified output does not include expected vendor prefixes or syntax lowering."}],"ecosystem":"npm","meta_description":null}