{"id":13461,"library":"lightningcss-freebsd-x64","title":"LightningCSS (FreeBSD x64 Native Build)","description":"LightningCSS is an exceptionally fast CSS parser, transformer, bundler, and minifier, leveraging the performance benefits of Rust. Currently stable at version 1.32.0, it maintains an active and frequent release cadence, often issuing minor or patch updates every few weeks. Key differentiators include its speed, boasting over 100x faster processing than JavaScript-based alternatives and capable of minifying millions of lines of code per second. It utilizes a browser-grade parser based on Mozilla's `cssparser` and processes typed property values, ensuring accuracy and consistency. The library offers extensive minification optimizations, including combining shorthands, merging adjacent rules, reducing `calc()` expressions, and converting colors to shorter formats. It also provides vendor prefixing, syntax lowering for older browsers, support for CSS Modules, and robust source map generation. Crucially, LightningCSS guarantees that its output CSS behaves identically to the input, avoiding unsafe optimizations that might alter styling for file size reductions.","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-freebsd-x64","lang":"bash","label":"npm"},{"cmd":"yarn add lightningcss-freebsd-x64","lang":"bash","label":"yarn"},{"cmd":"pnpm add lightningcss-freebsd-x64","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The core `lightningcss` library is primarily an ESM module. While Node.js supports `require()` for ESM, `import` is the recommended and cleaner syntax. This `lightningcss-freebsd-x64` package is a native binding and not typically imported directly.","wrong":"const { transform } = require('lightningcss');","symbol":"transform","correct":"import { transform } from 'lightningcss';"},{"note":"Used for bundling multiple CSS files and resolving `@import` statements. The `bundleAsync` variant supports custom resolvers. Requires `filename` option to read directly from the filesystem.","wrong":"import bundle from 'lightningcss';","symbol":"bundle","correct":"import { bundle } from 'lightningcss';"},{"note":"`browserslistToTargets` converts a Browserslist query into a target object for transpilation, and `Features` enum allows fine-grained control over transpilation features (e.g., `Features.Colors | Features.Nesting`).","wrong":"import { browserslistToTargets } from 'lightningcss/node';","symbol":"browserslistToTargets, Features","correct":"import { transform, browserslistToTargets, Features } from 'lightningcss';"}],"quickstart":{"code":"import { transform, browserslistToTargets } from 'lightningcss';\nimport browserslist from 'browserslist';\nimport { readFileSync } from 'fs';\n\n// Create a dummy CSS file for demonstration\nconst cssInput = `\n  @import url('other.css');\n  .container {\n    display: flex;\n    gap: 10px;\n    color: oklab(59.686% 0.1009 0.1192);\n    /* A modern CSS feature that will be lowered */\n    background: linear-gradient(to right, red, blue);\n  }\n  @media (min-width: 768px) {\n    .container {\n      flex-direction: column;\n    }\n  }\n`;\n\nconst otherCss = `.other { padding: 5px; }`;\n\n// In a real application, you'd write these to files or use a bundler.\n// For quickstart, we'll simulate file content.\n// Normally, `bundle` would read from actual files.\n\nasync function processCss() {\n  // Define browser targets using browserslist\n  const targets = browserslistToTargets(browserslist('>= 0.25%, not dead'));\n\n  // Using transform for a single file (no @import resolution via `code` option)\n  const { code: transformedCode, map: transformedMap } = transform({\n    filename: 'style.css',\n    code: Buffer.from(cssInput),\n    minify: true,\n    targets: targets,\n    sourceMap: true,\n    drafts: { nesting: true } // Enable draft features if needed\n  });\n\n  console.log('--- Transformed & Minified CSS ---\\n', transformedCode.toString());\n  console.log('\\n--- Source Map (partial) ---\\n', transformedMap ? transformedMap.toString().substring(0, 200) + '...' : 'No source map generated');\n\n  // To demonstrate @import bundling, you would typically use `bundle`\n  // which requires actual filesystem access.\n  // For example, if 'style.css' contained '@import \"./other.css\";'\n  /*\n  // You would need to ensure 'style.css' and 'other.css' exist on disk\n  // For this quickstart, demonstrating with Buffer for `transform` is more direct.\n  import { bundle } from 'lightningcss';\n  // ... (write cssInput and otherCss to 'style.css' and 'other.css')\n  const { code: bundledCode } = bundle({\n    filename: 'style.css',\n    minify: true,\n    targets: targets\n  });\n  console.log('\\n--- Bundled CSS (if files existed) ---\\n', bundledCode.toString());\n  */\n}\n\nprocessCss().catch(console.error);","lang":"typescript","description":"This example demonstrates how to use the `transform` function from `lightningcss` to parse, minify, transpile modern CSS features for specified browser targets, and generate a source map. It includes setting up browser targets using `browserslist`."},"warnings":[{"fix":"Review CSS code involving relative color calculations. If percentages were used where numbers are now expected by the spec, convert them to their numerical equivalents. Refer to the official v1.30.0 release notes for specific details.","message":"The v1.30.0 release introduced a breaking change in relative color parsing to align with the latest CSS specification. Code using relative color calculations on percentages may need to be updated to use numbers instead.","severity":"breaking","affected_versions":">=1.30.0"},{"fix":"Prefer ES Module `import` syntax (`import { symbol } from 'lightningcss';`) in your Node.js projects. Ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`). If CommonJS is unavoidable, investigate dynamic `import()` or specific transpilation configurations.","message":"LightningCSS is a native module primarily designed for ESM environments. Using `require()` for CommonJS modules can lead to issues or require specific configurations, especially in older Node.js setups.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `npm` can correctly identify and install the appropriate native module for your runtime environment. For Docker, build images on the target architecture or ensure multi-arch builds are correctly configured. Avoid `npm install --force` unless absolutely necessary and understand its implications. If errors occur, try deleting `node_modules` and `package-lock.json` and reinstalling.","message":"This package (`lightningcss-freebsd-x64`) is a platform-specific native binding. Incorrect installation or resolution of the native module (e.g., due to Docker environment mismatch, incorrect `npm install --force`) can lead to runtime errors like 'Cannot find module'.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For cases where invalid third-party CSS cannot be fixed, enable the `errorRecovery` option in the API (`transform({ errorRecovery: true })`) or use the `--error-recovery` CLI flag. This will skip invalid rules and declarations, emitting warnings instead of errors.","message":"By default, LightningCSS is strict and will throw an error when parsing invalid CSS rules or declarations. This can halt builds if third-party CSS contains non-standard or malformed syntax.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always place `@import` statements at the very top of your CSS files, after any `@charset` or `@layer` rules, but before any other `@rule` or style declarations.","message":"When using the bundling API, `@import` rules must strictly appear before all other rules in a stylesheet, except for `@charset` and `@layer` statements. Violating this order will result in an error.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Clear your `node_modules` directory and `package-lock.json` (or `yarn.lock`), then reinstall dependencies. For Docker environments, ensure the build process correctly identifies and installs the native module for the container's architecture or use multi-arch builds.","cause":"The native binding for the current platform (e.g., `lightningcss-freebsd-x64`) could not be found or loaded, often due to an architecture mismatch or corrupted `node_modules`.","error":"Error: Cannot find module '../lightningcss.<platform>.node'"},{"fix":"Review the CSS code around the indicated token for syntax errors. If the error originates from third-party CSS that cannot be directly fixed, consider using the `errorRecovery: true` option in the `transform` or `bundle` API call to skip invalid constructs.","cause":"LightningCSS encountered syntactically invalid CSS code or an unexpected token, as it strictly adheres to the CSS specification by default.","error":"CSS parse error: Unexpected token <token>"},{"fix":"Rearrange your CSS to ensure all `@import` rules are declared at the very beginning of the stylesheet, following only `@charset` or `@layer` rules if present.","cause":"An `@import` rule was found after a non-`@charset` or non-`@layer` rule within a CSS stylesheet when using the `bundle` API.","error":"Error: `@import` rules must appear before all other rules."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}