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

# Lightning CSS loader

[Lightning CSS](https://lightningcss.dev) 是一个基于 Rust 编写的高性能 CSS 解析、转译和压缩工具。它支持将许多现代的 CSS 特性解析并转化为指定浏览器支持的语法，并提供更好的压缩比例。

Rspack 提供了一个内置的 `builtin:lightningcss-loader`，它基于 Lightning CSS 来转换 CSS，可以替代 [postcss-loader](https://github.com/postcss/postcss-loader) 和 [autoprefixer](https://github.com/postcss/autoprefixer) 的 CSS 语法降级、添加前缀等功能，并提供更好的性能。

:::warning
请注意，Lightning CSS 严格要求输入的代码符合 CSS 规范。使用 `builtin:lightningcss-loader` 处理非标准 CSS 代码时，可能导致样式被忽略或产生不可预期的结果（未定义的行为）。为确保样式正确应用，请避免使用非标准 CSS 语法或特定浏览器的私有语法，而应采用符合 W3C 规范的标准 CSS 写法。
:::

## 示例

如果需要在项目中使用 `builtin:lightningcss-loader`，需进行如下配置。

```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 loader
        ],
      },
    ],
  },
};
```

## 类型声明

你可以使用 `@rspack/core` 导出的 `LightningcssLoaderOptions` 类型来开启类型提示：

```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 loader
        ],
      },
    ],
  },
};
```

## 选项

下面是 `builtin:lightningcss-loader` 支持的配置。详细的解释请查看 [lightningcss 文档](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

- **类型：** `string | string[] | Targets`

browserslist 查询字符串或指定浏览器版本的 `Targets` 对象。

:::tip 默认目标浏览器
未设置 `targets` 时，loader 会根据 Rspack 的 [`target`](https://rspack.rs/zh/config/target.md) 确定需要兼容的浏览器。例如，如果 `target` 为 `browserslist` 或 `browserslist:modern`，loader 就会使用相应的浏览器配置，无需重复设置。Lightning CSS 只支持浏览器环境，因此无法继承 `node` 等非浏览器 target。

即使没有显式设置 Rspack 的 `target`，loader 也会尝试继承它的默认值，详见 [`target` 的默认行为](https://rspack.rs/zh/config/target.md#default-behavior)。

如果没有设置 `target`，也找不到 Browserslist 配置，Rspack 就会使用默认值 `web`。由于 `web` 不包含浏览器版本信息，loader 不会自动设置 `targets`，需要时可以手动配置。
:::

下面是一些 targets 的用法示例。

- 设置 browserslist 查询字符串：

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

- 设置 browserslist 查询字符串数组：

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

- 设置 `Targets` 对象：

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

### errorRecovery

- **类型：** `boolean`
- **默认值：** `true`

控制 Lightning CSS 如何处理无效的 CSS 语法。

默认情况下启用，这意味着当 Lightning CSS 解析到无效的 CSS 规则或声明时，它会跳过这些内容，并输出警告，同时将这些无效部分从最终产物中移除，而不会中断编译过程。

#### 忽略警告

如果你确认这些警告可以忽略，可以使用 [ignoreWarnings](https://rspack.rs/zh/config/other-options.md#ignorewarnings) 过滤掉来自 LightningCSS 的提示。

比如忽略所有警告：

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

你也可以使用正则表达式来忽略特定的警告。

#### 关闭 errorRecovery

如果将 `errorRecovery` 设置为 `false`，Lightning CSS 在解析任何无效的 CSS 语法时，都会抛出编译错误并中断构建过程：

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