Lightning CSS (macOS x64)

Common errors

• Error: Cannot find module 'lightningcss-darwin-x64'

  cause The native binary for your operating system and architecture could not be found or loaded by the main `lightningcss` package.
  fix Ensure `npm install` (or `yarn install`, `pnpm install`) completed successfully. This error often occurs if the correct platform-specific package wasn't installed, if `node_modules` is corrupted, or if the `postinstall` script failed. Try `npm rebuild lightningcss` or delete `node_modules` and `package-lock.json` and reinstall.

• The 'browsers' option is required for autoprefixing.

  cause The `transform` or `bundle` function was called with options that require browser targets (e.g., `minify: true`, `sourceMap: true`, or specific feature flags for transpilation) but no `targets` object was provided.
  fix Provide a `targets` object derived from a `browserslist` query using `browserslistToTargets`. Example: `targets: browserslistToTargets(browserslist('>= 0.25%'))`.

• SyntaxError: <css input>: Unexpected token '<some_css_token>'

  cause The input CSS contains a syntax error, uses an unsupported draft feature without enabling it, or contains syntax that Lightning CSS's parser cannot understand.
  fix Check the CSS input for typos or invalid syntax. If using a modern CSS draft feature (e.g., nesting, custom media queries), ensure it is explicitly enabled in the `transform` or `bundle` options, for example, `drafts: { nesting: true }`.

Warnings

• breaking Version 1.30.0 introduced breaking changes related to relative color parsing and calculation. The spec now supports numbers instead of percentages, and `calc()` expressions in colors are always treated as numbers. Code relying on old relative color calculations might need updates.
  Fix: Update relative color calculations in CSS to align with the latest spec, using numbers instead of percentages where applicable for color functions like `lch()`, `oklch()`, `lab()`, `oklab()`, and `color-mix()`.
• gotcha As a native module written in Rust, `lightningcss-darwin-x64` (and other platform-specific variants) can sometimes encounter installation issues related to system dependencies, Node.js version mismatches, or incorrect platform detection by npm/yarn, leading to `Module not found` errors or build failures.
  Fix: Ensure Node.js version meets the `engines` requirement (currently `>= 12.0.0`). Verify that `npm install` successfully downloads the correct platform-specific package. For persistent issues, clear `node_modules` and `npm cache clean --force`, then reinstall.
• gotcha Lightning CSS actively tracks and adopts the latest CSS specifications, including draft features like CSS nesting, relative colors, and view transitions. While this provides cutting-edge support, it means that changes in these specs can lead to subtle or breaking changes in how your CSS is processed.
  Fix: Refer to the official Lightning CSS changelog and documentation with each major or minor update to understand any spec-driven behavior changes that might affect your CSS code or build process.
• gotcha In Node.js environments, particularly when using worker threads, earlier versions of Lightning CSS experienced crashes on process exit on Linux. While a fix was released in v1.30.1, it highlights potential stability issues when integrating native modules into complex, multi-threaded Node.js applications.
  Fix: Ensure you are on Lightning CSS v1.30.1 or newer. When using native modules in Node.js worker threads, monitor memory usage and process stability closely, and always test across target environments.
• gotcha Starting with v1.32.0, custom resolvers can explicitly mark `@import` rules as external by returning `{ external: string }`. This will leave the `@import` in the output CSS instead of bundling it, which changes default bundling behavior for affected imports if custom resolvers are in use.
  Fix: If using custom resolvers with `bundle` or `bundleAsync`, review their logic to ensure they handle the `external` option as intended. Adjust resolver returns if all `@import` statements are expected to be inlined.
• gotcha While Lightning CSS can replace many PostCSS plugins (like Autoprefixer and `postcss-preset-env`), it may not fully replace all custom PostCSS setups. Integrating both `lightningcss-loader` and `postcss-loader` requires careful configuration, as some PostCSS features might be overridden or become incompatible.
  Fix: Evaluate your PostCSS plugins to determine if Lightning CSS natively supports their functionality. If custom PostCSS plugins are essential, use `lightningcss-loader` alongside `postcss-loader` but be aware of potential conflicts and ensure correct loader order in your build configuration.

Install

• npm install lightningcss-darwin-x64 npm
• yarn add lightningcss-darwin-x64 yarn
• pnpm add lightningcss-darwin-x64 pnpm

Imports

• transform
  wrong:

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

  correct:

  import { transform } from 'lightningcss';

  The `transform` function compiles a single CSS stylesheet. For ESM-only projects, `import` is standard. CommonJS `require` can be used in Node.js environments that support it, but ESM is increasingly preferred.
• bundle
  wrong:

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

  correct:

  import { bundle } from 'lightningcss';

  `bundle` is used for processing `@import` rules and CSS Modules, requiring filesystem access. It operates on a filename rather than a direct code buffer.
• browserslistToTargets
  wrong:

  import browserslistToTargets from 'lightningcss/browserslistToTargets';

  correct:

  import { browserslistToTargets } from 'lightningcss';

  This utility converts a Browserslist query string into the `targets` object format expected by `transform` and `bundle` for transpilation. It should be imported directly as a named export.
• TransformOptions

  import type { TransformOptions } from 'lightningcss';

  For TypeScript users, import types for configuration objects, such as `TransformOptions` or `CSSOptions`, to ensure type safety when interacting with the API.

Quickstart

This quickstart demonstrates how to use `lightningcss` to transform, minify, and transpile modern CSS features for specific browser targets, including generating a source map. It enables CSS nesting and custom media drafts.

import { transform, browserslistToTargets } from 'lightningcss';
import browserslist from 'browserslist';
import { Buffer } from 'node:buffer';

const cssInput = `
  :root {
    --color: oklch(50% 0.1 200);
  }
  @media (min-width: 768px) {
    .container {
      display: grid;
      grid-template-columns: 1fr 1fr;
    }
  }
  .text-red {
    color: var(--color);
    text-shadow: 1px 1px red;
  }
  .flex-center {
    display: flex;
    justify-content: center;
    align-items: center;
  }
`;

// Determine browser targets from a browserslist query
const targets = browserslistToTargets(browserslist('last 2 Chrome versions, Firefox ESR, Edge >= 90'));

try {
  const { code, map } = transform({
    filename: 'input.css',
    code: Buffer.from(cssInput),
    minify: true,
    targets, // Transpile modern CSS features for these browsers
    sourceMap: true,
    drafts: {
      nesting: true, // Enable CSS nesting support
      customMedia: true // Enable custom media queries
    }
  });

  console.log('Transformed and minified CSS:\n', Buffer.from(code).toString());
  console.log('\nSource Map:\n', Buffer.from(map).toString());
} catch (error) {
  console.error('Error transforming CSS:', error);
}