{"id":15681,"library":"lightningcss-darwin-x64","title":"Lightning CSS (macOS x64)","description":"lightningcss-darwin-x64 is the platform-specific native binary build of Lightning CSS for macOS x64 systems. Lightning CSS is an extremely fast, Rust-written CSS parser, transformer, minifier, and bundler. It is a core component in tools like Parcel and can also be used as a standalone library or CLI. The library currently ships with version 1.32.0. It offers advanced features such as vendor prefixing, syntax lowering to support older browsers, CSS Modules compilation, and support for modern CSS features like container queries, view transitions, and relative color syntax, often adopting the latest CSS specification drafts. Releases are frequent, reflecting ongoing development and adherence to evolving CSS standards. Its key differentiator is its performance, often outperforming JavaScript-based alternatives due to its Rust implementation.","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-darwin-x64","lang":"bash","label":"npm"},{"cmd":"yarn add lightningcss-darwin-x64","lang":"bash","label":"yarn"},{"cmd":"pnpm add lightningcss-darwin-x64","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `transform` function compiles a single CSS stylesheet. For ESM-only projects, `import` is standard. CommonJS `require` can be used in Node.js environments that support it, but ESM is increasingly preferred.","wrong":"const { transform } = require('lightningcss');","symbol":"transform","correct":"import { transform } from 'lightningcss';"},{"note":"`bundle` is used for processing `@import` rules and CSS Modules, requiring filesystem access. It operates on a filename rather than a direct code buffer.","wrong":"const { bundle } = require('lightningcss');","symbol":"bundle","correct":"import { bundle } from 'lightningcss';"},{"note":"This utility converts a Browserslist query string into the `targets` object format expected by `transform` and `bundle` for transpilation. It should be imported directly as a named export.","wrong":"import browserslistToTargets from 'lightningcss/browserslistToTargets';","symbol":"browserslistToTargets","correct":"import { browserslistToTargets } from 'lightningcss';"},{"note":"For TypeScript users, import types for configuration objects, such as `TransformOptions` or `CSSOptions`, to ensure type safety when interacting with the API.","symbol":"TransformOptions","correct":"import type { TransformOptions } from 'lightningcss';"}],"quickstart":{"code":"import { transform, browserslistToTargets } from 'lightningcss';\nimport browserslist from 'browserslist';\nimport { Buffer } from 'node:buffer';\n\nconst cssInput = `\n  :root {\n    --color: oklch(50% 0.1 200);\n  }\n  @media (min-width: 768px) {\n    .container {\n      display: grid;\n      grid-template-columns: 1fr 1fr;\n    }\n  }\n  .text-red {\n    color: var(--color);\n    text-shadow: 1px 1px red;\n  }\n  .flex-center {\n    display: flex;\n    justify-content: center;\n    align-items: center;\n  }\n`;\n\n// Determine browser targets from a browserslist query\nconst targets = browserslistToTargets(browserslist('last 2 Chrome versions, Firefox ESR, Edge >= 90'));\n\ntry {\n  const { code, map } = transform({\n    filename: 'input.css',\n    code: Buffer.from(cssInput),\n    minify: true,\n    targets, // Transpile modern CSS features for these browsers\n    sourceMap: true,\n    drafts: {\n      nesting: true, // Enable CSS nesting support\n      customMedia: true // Enable custom media queries\n    }\n  });\n\n  console.log('Transformed and minified CSS:\\n', Buffer.from(code).toString());\n  console.log('\\nSource Map:\\n', Buffer.from(map).toString());\n} catch (error) {\n  console.error('Error transforming CSS:', error);\n}","lang":"typescript","description":"This quickstart demonstrates how to use `lightningcss` to transform, minify, and transpile modern CSS features for specific browser targets, including generating a source map. It enables CSS nesting and custom media drafts."},"warnings":[{"fix":"Update relative color calculations in CSS to align with the latest spec, using numbers instead of percentages where applicable for color functions like `lch()`, `oklch()`, `lab()`, `oklab()`, and `color-mix()`.","message":"Version 1.30.0 introduced breaking changes related to relative color parsing and calculation. The spec now supports numbers instead of percentages, and `calc()` expressions in colors are always treated as numbers. Code relying on old relative color calculations might need updates.","severity":"breaking","affected_versions":">=1.30.0"},{"fix":"Ensure Node.js version meets the `engines` requirement (currently `>= 12.0.0`). Verify that `npm install` successfully downloads the correct platform-specific package. For persistent issues, clear `node_modules` and `npm cache clean --force`, then reinstall.","message":"As a native module written in Rust, `lightningcss-darwin-x64` (and other platform-specific variants) can sometimes encounter installation issues related to system dependencies, Node.js version mismatches, or incorrect platform detection by npm/yarn, leading to `Module not found` errors or build failures.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refer to the official Lightning CSS changelog and documentation with each major or minor update to understand any spec-driven behavior changes that might affect your CSS code or build process.","message":"Lightning CSS actively tracks and adopts the latest CSS specifications, including draft features like CSS nesting, relative colors, and view transitions. While this provides cutting-edge support, it means that changes in these specs can lead to subtle or breaking changes in how your CSS is processed.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure you are on Lightning CSS v1.30.1 or newer. When using native modules in Node.js worker threads, monitor memory usage and process stability closely, and always test across target environments.","message":"In Node.js environments, particularly when using worker threads, earlier versions of Lightning CSS experienced crashes on process exit on Linux. While a fix was released in v1.30.1, it highlights potential stability issues when integrating native modules into complex, multi-threaded Node.js applications.","severity":"gotcha","affected_versions":"<1.30.1"},{"fix":"If using custom resolvers with `bundle` or `bundleAsync`, review their logic to ensure they handle the `external` option as intended. Adjust resolver returns if all `@import` statements are expected to be inlined.","message":"Starting with v1.32.0, custom resolvers can explicitly mark `@import` rules as external by returning `{ external: string }`. This will leave the `@import` in the output CSS instead of bundling it, which changes default bundling behavior for affected imports if custom resolvers are in use.","severity":"gotcha","affected_versions":">=1.32.0"},{"fix":"Evaluate your PostCSS plugins to determine if Lightning CSS natively supports their functionality. If custom PostCSS plugins are essential, use `lightningcss-loader` alongside `postcss-loader` but be aware of potential conflicts and ensure correct loader order in your build configuration.","message":"While Lightning CSS can replace many PostCSS plugins (like Autoprefixer and `postcss-preset-env`), it may not fully replace all custom PostCSS setups. Integrating both `lightningcss-loader` and `postcss-loader` requires careful configuration, as some PostCSS features might be overridden or become incompatible.","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":"Ensure `npm install` (or `yarn install`, `pnpm install`) completed successfully. This error often occurs if the correct platform-specific package wasn't installed, if `node_modules` is corrupted, or if the `postinstall` script failed. Try `npm rebuild lightningcss` or delete `node_modules` and `package-lock.json` and reinstall.","cause":"The native binary for your operating system and architecture could not be found or loaded by the main `lightningcss` package.","error":"Error: Cannot find module 'lightningcss-darwin-x64'"},{"fix":"Provide a `targets` object derived from a `browserslist` query using `browserslistToTargets`. Example: `targets: browserslistToTargets(browserslist('>= 0.25%'))`.","cause":"The `transform` or `bundle` function was called with options that require browser targets (e.g., `minify: true`, `sourceMap: true`, or specific feature flags for transpilation) but no `targets` object was provided.","error":"The 'browsers' option is required for autoprefixing."},{"fix":"Check the CSS input for typos or invalid syntax. If using a modern CSS draft feature (e.g., nesting, custom media queries), ensure it is explicitly enabled in the `transform` or `bundle` options, for example, `drafts: { nesting: true }`.","cause":"The input CSS contains a syntax error, uses an unsupported draft feature without enabling it, or contains syntax that Lightning CSS's parser cannot understand.","error":"SyntaxError: <css input>: Unexpected token '<some_css_token>'"}],"ecosystem":"npm"}