#CSS

Rslib 对 CSS 提供开箱即用的支持，包括 CSS Modules、CSS 预处理器、PostCSS、CSS 内联、Lightning CSS 和 CSS 压缩。

Rslib 也提供了多个配置项，允许自定义 CSS 文件的处理规则。

#引用 CSS

在 JavaScript 文件中，可以直接通过 import 引用 CSS 文件。

import './index.css';

需要注意的是，Rslib 的 output.target 默认值为 'node'，如果你需要处理 CSS 样式，需要将其设置为 'web'。

export default {
  output: {
    target: 'web',
  },
};

在 format 为 'cjs' 或 'esm' 时，Rslib 会根据 bundle 配置对 CSS 应用不同的处理方式。

#Bundle 模式

在 bundle 模式下（默认行为），Rslib 会将 CSS 进行打包，输出的 JavaScript 文件中不会保留引用 CSS 的 import 语句。

这是社区库开发的常见做法，对服务端渲染（SSR）更加友好，避免在 Node.js 环境中加载 CSS 文件可能导致的解析错误。同时，对于使用该库的上游应用，可以通过相关插件或配置（如 Rsbuild 的 source.transformImport）来实现样式的按需加载。

如果你希望保留引用 CSS 的 import 语句，可以使用以下几种方式：

1. 使用 banner：配置 banner.js 在输出的 JavaScript 文件头部添加 import './index.css';。

export default {
  lib: [
    {
      banner: {
        js: "import './index.css';",
      },
    },
  ],
};

对于更复杂的场景，例如存在代码拆分产生多个 chunk 文件时，可以使用 Rspack 的 BannerPlugin 来精确控制哪些模块需要添加 banner，避免在所有 chunk 中都添加。

export default {
  lib: [
    {
      tools: {
        rspack: {
          plugins: [
            new rspack.BannerPlugin({
              banner: "import './index.css';",
              raw: true,
              test: /^index\.js$/,
            }),
          ],
        },
      },
    },
  ],
};

2. 内联样式：开启 output.injectStyles 将 CSS 直接注入到 JavaScript 运行时中。

3. 使用 bundleless 模式：将 bundle 设置为 false，保留源码的文件结构和引用关系。

#Bundleless 模式

在 bundleless 模式下（bundle 设置为 false），Rslib 会保留源码的文件结构和引用关系。这意味着输出的 JavaScript 文件中会保留引用 CSS 的 import 语句。这种方式对构建工具更加友好，便于实现 Tree Shaking 和样式按需加载。

下面是一个使用示例，假设源码如下：

import './index.css';
export const component = () => {};

.title {
  color: red;
}

会根据配置文件中的 产物结构 配置，输出如下产物：

const component = () => {};
export { component };

.title {
  color: red;
}

import './index.css';
const component = () => {};
export { component };

.title {
  color: red;
}

#CSS Modules

Rslib 默认支持使用 CSS Modules，无需添加额外的配置。我们约定使用 [name].module.css 文件名来启用 CSS Modules。

以下样式文件会被视为 CSS Modules：

• *.module.css
• *.module.less
• *.module.sass
• *.module.scss
• *.module.styl
• *.module.stylus

阅读 CSS Modules 章节来了解 CSS Modules 的完整用法。

假设源码如下：

import styles from './index.module.css';

console.log(styles.title);

.title {
  color: red;
}

会输出如下产物：

const index_module = {
  title: 'title-aQjbKQ',
};
console.log(index_module.title);

.title-aQjbKQ {
  color: red;
}

import index_module from './index.module.mjs';
console.log(index_module.title);

import './index_module.css';
const index_module = {
  title: 'title-aQjbKQ',
};
export { index_module as default };

.title-aQjbKQ {
  color: red;
}

#CSS 预处理器

Rslib 通过插件来支持社区流行的 CSS 预处理器，包括 Sass、Less 和 Stylus，使用方式请参考：

• Sass 插件
• Less 插件
• Stylus 插件

以 Sass 插件为例，你可以通过如下的命令安装插件:

npm add @rsbuild/plugin-sass -D

yarn add @rsbuild/plugin-sass -D

pnpm add @rsbuild/plugin-sass -D

bun add @rsbuild/plugin-sass -D

deno add npm:@rsbuild/plugin-sass -D

然后在 rslib.config.ts 文件中注册插件：

import { pluginSass } from '@rsbuild/plugin-sass';

export default {
  plugins: [pluginSass()],
};

注册插件后，你可以在代码中引入 *.scss，*.sass，*.module.scss 或 *.module.sass 文件，无须添加其他配置。

#PostCSS

Rslib 支持通过 PostCSS 来转换 CSS 代码。你可以通过以下方式来配置 PostCSS：

#配置文件

Rslib 使用 postcss-load-config 来加载当前项目根目录下的 PostCSS 配置文件，比如 postcss.config.cjs：

module.exports = {
  plugins: {
    'postcss-px-to-viewport': {
      viewportWidth: 375,
    },
  },
};

