{"id":15684,"library":"lightningcss-linux-x64-gnu","title":"LightningCSS (Linux x64 GNU Native Binding)","description":"lightningcss-linux-x64-gnu is a platform-specific native Node.js binding for Lightning CSS, an extremely fast CSS parser, transformer, bundler, and minifier written in Rust. It serves as the underlying native module for Linux x64 GNU systems when using the main `lightningcss` npm package. Lightning CSS, currently at version 1.32.0 and released frequently (typically minor versions every few weeks), is known for its exceptional performance, often outperforming JavaScript-based tools by over 100x. Key differentiators include its Rust foundation, browser-grade parsing based on Mozilla's `cssparser` and `selectors` crates, advanced minification techniques (shorthands, merging rules, reducing `calc()` expressions), automatic vendor prefixing, syntax lowering for modern CSS features (like nesting, custom media, high gamut colors) based on `browserslist` targets, and robust support for CSS Modules with local scoping and tree-shaking capabilities. [1, 2, 8, 10, 11]","status":"active","version":"1.32.0","language":"javascript","source_language":"en","source_url":"https://github.com/parcel-bundler/lightningcss","tags":["javascript"],"install":[{"cmd":"npm install lightningcss-linux-x64-gnu","lang":"bash","label":"npm"},{"cmd":"yarn add lightningcss-linux-x64-gnu","lang":"bash","label":"yarn"},{"cmd":"pnpm add lightningcss-linux-x64-gnu","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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]","wrong":"const { transform } = require('lightningcss');","symbol":"transform","correct":"import { transform } from 'lightningcss';"},{"note":"`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]","wrong":"const { bundle } = require('lightningcss');","symbol":"bundle","correct":"import { bundle } from 'lightningcss';"},{"note":"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]","symbol":"Features","correct":"import { Features } from 'lightningcss';"}],"quickstart":{"code":"import { transform, Features } from 'lightningcss';\nimport { Buffer } from 'node';\n\nconst cssInput = `\n  @media (width <= 500px) {\n    .container {\n      display: flex;\n      color: oklab(59.686% 0.1009 0.1192);\n    }\n  }\n  .button {\n    background-color: #3498db;\n    &:hover {\n      background-color: darken(#3498db, 10%);\n    }\n  }\n`;\n\nasync function processCss() {\n  try {\n    const { code, map } = transform({\n      filename: 'input.css',\n      code: Buffer.from(cssInput),\n      minify: true,\n      sourceMap: true,\n      targets: {\n        chrome: 100 << 16, // Chrome 100\n        firefox: 90 << 16, // Firefox 90\n        safari: 15 << 16   // Safari 15\n      },\n      drafts: { \n        nesting: true, \n        customMedia: true \n      }, // Enable CSS nesting and custom media queries [2, 8, 11]\n      // Additional features can be enabled with bitwise OR, e.g., include: Features.Colors\n    });\n\n    console.log('Minified CSS:');\n    console.log(code.toString());\n    console.log('\\nSource Map (base64):');\n    console.log(map?.toString('base64'));\n  } catch (error) {\n    console.error('Error processing CSS:', error);\n  }\n}\n\nprocessCss();","lang":"typescript","description":"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]"},"warnings":[{"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.","message":"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]","severity":"breaking","affected_versions":">=1.30.0"},{"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.","message":"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]","severity":"gotcha","affected_versions":">=1.0.0"},{"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]","message":"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]","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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]","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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';`).","cause":"Attempting to `require()` the `lightningcss` package from a CommonJS module, but `lightningcss` is an ES Module. [15]","error":"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."},{"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)`.","cause":"`lightningcss.transform` or `lightningcss.bundle` received input CSS as a string instead of the required `Buffer` object. [2]","error":"TypeError: code must be a Buffer"},{"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).","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]","error":"CSS output includes prefixed properties for unsupported browsers or lacks transpilation for target browsers."}],"ecosystem":"npm"}