在 Webpack、Rspack 和 Rsbuild 中配置 Master CSS

将 Master CSS 构建到 Webpack、Rspack 或 Rsbuild 应用中。三者都使用 @master/css-webpack：CSS 入口提供定义，插件生成工具类规则，HTML 插件则将输出链接到页面。请从已有入口、HTML 模板且正常工作的应用开始。

#安装

1. #添加 Master CSS

   在现有的 Webpack、Rspack 或 Rsbuild 项目中，从项目根目录运行安装程序，并指定 --framework webpack、rspack 或 rsbuild。默认使用静态模式：注册插件并创建 src/index.css。

   npm create @master/css@2.0.0 -- --framework webpack --yes

2. #导入 CSS 入口

   安装程序会创建包含 @import '@master/css'; 的 src/index.css。从应用的 JavaScript 或 TypeScript 入口导入它，并保留现有挂载代码。请使用全局入口，让每个需要这些工具类的页面都能加载。

   src/index.js

   import './index.css'

3. #将 HTML 模板加入扫描

   如果将段落放在独立的 index.html 模板中，请用 @source 将它加入扫描。路径相对于 src/index.css；如果 HTML 插件使用其他模板，请调整路径。框架组件中的类会从模块依赖中检测。

   src/index.css

   @import '@master/css';@source '../index.html';

4. #开始使用 Master CSS

   将段落放入 HTML 模板或框架组件，再启动开发服务器。修改独立模板后，等待开发服务器重新构建，再刷新页面。

index.html

<!doctype html><html lang="en">  <head>    <meta charset="UTF-8">    <meta name="viewport" content="width=device-width, initial-scale=1">    <title>Master CSS with Webpack</title>  </head>  <body>    <p id="master-check" class="w-fit m(0) p-md b-solid b(1) b-line-divider r-md text-sm font-regular bg-surface-raised fg-text-strong">      Hello World    </p>  </body></html>

中性色表面、细边框、小圆角，以及四边各 1rem 的内边距。

#打包工具配置

安装程序会写入配置中属于 Master CSS 的部分。请将其合并到现有配置，保留框架插件、入口和 HTML 生成配置，并且只注册一次插件。

#Webpack

插件需要原生 CSS 处理和 HtmlWebpackPlugin，才能交付生成的样式表：

import HtmlWebpackPlugin from 'html-webpack-plugin'import MasterCSSPlugin from '@master/css-webpack'export default {  entry: './src/index.js',  experiments: { css: true },  module: {    rules: [{ test: /\.css$/i, type: 'css/auto' }]  },  plugins: [    new HtmlWebpackPlugin({ template: './index.html' }),    new MasterCSSPlugin({ mode: 'static' })  ]}

#Rspack

Rspack 使用相同的 Webpack 兼容插件，搭配内置 CSS 支持和 HtmlRspackPlugin：

import { HtmlRspackPlugin } from '@rspack/core'import MasterCSSPlugin from '@master/css-webpack'export default {  entry: './src/index.js',  module: {    rules: [      {        test: /\.css$/i,        type: 'css/auto'      }    ]  },  plugins: [    new HtmlRspackPlugin({ template: './index.html' }),    new MasterCSSPlugin({ mode: 'static' })  ]}

#Rsbuild

Rsbuild 通过 tools.rspack 钩子注册插件。保留框架插件和挂载应用的入口；此钩子只添加 Master CSS 处理。

import { defineConfig } from '@rsbuild/core'import MasterCSSPlugin from '@master/css-webpack'export default defineConfig({  tools: {    rspack(config) {      config.plugins ||= []      config.plugins.push(new MasterCSSPlugin({ mode: 'static' }))      return config    }  }})

在 React 初始项目中，请将段落放在 src/App.tsx：

export default function App() {  return (    <p id="master-check" className="w-fit m(0) p-md b-solid b(1) b-line-divider r-md text-sm font-regular bg-surface-raised fg-text-strong">      Hello World    </p>  )}

#检查配置

先在开发服务器运行时，将源代码中的 p-md 改为 p-lg。段落内边距应从 1rem 增加到 1.5rem；确认后恢复原值。

使用对应打包工具的命令构建：

使用 HTTP 服务器提供输出目录。段落应具有 1rem 内边距、凸起表面和圆角。静态模式的工具类来自链接的 CSS，不使用 Master CSS 运行时。禁用 JavaScript 时，HTML 模板内容仍应具有样式；客户端渲染框架仍需要 JavaScript 创建内容。

HTML 插件会输出样式表链接和所需的运行时脚本。直接从开发服务器静态目录提供的文件不会获取这些内容。如果缺少 CSS 请求，请先检查 HTML 生成流程；如果文件已加载却没有工具类，请检查 CSS 入口、原生 CSS 处理和插件注册。

#选择其他渲染模式

默认使用静态模式。插件的 mode 选项可选择其他交付方式，HTML 插件会加入其运行时脚本：

npm create @master/css@2.0.0 -- --framework webpack --mode runtime --yes

document.querySelector('#master-check').classList.add('underline')