> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Lightning CSS loader

[Lightning CSS](https://lightningcss.dev) is a high performance CSS parser, transformer and minifier written in Rust. It supports parsing and transforming many modern CSS features into syntax supported by target browsers, and also provides a better compression ratio.

Rspack provides a built-in `builtin:lightningcss-loader`, which is based on Lightning CSS to transform CSS. It can replace the [postcss-loader](https://github.com/postcss/postcss-loader) and [autoprefixer](https://github.com/postcss/autoprefixer) for CSS syntax downgrading, prefixing, and other functionalities, offering better performance.

::: warning
Please note that Lightning CSS strictly requires standards-compliant CSS input. When non-standard CSS is processed by the `builtin:lightningcss-loader`, styles may be ignored or produce unexpected results (Undefined Behavior). To ensure that styles are correctly applied, avoid using non-standard CSS syntax or browser-specific proprietary syntax, and instead use standard CSS writing practices that conform to W3C specifications.
:::

## Example

To use `builtin:lightningcss-loader` in your project, you need to configure it as follows.

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: 'builtin:lightningcss-loader',
            options: {
              targets: 'ie 10',
            },
          },
          // ... other loaders
        ],
      },
    ],
  },
};
```

## Type declarations

You can use the `LightningcssLoaderOptions` type exported by `@rspack/core` to enable type hints:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: 'builtin:lightningcss-loader',
            /** @type {import('@rspack/core').LightningcssLoaderOptions} */
            options: {
              targets: 'ie 10',
            },
          },
          // ... other loaders
        ],
      },
    ],
  },
};
```

## Options

Below are the configurations supported by `builtin:lightningcss-loader`. For detailed configuration, please refer to [lightningcss document](https://lightningcss.dev/transpilation.html).

```ts
type LightningcssFeatureOptions = {
  nesting?: boolean;
  notSelectorList?: boolean;
  dirSelector?: boolean;
  langSelectorList?: boolean;
  isSelector?: boolean;
  textDecorationThicknessPercent?: boolean;
  mediaIntervalSyntax?: boolean;
  mediaRangeSyntax?: boolean;
  customMediaQueries?: boolean;
  clampFunction?: boolean;
  colorFunction?: boolean;
  oklabColors?: boolean;
  labColors?: boolean;
  p3Colors?: boolean;
  hexAlphaColors?: boolean;
  spaceSeparatedColorNotation?: boolean;
  fontFamilySystemUi?: boolean;
  doublePositionGradients?: boolean;
  vendorPrefixes?: boolean;
  logicalProperties?: boolean;
  selectors?: boolean;
  mediaQueries?: boolean;
  color?: boolean;
};

type Targets = {
  android?: string;
  chrome?: string;
  edge?: string;
  firefox?: string;
  ie?: string;
  ios_saf?: string;
  opera?: string;
  safari?: string;
  samsung?: string;
};

type LightningcssLoaderOptions = {
  minify?: boolean;
  errorRecovery?: boolean;
  targets?: string[] | string | Targets;
  include?: LightningcssFeatureOptions;
  exclude?: LightningcssFeatureOptions;
  drafts?: Drafts;
  nonStandard?: NonStandard;
  pseudoClasses?: PseudoClasses;
  unusedSymbols?: string[];
};
```

### targets

- **Type:** `string | string[] | Targets`

Browserslist query string or a `Targets` object specifying browser versions.

:::tip Default targets from Rspack
If `targets` is not configured, `builtin:lightningcss-loader` will automatically derive a default targets from Rspack's [`target`](/config/target.md) configuration when using browserslist-related targets (e.g., `browserslist` or `browserslist:modern`). Since Lightning CSS only supports browser-related targets, non-browser targets like `node` will not provide default targets for this loader.

This means you can rely on your Rspack `target` configuration without manually specifying the same targets in the loader options.
:::

Here are some examples of setting targets.

- Setting a browserslist query string:

```js
const loader = {
  loader: 'builtin:lightningcss-loader',
  /** @type {import('@rspack/core').LightningcssLoaderOptions} */
  options: {
    targets: 'ie 10',
  },
};
```

- Setting an array of browserslist query strings:

```js
const loader = {
  loader: 'builtin:lightningcss-loader',
  /** @type {import('@rspack/core').LightningcssLoaderOptions} */
  options: {
    targets: ['chrome >= 87', 'edge >= 88', '> 0.5%'],
  },
};
```

- Setting a `Targets` object:

```js
const loader = {
  loader: 'builtin:lightningcss-loader',
  /** @type {import('@rspack/core').LightningcssLoaderOptions} */
  options: {
    targets: {
      chrome: '95.0',
      safari: '13.2',
    },
  },
};
```

### errorRecovery

- **Type:** `boolean`
- **Default:** `true`

Control how Lightning CSS handles invalid CSS syntax.

By default, this option is enabled, meaning that when invalid CSS rules or declarations are parsed, Lightning CSS will skip them and emit warnings, while omitting them from the final output without interrupting the compilation process.

#### Ignoring warnings

If you confirm that these warnings can be ignored, you can use [ignoreWarnings](/config/other-options.md#ignorewarnings) to filter out the warnings from LightningCSS.

For example, ignore all warnings:

```js title="rspack.config.mjs"
export default {
  ignoreWarnings: [
    (warning) => /LightningCSS parse warning/.test(warning.message),
  ],
};
```

You can also use regular expressions to ignore specific warnings.

#### Disabling `errorRecovery`

If you set `errorRecovery` to `false`, Lightning CSS will throw a compilation error and interrupt the build process when parsing any invalid CSS syntax:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: 'builtin:lightningcss-loader',
            /** @type {import('@rspack/core').LightningcssLoaderOptions} */
            options: {
              errorRecovery: false,
            },
          },
        ],
      },
    ],
  },
};
```