CSS

Rspack 内置了对 CSS 的支持，并提供了多种能力来支持 CSS 打包。

内置 CSS 支持

Rspack 支持以下四种 CSS 模块类型，你可以手动进行配置：

css/auto：基于文件扩展名自动判断是普通 CSS 文件还是 CSS Modules，*.module.css 或 *.modules.css 结尾的文件会被视为 CSS Modules。
css：用于解析普通的 CSS 文件，不启用 CSS Modules 能力。
css/global：用于以全局作用域模式解析 CSS Modules。
css/module：用于解析 CSS Modules。

css/auto、css/global 和 css/module 的区别在于 CSS Modules 作用域对生成 CSS 的影响：

css/auto 会根据文件名选择行为。style.css 会作为普通 CSS 处理，而 style.module.css 和 style.modules.css 会按 css/module 处理。
css/module 会启用 CSS Modules，默认使用局部作用域。像 .button 这样的选择器会在生成的 CSS 中被重命名。如果希望选择器保持全局，可以使用 :global(.button)。
css/global 会启用 CSS Modules，默认使用全局作用域。像 .button 这样的选择器会保持全局。如果希望选择器在生成的 CSS 中被重命名，可以使用 :local(.button)。

例如：

style.css

.button {
  color: red;
}

:local(.title) {
  color: blue;
}

当使用 type: 'css' 时，文件会作为普通 CSS 输出，不会应用 CSS Modules 作用域转换。

当使用 type: 'css/module' 时，.button 和 .title 都是局部选择器，会在生成的 CSS 中被重命名。如果 .button 需要保持全局，可以使用 :global(.button)。

当使用 type: 'css/global' 时，.button 会保持全局，而 .title 因为被 :local(...) 包裹，会被重命名。

生成的 CSS 大致如下：

css/auto style.css

css/auto style.module.css

css/module style.css

css/global style.css

.button {
  color: red;
}

:local(.title) {
  color: blue;
}

要启用 CSS 支持，需要将 CSS 规则添加到配置中：

rspack.config.mjs

export default {
  module: {
    rules: [
      {
        test: /\.module\.css$/i,
        type: 'css/module',
      },
      {
        test: /\.global\.css$/i,
        type: 'css/global',
      },
      {
        test: /\.css$/i,
        type: 'css/auto',
      },
    ],
  },
};

你也可以通过配置自定义将哪些文件视为 CSS 文件。比如，将 .less 文件视为 CSS 文件：

rspack.config.mjs

export default {
  module: {
    rules: [
      {
        test: /\.less$/,
        type: 'css/auto', // 👈
        use: ['less-loader'],
      },
    ],
  },
};

CSS export type

内置 CSS 支持默认使用 exportType: 'link'。这会将 CSS 作为样式表产物输出，并通过内置 CSS loading runtime 加载。你可以设置 module.parser.css.exportType，或设置 css/auto、css/global、css/module 的 parser 选项，来改变 CSS 导出到 JavaScript 的方式。

支持的取值：

link：将 CSS 作为样式表产物输出。
text：将生成后的 CSS 文本作为默认导出。
css-style-sheet：将 CSSStyleSheet 实例作为默认导出。
style：在运行时通过 <style> 标签将 CSS 注入到文档中。

rspack.config.mjs

export default {
  module: {
    rules: [
      {
        test: /\.css$/i,
        type: 'css/auto',
        parser: {
          exportType: 'text',
        },
      },
    ],
  },
};

index.js

import cssText from './style.css';

console.log(cssText);

更多细节请参考 module.parser["css/auto"].exportType。

CSS 入口

使用默认的 exportType: 'link' 时，你可以将 CSS 文件作为入口，输出样式表，而不生成对应的 JavaScript 入口文件。例如：

rspack.config.mjs

export default {
  entry: './src/styles.css',
  module: {
    rules: [{ test: /\.css$/i, type: 'css' }],
  },
};

此配置只输出 dist/main.css。如果配置了资源引用或 source map，可能会额外生成其他文件。可以通过 output.cssFilename 自定义样式表文件名。

外部资源

使用内置 CSS 支持时，你可以通过 externals 将 CSS 导入和资源排除在打包产物之外。对于 @import，使用 css-import external 类型；对于 url() 引用，使用 asset-url 类型：

style.css

@import './theme.css';

.logo {
  background-image: url('./logo.svg');
}

rspack.config.mjs

