Lightning CSS (Linux x64 Musl)

Common errors

• Error: Cannot find module 'lightningcss' or its corresponding type declarations.

  cause Attempting to `import` or `require` `lightningcss` when it's not installed or incorrectly resolved. This specific package (`lightningcss-linux-x64-musl`) is a native binding, not the main JavaScript API.
  fix Ensure `npm install lightningcss` has been run. The main `lightningcss` package will then correctly pull in the platform-specific native dependency.

• Error: Failed to load native binding

  cause The JavaScript wrapper in `lightningcss` could not find or load the appropriate native binary for your system, or the binary itself is corrupted/incompatible.
  fix This often indicates a mismatch between your system's architecture/OS/libc and the installed native `lightningcss-*-*` package. Try `npm rebuild lightningcss` or delete `node_modules` and `package-lock.json` then reinstall. Verify your Node.js version meets the `engines` requirement (Node.js >= 12.0.0).

• TypeError: Cannot read properties of undefined (reading 'transform')

  cause This error occurs if the `transform` function is not properly imported or the `lightningcss` module did not initialize correctly, likely due to a failure in loading the native binding.
  fix First, address any 'Failed to load native binding' errors. Ensure your `import { transform } from 'lightningcss';` statement is correct and that the main `lightningcss` package is installed and functional.

• Error: The `code` option must be a Buffer.

  cause The `transform` and `bundle` functions in `lightningcss` expect the `code` option to be a Node.js `Buffer` object, not a string.
  fix Convert your CSS string to a Buffer before passing it: `code: Buffer.from(yourCssString)`.

Warnings

• gotcha This package, `lightningcss-linux-x64-musl`, is a platform-specific native addon. It is generally not intended for direct use but should be installed as an `optionalDependency` or `peerDependency` of the main `lightningcss` package. Direct installation of only this package without `lightningcss` will not provide the JavaScript API.
  Fix: Install the main `lightningcss` package which will automatically handle installing the correct native binding for your platform as an optional dependency.
• breaking In v1.30.0, the relative color parsing was updated to the latest CSS spec. This change means `calc()` functions within colors now always resolve to numbers instead of percentages, and numbers are supported in addition to percentages. If your CSS uses relative color calculations with percentages, you may need to update them to use numbers instead.
  Fix: Review CSS code utilizing relative color syntax introduced in `color-mix` or similar functions, and adjust percentage values to numbers where applicable according to the updated spec.
• gotcha Lightning CSS relies on native binaries. If you encounter errors related to missing shared libraries or incorrect architecture, ensure you have the correct platform-specific package (e.g., `-linux-x64-gnu`, `-win32-x64`, `-darwin-arm64`) installed. The `detect-libc` library is used to choose the correct `libc` variant (e.g., `musl` vs. `gnu`) on Linux.
  Fix: Ensure `lightningcss` is installed correctly, allowing `npm` or `yarn` to pick the right optional dependency. If issues persist, manually ensure `lightningcss-<platform>-<arch>-<libc>` matching your system is present, or try removing `node_modules` and reinstalling.
• breaking The nesting implementation was updated in v1.30.0 to align with the new CSS Nesting spec, allowing selectors with pseudo-elements and more flexible nesting of declarations and rules. While generally an enhancement, this might subtly change how previously supported but non-standard nesting patterns are parsed or interpreted.
  Fix: Verify existing CSS nesting patterns, especially those involving pseudo-elements, for compatibility with the updated spec. Refer to the official CSS Nesting specification for current behavior.

Install

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

Imports

• transform
  wrong:

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

  correct:

  import { transform } from 'lightningcss';

  The main `lightningcss` package exports named functions. While CommonJS `require` might work with transpilation, direct ESM imports are preferred. This `lightningcss-linux-x64-musl` package is an internal dependency, not directly imported.
• bundle

  import { bundle } from 'lightningcss';

  Used for bundling CSS with `@import` resolution. Similar to `transform`, this is imported from the main `lightningcss` package.
• browserslistToTargets

  import { browserslistToTargets } from 'lightningcss';

  A utility function to convert a Browserslist query into a target object compatible with `transform` and `bundle` options.

Quickstart

This quickstart demonstrates basic CSS transformation and minification using `lightningcss`. It includes setting browser targets, generating a source map, and shows a simple custom `@import` resolver. It will utilize the native `lightningcss-linux-x64-musl` build if installed as a dependency of `lightningcss`.

import { transform, browserslistToTargets } from 'lightningcss';
import * as browserslist from 'browserslist';

const cssInput = `
  @import "./base.css";
  :root {
    --primary-color: #007bff;
  }
  .container {
    display: flex;
    gap: 10px;
    @media (min-width: 768px) {
      flex-direction: row;
    }
    @media (max-width: 767px) {
      flex-direction: column;
    }
  }
  .button {
    background-color: var(--primary-color);
    color: white;
    padding: 10px 20px;
    border-radius: 5px;
  }
`;

const targets = browserslistToTargets(browserslist('>= 0.25%'));

async function processCss() {
  try {
    const { code, map } = await transform({
      filename: 'input.css',
      code: Buffer.from(cssInput),
      minify: true,
      sourceMap: true,
      targets,
      cssModules: false,
      // Example custom resolver for @import (synchronous)
      resolver: {
        resolve(specifier, from) {
          if (specifier === './base.css') {
            return {
              filePath: 'base.css',
              contents: Buffer.from('body { margin: 0; }')
            };
          }
          return null;
        }
      }
    });

    console.log('Transformed CSS:\n', code.toString());
    // console.log('Source Map:\n', map?.toString());
  } catch (e) {
    console.error('Error transforming CSS:', e);
  }
}

processCss();