LightningCSS (Linux ARM64 Musl Native Build)

Common errors

• Error: Cannot find module 'lightningcss-linux-arm64-musl/lightningcss.node' (or similar path for other platforms)

  cause The native binary for your specific platform/architecture could not be found or loaded. This usually happens if the main `lightningcss` package failed to install the correct optional dependency, or if the environment's architecture/libc changed after installation.
  fix First, try reinstalling `lightningcss` to ensure the correct native module is fetched: `npm rebuild lightningcss`. If using Docker/containers, ensure the Node.js version and base image architecture (e.g., `arm64` vs `amd64`, `musl` vs `glibc`) are consistent.

• The 'lightningcss' package requires Node.js version >= 12.0.0.

  cause The installed Node.js version does not meet the minimum requirement specified in the package's `engines` field.
  fix Upgrade your Node.js runtime to version 12.0.0 or higher. The latest LTS release is generally recommended.

• Error: Failed to parse CSS: Expected a declaration, found 'something-unexpected' (at input.css:X:Y)

  cause The input CSS contains syntax errors or uses features not yet understood by LightningCSS without enabling specific draft flags.
  fix Review the CSS code at the indicated line and column for syntax errors. If using experimental or very new CSS features, ensure you have enabled the relevant `drafts` option (e.g., `drafts: { nesting: true }`) in the `transform` or `bundle` configuration.

Warnings

• breaking Version 1.30.0 introduced a breaking change by updating relative color parsing to the latest CSS specification. Code relying on previous interpretations of percentages in relative color calculations may need to be updated to use numbers instead.
  Fix: Review CSS code using relative color functions (e.g., `color-mix`, `color-contrast`) and adjust percentage values to numbers where the spec now requires it.
• gotcha This package (`lightningcss-linux-arm64-musl`) is a platform-specific native binary. While `lightningcss` itself handles installing the correct binary for your system, direct installation or misconfiguration (e.g., deploying on a different architecture/libc than compiled for) can lead to runtime errors due to missing or incompatible native modules.
  Fix: Ensure you `npm install lightningcss` rather than direct platform packages. If issues persist in containerized environments, verify the base image's architecture and C library (e.g., glibc vs. musl) match the installed binding, or explicitly specify the correct native package in your `package.json` overrides.
• gotcha LightningCSS tracks the latest CSS specifications closely. This means that features still in draft or undergoing changes in the W3C spec might behave differently between minor versions, especially when enabling draft features. This can occasionally lead to unexpected output or parsing errors if your CSS relies on an older draft behavior.
  Fix: Regularly check the `lightningcss` release notes for updates on spec changes and how they affect implemented features. Be mindful when using `drafts` options, as their behavior is subject to change.

Install

• npm install lightningcss-linux-arm64-musl npm
• yarn add lightningcss-linux-arm64-musl yarn
• pnpm add lightningcss-linux-arm64-musl pnpm

Imports

• transform
  wrong:

  const { transform } = require('lightningcss')

  correct:

  import { transform } from 'lightningcss'

  Main function for single-file CSS processing, minification, and transpilation. Primarily ESM, though CommonJS is also available.
• bundle
  wrong:

  const bundle = require('lightningcss').bundle

  correct:

  import { bundle } from 'lightningcss'

  Used for bundling multiple CSS files, resolving @import statements. Requires a resolver function for custom import handling.
• browserslistToTargets
  wrong:

  import browserslistToTargets from 'lightningcss/browserslistToTargets'

  correct:

  import { browserslistToTargets } from 'lightningcss'

  Utility to convert a Browserslist query array into the target format expected by `transform` and `bundle`.

Quickstart

Demonstrates how to use `lightningcss` to transform, minify, and transpile CSS code with browser targeting and draft feature enablement.

import { transform, browserslistToTargets } from 'lightningcss';

async function processCss() {
  const cssCode = `
    :root {
      --primary-color: #3498db;
    }
    .container {
      background-color: var(--primary-color);
      display: flex;
      gap: 10px;
      @media (min-width: 768px) {
        flex-direction: row;
      }
    }
    .button {
      padding: 10px 20px;
      color: white;
      background-color: var(--primary-color);
      transition: background-color 0.3s ease-in-out;
      &:hover {
        /* Example of nested selector and a CSS function */
        background-color: color-mix(in srgb, var(--primary-color) 80%, black);
      }
    }
  `;

  // Define target browsers using a Browserslist query
  const targets = browserslistToTargets(['last 2 Chrome versions', 'last 2 Firefox versions', 'Safari >= 15']);

  try {
    const { code, map } = transform({
      filename: 'input.css',
      code: Buffer.from(cssCode),
      minify: true,
      targets,
      // Enable draft features like nesting and custom media queries
      drafts: {
        nesting: true,
        customMedia: true,
      },
      // Uncomment to generate source map
      // sourceMap: true,
      // cssModules: { /* ... options for CSS Modules */ },
    });

    console.log('Minified and Transformed CSS:');
    console.log(code.toString());
    // if (map) {
    //   console.log('\nSource Map:');
    //   console.log(map.toString());
    // }
  } catch (error) {
    console.error('Error processing CSS:', error);
  }
}

processCss();