export default {
  externals: {
    './theme.css': 'css-import https://example.com/theme.css',
    './logo.svg': 'asset-url https://example.com/logo.svg',
  },
};

生成的 CSS 会引用外部 URL，而不会打包这些文件。浏览器加载样式表时会加载这些资源。

对于默认的 web target，CSS 中的 HTTP(S) 和协议相对 URL 默认会被视为 external。启用 experiments.buildHttp 可能会改变 HTTP(S) URL 的处理方式。

魔法注释

使用内置 CSS 支持时，可以为 @import 或 url() 引用添加 /* rspackIgnore: true */，让 Rspack 保留原始引用，不对其进行解析和打包。将注释放在 @import 之后或 url() 之前：

@import /* rspackIgnore: true */ url('/styles/theme.css');

.logo {
  background-image: /* rspackIgnore: true */ url('/images/logo.svg');
}

Rspack 不会输出被忽略的资源，因此需要确保它们在运行时可通过相应的 URL 访问。为了兼容 webpack，也支持使用 /* webpackIgnore: true */。

如需禁用对所有 @import 规则或 url() 引用的处理，请参阅 CSS parser 选项 import 和 url。

使用 css-loader

你可以将 css-loader 与 CssExtractRspackPlugin 配合使用，生成独立的 CSS 文件；也可以与 style-loader 配合使用，在运行时注入样式。

使用 CssExtractRspackPlugin

Rspack 支持使用 css-loader 和 CssExtractRspackPlugin，用于生成独立的 CSS 文件。

如果你正在迁移一个使用 mini-css-extract-plugin 的 webpack 项目，那么推荐使用 CssExtractRspackPlugin 来替换 mini-css-extract-plugin，它们的功能和配置方式基本一致。

安装 css-loader：

npm

yarn

pnpm

bun

deno

npm add css-loader -D

添加配置：

rspack.config.mjs

import { rspack } from '@rspack/core';

export default {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [rspack.CssExtractRspackPlugin.loader, 'css-loader'],
        type: 'javascript/auto',
      },
    ],
  },
  plugins: [new rspack.CssExtractRspackPlugin({})],
};

参考迁移指南了解如何从 webpack 进行迁移。

Tip

CssExtractRspackPlugin 不能与 type: 'css'、type: 'css/auto'、type: 'css/global' 或 type: 'css/module' 同时使用，因为 css-loader 会将 css 转换成 javascript 类型。

使用 style-loader

Rspack 支持使用 css-loader 和 style-loader，将 CSS 通过 <style> 标签注入。这种方式不会生成独立的 CSS 文件，而是将 CSS 的内容内联到 JS 文件中。

安装 css-loader 和 style-loader：

npm

yarn

pnpm

bun

deno

npm add css-loader style-loader -D

添加配置：

rspack.config.mjs

export default {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ['style-loader', 'css-loader'],
        type: 'javascript/auto',
      },
    ],
  },
};

Tip

style-loader 不能与 type: 'css'、type: 'css/auto'、type: 'css/global' 或 type: 'css/module' 同时使用，因为 css-loader 会将 css 转换成 javascript 类型。

CSS Modules

CSS Modules 是一种 CSS 文件的组织方式，它通过为类名自动生成唯一标识符，来局部化 CSS 的作用域，这允许你在不同的文件中使用相同的类名，而不用担心冲突。

内置支持

在开启内置 CSS 支持后，Rspack 默认将扩展名为 *.module.css 的文件视为 CSS Modules，你可以在 JavaScript 文件中导入它，然后将 CSS 文件中定义的每个类作为模块的导出来访问。

index.module.css

.red {
  color: red;
}

你可以使用命名空间导入：

index.js

import * as styles from './index.module.css';
document.getElementById('element').className = styles.red;

也可以使用具名导入：

import { red } from './index.module.css';
document.getElementById('element').className = red;

要在 Rspack 中启用默认导入方式，你需要在 Rspack 配置中将 namedExports 配置为 false。这允许你在用到 CSS Modules 时，除了命名空间导入和具名导入，也能通过默认导入整个样式模块：

rspack.config.mjs

export default {
  module: {
    parser: {
      'css/auto': {
        namedExports: false,
      },
    },
  },
};

现在你可以使用默认导入：

import styles from './index.module.css';
document.getElementById('element').className = styles.red;

Tip

Rspack 提供了选项，允许你自定义 CSS Modules 的解析和生成方式：

解析器选项：
生成器选项：

使用 css-loader

