Lightning CSS

Common errors

• Error: Cannot find module 'lightningcss'

  cause Attempting to import `lightningcss` using CommonJS `require()` syntax in an environment configured for ESM, or an incorrect package path.
  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')`.

• Error: Unknown pseudo-class or pseudo-element '::some-new-pseudo'

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

• Minified output does not include expected vendor prefixes or syntax lowering.

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

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• deprecated The `@value` at-rule of CSS Modules has been deprecated and `lightningcss` will issue a warning if it encounters it during processing.
  Fix: Migrate from the deprecated `@value` at-rule to modern CSS Custom Properties or other CSS Module features that align with current specifications.

Install

• npm install lightningcss npm
• yarn add lightningcss yarn
• pnpm add lightningcss pnpm

Imports

• transform
  wrong:

  const { transform } = require('lightningcss');

  correct:

  import { transform } from 'lightningcss';

  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.
• bundle
  wrong:

  const bundle = require('lightningcss').bundle;

  correct:

  import { bundle } 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.
• browserslistToTargets

  import { browserslistToTargets } 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.

Quickstart

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();