LightningCSS (Linux x64 GNU Native Binding)

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/lightningcss/lib/index.js not supported. /path/to/your/file.js is a CommonJS module file. You can convert this file to an ES module by adding "type": "module" to its package.json or using the .mjs extension.

  cause Attempting to `require()` the `lightningcss` package from a CommonJS module, but `lightningcss` is an ES Module. [15]
  fix Migrate your project or the offending file to use ES Modules by adding `"type": "module"` to your `package.json` or changing the file extension to `.mjs`. Then, update `require()` calls to `import` statements (e.g., `import { transform } from 'lightningcss';`).

• TypeError: code must be a Buffer

  cause `lightningcss.transform` or `lightningcss.bundle` received input CSS as a string instead of the required `Buffer` object. [2]
  fix Convert your CSS string to a Node.js `Buffer` before passing it to the `code` option. Example: `code: Buffer.from(yourCssString)`. For browser/Deno environments using `lightningcss-wasm`, use `new TextEncoder().encode(yourCssString)`.

• CSS output includes prefixed properties for unsupported browsers or lacks transpilation for target browsers.

  cause The `browserslist` configuration is either missing, incorrect, or the `targets` option in `transform`/`bundle` is not correctly specified, leading to suboptimal output for desired browser compatibility. [8, 11]
  fix Ensure you have a `browserslist` entry in your `package.json` or `.browserslistrc` file. Alternatively, explicitly pass the `targets` option to `transform` or `bundle` with appropriate browser versions (e.g., `targets: { chrome: 100 << 16 }` for Chrome 100).

Warnings

• breaking Lightning CSS v1.30.0 introduced a breaking change in relative color parsing. The specification was updated to support numbers in addition to percentages, and `calc()` expressions in colors are now always treated as numbers. Code relying on previous percentage-based relative color calculations may need updating to use numbers instead. [changelog: 1.30.0]
  Fix: Review relative color calculations; update percentage values to numbers where applicable according to the latest CSS Color Module Level 5 specification. Consult `lightningcss` documentation for specific examples.
• gotcha This package, `lightningcss-linux-x64-gnu`, is a platform-specific native binding. End users typically install the main `lightningcss` package, which automatically selects and loads the correct native module for their system. Manually installing or forcing this specific binding may lead to unexpected runtime errors or build issues if the environment does not match, or if `lightningcss` expects to manage its native dependencies dynamically. [5, 6, 7]
  Fix: Always install the umbrella `lightningcss` package (`npm install lightningcss`) and let it manage the appropriate native bindings for your target environment. Only install specific bindings directly for advanced, platform-constrained deployment scenarios.
• gotcha The main `lightningcss` library is primarily an ES Module (ESM). Attempting to use `require()` for imports in a CommonJS (CJS) environment can lead to `ERR_REQUIRE_ESM` errors, especially in Node.js versions that have stricter ESM/CJS interoperability rules. [15]
  Fix: Ensure your project is configured for ES Modules (e.g., `"type": "module"` in `package.json`, using `.mjs` extensions) and use `import` statements. If a CJS environment is strictly required, investigate dynamic `import()` or dual-package strategies, though direct `require()` is generally not supported for ESM-only packages. [14]
• gotcha While Lightning CSS offers a powerful visitor API for custom transforms, implementing these in JavaScript can incur a significant performance overhead, potentially making compilation around 2x slower compared to transformations performed natively in Rust. [3]
  Fix: Minimize the complexity and frequency of JS visitor calls. Optimize visitor logic for performance. Consider if the custom transform can be achieved through configuration options or if the performance impact is acceptable for your build process.

Install

• npm install lightningcss-linux-x64-gnu npm
• yarn add lightningcss-linux-x64-gnu yarn
• pnpm add lightningcss-linux-x64-gnu pnpm

Imports

• transform
  wrong:

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

  correct:

  import { transform } from 'lightningcss';

  The primary `lightningcss` package is predominantly ESM. While CommonJS `require()` might work for some versions or setups, ESM `import` is the recommended and more robust pattern to avoid `ERR_REQUIRE_ESM` issues. This specific `*-linux-x64-gnu` package is a native dependency loaded by the main `lightningcss` package, not directly imported by userland code. [2, 13, 15]
• bundle
  wrong:

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

  correct:

  import { bundle } from 'lightningcss';

  `bundle` is used for processing `@import` rules and inlining them. Similar to `transform`, favor ESM `import` for consistency and compatibility with the `lightningcss` API. [2]
• Features

  import { Features } from 'lightningcss';

  Used for configuring advanced transpilation features like enabling/disabling specific CSS draft syntaxes, independent of browser targets. Often used with bitwise OR for multiple flags. [8]

Quickstart

Demonstrates how to use the `transform` function to minify CSS, apply vendor prefixes, lower syntax (like `oklab` colors and nesting) for specified browser targets, and generate a source map. This example shows processing modern CSS features like nesting and custom media queries. [2, 8, 10, 11]

import { transform, Features } from 'lightningcss';
import { Buffer } from 'node';

const cssInput = `
  @media (width <= 500px) {
    .container {
      display: flex;
      color: oklab(59.686% 0.1009 0.1192);
    }
  }
  .button {
    background-color: #3498db;
    &:hover {
      background-color: darken(#3498db, 10%);
    }
  }
`;

async function processCss() {
  try {
    const { code, map } = transform({
      filename: 'input.css',
      code: Buffer.from(cssInput),
      minify: true,
      sourceMap: true,
      targets: {
        chrome: 100 << 16, // Chrome 100
        firefox: 90 << 16, // Firefox 90
        safari: 15 << 16   // Safari 15
      },
      drafts: { 
        nesting: true, 
        customMedia: true 
      }, // Enable CSS nesting and custom media queries [2, 8, 11]
      // Additional features can be enabled with bitwise OR, e.g., include: Features.Colors
    });

    console.log('Minified CSS:');
    console.log(code.toString());
    console.log('\nSource Map (base64):');
    console.log(map?.toString('base64'));
  } catch (error) {
    console.error('Error processing CSS:', error);
  }
}

processCss();