如果你没有开启 Rspack 的内置 CSS 支持，那么可以使用 css-loader 来提供对 CSS Modules 的支持。

通过 css-loader 的 modules 选项开启：

rspack.config.mjs

export default {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        type: 'javascript/auto',
        options: {
          modules: true,
        },
      },
    ],
  },
};

更多用法请参考 css-loader - modules。

PostCSS

Rspack 支持使用 postcss-loader，你可以这样配置：

npm

yarn

pnpm

bun

deno

npm add postcss postcss-loader -D

rspack.config.mjs

export default {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: 'postcss-loader',
            options: {
              postcssOptions: {
                // ...
              },
            },
          },
        ],
        // 如果你需要将 '*.module.css' 视为 CSS Modules 那么将 'type' 设置为 'css/auto' 否则设置为 'css'
        type: 'css/auto',
      },
    ],
  },
};

上述配置会将所有 *.css 文件经过 postcss-loader 处理，并将生成的结果交给 Rspack 完成 CSS 后续流程的处理。

Tailwind CSS

Tailwind CSS 是一个提供实用类的 CSS 框架，可以快速为组件添加样式。

对于 Tailwind CSS v4 及以上版本，使用 @tailwindcss/webpack loader 配合 Rspack 的内置 CSS 支持：

npm

yarn

pnpm

bun

deno

npm add tailwindcss @tailwindcss/webpack -D

rspack.config.mjs

export default {
  module: {
    rules: [
      {
        test: /\.css$/i,
        type: 'css',
        use: ['@tailwindcss/webpack'],
      },
    ],
  },
};

在样式文件中导入 Tailwind CSS：

src/styles.css

@import 'tailwindcss';

如果使用 css-loader 和 CssExtractRspackPlugin，则额外安装 css-loader，并使用以下配置：

npm

yarn

pnpm

bun

deno

npm add css-loader -D

rspack.config.mjs

import { rspack } from '@rspack/core';

export default {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          rspack.CssExtractRspackPlugin.loader,
          'css-loader',
          '@tailwindcss/webpack',
        ],
      },
    ],
  },
  plugins: [new rspack.CssExtractRspackPlugin()],
};

对于 Tailwind CSS v3，请参考 Install Tailwind CSS v3 with Rspack。

Sass

Rspack 支持使用 sass-loader，你可以这样配置：

npm

yarn

pnpm

bun

deno

npm add sass-embedded sass-loader -D

rspack.config.mjs

export default {
  module: {
    rules: [
      {
        test: /\.(sass|scss)$/,
        use: [
          {
            loader: 'sass-loader',
            options: {
              // 同时使用 `modern-compiler` 和 `sass-embedded` 可以显著提升构建性能
              // 需要 `sass-loader >= 14.2.1`
              api: 'modern-compiler',
              implementation: require.resolve('sass-embedded'),
            },
          },
        ],
        // 如果你需要将 '*.module.(sass|scss)' 视为 CSS Modules 那么将 'type' 设置为 'css/auto' 否则设置为 'css'
        type: 'css/auto',
      },
    ],
  },
};

上述配置会将所有 *.sass 和 *.scss 文件经过 sass-loader 处理，并将生成的结果交给 Rspack 完成 CSS 后续流程的处理。

Less

Rspack 支持使用 less-loader，你可以这样配置：

npm

yarn

pnpm

bun

deno

npm add less less-loader -D

rspack.config.mjs

export default {
  module: {
    rules: [
      {
        test: /\.less$/,
        use: [
          {
            loader: 'less-loader',
            options: {
              // ...
            },
          },
        ],
        // 如果你需要将 '*.module.less' 视为 CSS Modules 那么将 'type' 设置为 'css/auto' 否则设置为 'css'
        type: 'css/auto',
      },
    ],
  },
};

上述配置会将所有 *.less 文件经过 less-loader 处理，并将生成的结果交给 Rspack 完成 CSS 后续流程的处理。

#CSS

#内置 CSS 支持

#CSS export type

#CSS 入口

#外部资源

#魔法注释

#使用 css-loader

#使用 CssExtractRspackPlugin

#使用 style-loader

#CSS Modules

#内置支持

#使用 css-loader

#PostCSS

#Tailwind CSS

#Sass

#Less

CSS

内置 CSS 支持

CSS export type

CSS 入口

外部资源

魔法注释

使用 css-loader

使用 CssExtractRspackPlugin

使用 style-loader

CSS Modules

内置支持

使用 css-loader

PostCSS

Tailwind CSS

Sass

Less