postcss-load-config 支持多种文件格式，包括但不限于以下文件名：

• postcss.config.js
• postcss.config.mjs
• postcss.config.cjs
• postcss.config.ts
• ...

#tools.postcss

你也可以通过 tools.postcss 选项来配置 postcss-loader，该选项支持通过函数来修改内置配置，比如：

export default {
  tools: {
    postcss: (opts) => {
      const viewportPlugin = require('postcss-px-to-viewport')({
        viewportWidth: 375,
      });
      opts.postcssOptions.plugins.push(viewportPlugin);
    },
  },
};

#配置优先级

• 当你同时配置 postcss.config.js 文件和 tools.postcss 选项时，两者都会生效，并且 tools.postcss 的优先级更高。
• 如果项目中没有 postcss.config.js 文件，也没有配置 tools.postcss 选项，Rslib 将不会注册 postcss-loader。

#Tailwind CSS

#Tailwind CSS v4

Rslib 内置支持 PostCSS，你可以通过 PostCSS 插件来在 Rslib 中接入 Tailwind CSS v4。以下是接入 Tailwind CSS v4 的步骤：

1. 安装 tailwindcss 和 @tailwindcss/postcss 包：

npm add tailwindcss @tailwindcss/postcss -D

yarn add tailwindcss @tailwindcss/postcss -D

pnpm add tailwindcss @tailwindcss/postcss -D

bun add tailwindcss @tailwindcss/postcss -D

deno add npm:tailwindcss npm:@tailwindcss/postcss -D

2. 通过 postcss.config.mjs 或 tools.postcss 来注册 Tailwind CSS 的 PostCSS 插件。

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

3. 在 CSS 入口文件中添加 @import 指令，引入 Tailwind CSS。

@import 'tailwindcss';

4. 在任意组件或 HTML 中使用 Tailwind 的 utility classes，比如：

<h1 class="text-3xl font-bold underline">Hello world!</h1>

更多用法请参考 Tailwind CSS 文档。

#Tailwind CSS v3

参考 使用 Tailwind CSS v3。

#内联 CSS

默认情况下（bundle 为 true 时），Rslib 会把 CSS 提取为独立的 .css 文件，并输出到构建产物目录。

如果你希望将样式内联到 JS 文件中，可以将 output.injectStyles 设置为 true 来禁用 CSS 提取逻辑。当浏览器请求到 JS 文件后，JS 将动态地向 HTML 插入 <style> 标签，以此加载 CSS 样式。

export default {
  output: {
    injectStyles: true,
  },
};

这将会增大你的 JS Bundle 体积，因此通常情况下，不太建议禁用 CSS 提取逻辑。

#从 node_modules 引用

Rslib 支持引用 node_modules 里的 CSS 文件。

• 在 JS 文件中引用：

/* 引用 normalize.css */
/* https://github.com/necolas/normalize.css */
import 'normalize.css';

• 在 CSS 文件中引用：

@import 'normalize.css';

body {
  /* */
}

• 在 Sass 和 Less 文件中，也允许添加 ~ 前缀来解析 node_modules 里的样式文件，但这是一个废弃的特性，建议从代码中移除 ~ 前缀。

@import '~normalize.css';

#查询参数

#inline

Rslib 支持通过 ?inline 查询参数引用 CSS 文件编译后的内容，并将其作为字符串导入到 JavaScript 中。

import inlineCss from './style.css?inline';

console.log(inlineCss); // 编译后的 CSS 内容

使用 import "*.css?inline" 的行为如下：

• 获取 CSS 文件编译后的文本内容，经过 Lightning CSS、PostCSS 和 CSS 预处理器的处理
• 内容会作为字符串内联到最终的 JavaScript 包中
• 不会生成单独的 CSS 文件

#raw

Rslib 支持通过 ?raw 查询参数引用 CSS 文件的原始内容，并将其作为字符串导入到 JavaScript 中。

import rawCss from './style.css?raw';

console.log(rawCss); // 输出 CSS 文件的原始内容

使用 import "*.css?raw" 的行为如下：

• 获取 CSS 文件的原始文本内容，不经过任何预处理或编译
• 内容会作为字符串内联到最终的 JavaScript 包中
• 不会生成单独的 CSS 文件

#Lightning CSS

Rslib 使用 Rspack 内置的 lightningcss-loader 来转换 CSS 代码，它会自动读取项目中的 syntax 配置，并将 CSS 代码转换为目标浏览器支持的语法。

更多信息可以查看 Lightning CSS。

#CSS 压缩

Rslib 默认关闭了 CSS 压缩（即 output.minify.css 默认为 false）。

如果你需要开启 CSS 压缩，可以通过 output.minify 选项将 output.minify.css 设置为 true。此时，Rslib 会使用 Rspack 内置的 LightningCssMinimizerRspackPlugin 插件来压缩 CSS 资源。

此外，你也可以通过 @rsbuild/plugin-css-minimizer 来自定义 CSS 压缩工具，切换到 cssnano 或是其他 CSS 压缩器。