LightningCSS: High-Performance CSS Toolchain for Linux ARM

Common errors

• Error: Cannot find module '../lightningcss.darwin-arm64.node' (or similar platform-specific .node file)

  cause The native binary for LightningCSS specific to your operating system and architecture was not found or correctly loaded, often due to an incomplete or incorrect `npm install` for native modules.
  fix First, clear your `node_modules` and `package-lock.json` (or `yarn.lock`) and then reinstall: `rm -rf node_modules package-lock.json && npm install`. If the problem persists, verify your Node.js version is compatible and consider checking for specific OS dependencies like `VC_redist` on Windows.

• Error [ERR_REQUIRE_ESM]: require() of ES Module <path>/lightningcss/node/index.js not supported

  cause You are attempting to use `require()` to import LightningCSS, but it is primarily an ES Module (ESM). CommonJS `require()` cannot directly load ESM modules.
  fix Update your import statements from `const { transform } = require('lightningcss');` to `import { transform } from 'lightningcss';`. Ensure your project's `package.json` either specifies `"type": "module"` or uses `.mjs` file extensions for ESM.

Warnings

• breaking In version 1.30.0, the parsing for relative colors was updated to align with the latest CSS spec. This change now supports numbers in addition to percentages and ensures `calc()` expressions within colors are always treated as numbers. Code relying on previous relative color calculations with percentages may need updates to use numbers instead.
  Fix: Review CSS code using relative color calculations, especially those involving percentages. Update `calc()` expressions and color values to conform to the updated spec, explicitly using numbers where appropriate.
• breaking Version 1.30.0 also introduced updates to the CSS nesting implementation to adhere to the latest spec. This change allows for more flexible nesting patterns, including selectors with pseudo-elements and direct nesting of declarations and rules. While generally an improvement, existing CSS with complex nesting might behave differently or require adjustments.
• gotcha Users employing Node.js worker threads on Linux experienced crashes with earlier versions of LightningCSS. This was addressed in v1.30.1. Ensure you are on a compatible version if running LightningCSS within worker threads to prevent unexpected process exits.
  Fix: Upgrade LightningCSS to version 1.30.1 or newer to resolve the worker thread crash on Linux.
• gotcha Custom resolvers for bundling (`bundleAsync` API) and visitor functions for custom transforms received enhancements in v1.32.0 and v1.31.0, respectively. While these add powerful capabilities (e.g., marking imports as external, adding dependencies), users with existing custom logic should verify compatibility and consider leveraging new features for improved control.
  Fix: Consult the official LightningCSS documentation for updated guidance on custom resolvers and visitor API usage, especially if upgrading from older versions with custom plugins.
• gotcha As `lightningcss-linux-arm-gnueabihf` is a platform-specific native binding, incorrect environment setup or `npm` configuration can lead to runtime errors where the native module cannot be found. This is a common issue for native Node.js modules, especially on ARM platforms or when `npm` fails to install the correct binary.
  Fix: Ensure `npm` cache is clean and try reinstalling `lightningcss`. Verify your Node.js version is compatible with the installed native binary. If issues persist, manually ensure the correct platform-specific package (e.g., `lightningcss-linux-arm-gnueabihf`) is correctly resolved and installed by the main `lightningcss` package, or address potential `browserslist` misconfigurations if using tools like TailwindCSS that rely on LightningCSS.

Install

• npm install lightningcss-linux-arm-gnueabihf npm
• yarn add lightningcss-linux-arm-gnueabihf yarn
• pnpm add lightningcss-linux-arm-gnueabihf pnpm

Imports

• transform
  wrong:

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

  correct:

  import { transform } from 'lightningcss';

  LightningCSS is primarily consumed as an ES Module. While Node.js has robust ESM support, explicit `import` statements are recommended. `require()` may work in some setups but can lead to issues with certain configurations or tools.
• bundle
  wrong:

  import bundle from 'lightningcss';

  correct:

  import { bundle } from 'lightningcss';

  `bundle` is a named export, not a default export. This function is used to process CSS `@import` rules and inline them, requiring filesystem access.
• browserslistToTargets

  import { browserslistToTargets } from 'lightningcss';

  This helper function converts a browserslist query into the `targets` object required by LightningCSS for intelligent transpilation and prefixing. It's often used alongside the `browserslist` npm package.
• Features

  import { Features } from 'lightningcss';

  The `Features` enum allows selective inclusion or exclusion of specific CSS features during transformation, useful for fine-grained control over output compatibility.

Quickstart

This quickstart demonstrates how to use LightningCSS to parse, minify, and transpile modern CSS syntax (like nesting, custom media queries, and OKLAB colors) for specified browser targets, including source map generation.

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

const cssInput = `
  @media (width <= 600px) {
    .card {
      display: grid;
      gap: 1rem;
      color: oklab(59.686% 0.1009 0.1192);
      @nest &::before {
        content: 'Mobile view';
      }
    }
  }
  .container { width: clamp(200px, 50%, 800px); }
`;

// Define browser targets using browserslist
const targets = browserslistToTargets(browserslist('last 2 versions, > 0.2%'));

try {
  const { code, map } = transform({
    filename: 'input.css',
    code: Buffer.from(cssInput),
    minify: true,
    sourceMap: true,
    targets,
    drafts: {
      nesting: true,
      customMedia: true
    }
  });

  console.log('Transformed and minified CSS:\n', code.toString());
  // console.log('Source Map:\n', map?.toString());

  // Example for bundling (requires a file on disk)
  // import { bundle } from 'lightningcss';
  // const { code: bundledCode } = bundle({
  //   filename: 'path/to/entry.css',
  //   minify: true,
  //   targets,
  // });
  // console.log('Bundled CSS:\n', bundledCode.toString());

} catch (error) {
  console.error('Error transforming CSS:', error);
}