docs: add document for CssExtractRspackPlugin (#6147)

website/components/i18n/en.json

@@ -9,7 +9,7 @@
   "define-plugin-desc": "Support for this plugin was implemented in v0.3.3, before v0.3.3 you could use builtins.define instead.",
   "copy-plugin-desc": "Use builtins.copy or rspack.CopyRspackPlugin instead.",
   "banner-plugin-desc": "Support for this plugin was implemented in v0.3.3, before v0.3.3 you could use builtins.banner instead.",
-  "mini-css-extract-plugin-desc": "use experiments.css instead",
+  "mini-css-extract-plugin-desc": "use experiments.css or rspack.CssExtractRspackPlugin instead",
   "terser-webpack-plugin-desc": "Use rspack.SwcJsMinimizerRspackPlugin or builtins.minifyOptions instead.",
   "progress-plugin-desc": "use builtins.progress instead",
   "tsconfig-paths-webpack-plugin-desc": "use resolve.tsconfigPath instead"

website/components/i18n/zh.json

@@ -9,7 +9,7 @@
   "define-plugin-desc": "在 v0.3.3 已实现对该插件的支持，v0.3.3 之前可使用 builtins.define 替代",
   "copy-plugin-desc": "使用 builtins.copy 或 rspack.CopyRspackPlugin 替代",
   "banner-plugin-desc": "在 v0.3.3 已实现对该插件的支持，v0.3.3 之前可使用 builtins.banner 替代",
-  "mini-css-extract-plugin-desc": "使用 experiments.css 替代",
+  "mini-css-extract-plugin-desc": "使用 experiments.css 或 rspack.CssExtractRspackPlugin 替代",
   "terser-webpack-plugin-desc": "使用 rspack.SwcJsMinimizerRspackPlugin 或 builtins.minifyOptions 替代",
   "progress-plugin-desc": "使用 builtins.progress 替代",
   "tsconfig-paths-webpack-plugin-desc": "使用 resolve.tsconfigPath 替代"

website/docs/en/config/plugins.mdx

@@ -1211,3 +1211,169 @@ module.exports = {
 ```
 
 The result of running with the above configuration would be that the `directory` folder is moved to the `newdirectory` folder within the output folder, for example `dist/newdirectory/directory/foo`.
+
+#### CssExtractRspackPlugin
+
+<ApiMeta addedVersion={'0.6.0'} />
+
+Rspack currently does not support mini-css-extract-plugin, but it can be replaced with this plugin and used in conjunction with css-loader to extract css into separate files.
+
+If your project does not depend on css-loader, it is recommended to use the built-in css solution experiments.css of Rspack for better performance.
+
+- options
+
+  - **Types:**
+
+  ```ts
+  export interface PluginOptions {
+    filename?: string;
+    chunkFilename?: string;
+    ignoreOrder?: boolean;
+    insert?: string | ((linkTag: HTMLLinkElement) => void);
+    attributes?: Record<string, string>;
+    linkType?: string | 'text/css' | false;
+    runtime?: boolean;
+    pathinfo?: boolean;
+  }
+
+  export interface LoaderOptions {
+    publicPath?: string | ((resourcePath: string, context: string) => string);
+    emit?: boolean;
+    esModule?: boolean;
+  }
+  ```
+
+  Plugin Configuration
+
+   <Table
+     header={[
+       {
+         name: 'Name',
+         key: 'name',
+       },
+       {
+         name: 'Type',
+         key: 'type',
+       },
+       {
+         name: 'Default Value',
+         key: 'default',
+       },
+       {
+         name: 'Description',
+         key: 'description',
+       },
+     ]}
+     body={[
+      {
+        name: '`filename`',
+        type: '`string`',
+        default: '"[name].css"',
+        description:'The name of the CSS artifact, please refer to output.filename'
+      }, 
+      {
+        name: '`chunkFilename`',
+        type: '`string`',
+        default: '"[name].css"',
+        description:"The name of the asynchronous loading CSS artifact. If not set, it will use filename; please see output.chunkFilename"}, {name:"'ignoreOrder'", type:"'boolean'", default:"false", description:"Whether to issue a warning if there are conflicts in the order of some CSS in different chunks. For example, entryA introduces a.css b.css, entryB introduces b.css a.css, and the order of a.css and b.css cannot be determined"
+      },
+      {
+        name: '`ignoreOrder`',
+        type: '`boolean`',
+        default: 'false',
+        description:
+          'If there are conflicts in the order of certain CSS files in different chunks, should a warning be issued? For example, entryA imports a.css and b.css, while entryB imports b.css and a.css. The order of a.css and b.css cannot be determined.',
+      },
+      {
+        name: '`insert`',
+        type: '`string | ((linkTag: HTMLLinkElement) => void)`',
+        default: 'undefined',
+        description: "Decide how the link tag is inserted into the page. If passed as a string type，it will be regarded as dom selector，and the link tag will be inserted after element corresponding to that selector。If passed as function type，the function will be converted into a String at runtime for invocation，with link tag as parameter"
+      },
+      {
+        name: '`attributes`',
+        type: '`Record<string, string>`',
+        default: 'undefined',
+        description: "Add attributes to link tags"
+      },
+      {
+        name: '`linkType`',
+        type: "`string | 'text/css' | false`",
+        default: '"text/css"',
+        description: "Set the Type attribute value for Link Tag"
+      },
+      {
+        name: '`runtime`',
+        type: '`boolean`',
+        default: 'true',
+        description : `Injecting Runtime code related to Css Loading `
+      },
+      {
+        name: '`pathinfo`',
+        type: '`boolean`',
+        default: 'false',
+        description: 'Whether more detailed information about Css Path should remain in product'
+      }
+    ]}
+  />
+
+  Loader Configuration
+
+  <Table
+    header={[
+      {
+        name: 'Name',
+        key: 'name',
+      },
+      {
+        name: 'Type',
+        key: 'type',
+      },
+      {
+        name: 'Default Value',
+        key: 'default',
+      },
+      {
+        name: 'Description',
+        key: 'description',
+      },
+    ]}
+    body={[
+      {
+        name: '`publicPath`',
+        type: '`string | ((resourcePath: string, context: string) => string)`',
+        default: 'output.publicPath',
+        description: 'Public Path in Css Module'
+      },
+      {
+        name: '`emit`',
+        type: '`boolean`',
+        default: 'true',
+        description: 'Whether Extracting Out Css Files Setting It To False Will Not Generate Css Files'
+      },
+      {
+        name: '`esModule`',
+        type: '`boolean`',
+        default: 'true',
+        description: 'Whether To Use Es Module Syntax For Exporting Class Names Of Css Modules'
+      }
+    ]}
+  />
+
+Example:
+
+```ts title="rspack.config.js"
+const rspack = require('@rspack/core');
+
+module.exports = {
+  plugins: [new rspack.CssExtractRspackPlugin({})],
+  module: {
+    rules:[
+      {
+        test: /\.css$/i,
+        use: [rspack.CssExtractRspacKplugin.loader,'Css-Loader']
+      }
+    ]
+  }
+}
+```

website/docs/en/guide/migrate-from-webpack.mdx

@@ -134,6 +134,37 @@ Rspack's [css-modules](https://github.com/css-modules/css-modules) functionality
  };
 ```
 
+
+### CssExtractPlugin
+
+If you need some specific configurations from css-loader, you can still use style-loader + css-loader, if you want to extract css files for production, you can use Rspack builtin plugin: CssExtractRspackPlugin.
+
+CssExtractRspackPlugin is similar to mini-css-extract-plugin, be sure that you've already enabled `experiments.rspackFuture.newTreeshaking`, it's enabled by default after v0.6.
+
+```diff
++ const { CssExtractRspackPlugin } = require("@rspack/core");
+- const CssExtractPlugin = require("mini-css-extract-plugin");
+
+module.exports = {
+  plugins: [
++    new CssExtractRspackPlugin(),
+-    new CssExtractPlugin(),
+  ]
+  module: {
+    rules: [
+      {
+        test: /\.css$/i,
+        use: [
++          CssExtractRspackPlugin.loader,
+-          CssExtractPlugin.loader,
+          "css-loader"
+        ]
+      }
+    ]
+  }
+}
+```
+
 ### Using asset modules instead of file-loader and url-loader
 
 Rspack is aligned with Webpack 5's "asset modules," which should be used instead of `file-loader` and `url-loader`.

website/docs/zh/config/plugins.mdx

@@ -1205,3 +1205,172 @@ module.exports = {
 ```
 
 以上面的配置运行结果会是 `directory` 目录被移动到产物目录中的 `newdirectory` 目录，例如 `dist/newdirectory/directory/foo`。
+
+#### CssExtractRspackPlugin
+
+<ApiMeta addedVersion={'0.6.0'} />
+
+Rspack 目前不兼容 mini-css-extract-plugin，但可以使用该插件替代，和 css-loader 搭配使用，将 css 提取成单独文件。
+
+如果你的项目不依赖 css-loader，更推荐使用 Rspack 内置的 css 解决方案 experiments.css，性能更好。
+
+- options
+
+  - **类型：**
+
+  ```ts
+  export interface PluginOptions {
+    filename?: string;
+    chunkFilename?: string;
+    ignoreOrder?: boolean;
+    insert?: string | ((linkTag: HTMLLinkElement) => void);
+    attributes?: Record<string, string>;
+    linkType?: string | 'text/css' | false;
+    runtime?: boolean;
+    pathinfo?: boolean;
+  }
+
+  export interface LoaderOptions {
+    publicPath?: string | ((resourcePath: string, context: string) => string);
+    emit?: boolean;
+    esModule?: boolean;
+  }
+  ```
+
+  plugin 配置
+
+  <Table
+    header={[
+      {
+        name: '名称',
+        key: 'name',
+      },
+      {
+        name: '类型',
+        key: 'type',
+      },
+      {
+        name: '默认值',
+        key: 'default',
+      },
+      {
+        name: '描述',
+        key: 'description',
+      },
+    ]}
+    body={[
+      {
+        name: '`filename`',
+        type: '`string`',
+        default: '"[name].css"',
+        description: 'css 产物的名字，请见 output.filename',
+      },
+      {
+        name: '`chunkFilename`',
+        type: '`string`',
+        default: '"[name].css"',
+        description:
+          'css 异步加载产物的名字，如果不设置则会使用 filename，请见 output.chunkFilename',
+      },
+      {
+        name: '`ignoreOrder`',
+        type: '`boolean`',
+        default: 'false',
+        description:
+          '若某些 css 在不同 chunk 中顺序有冲突，是否发出警告。例如 entryA 引入 a.css b.css，entryB 引入 b.css a.css，a.css 和 b.css 的顺序无法确定',
+      },
+      {
+        name: '`insert`',
+        type: '`string | ((linkTag: HTMLLinkElement) => void)`',
+        default: 'undefined',
+        description: '决定 link 标签怎样插入到页面，如果传入 string 类型，则会视为 dom 选择器，link 标签会插入到该选择器对应的元素后。如果传入 function 类型，则会将 function 转成字符串，在运行时进行调用，参数是 link 标签',
+      },
+      {
+        name: '`attributes`',
+        type: '`Record<string, string>`',
+        default: 'undefined',
+        description: '给 link 标签添加 attributes',
+      },
+      {
+        name: '`linkType`',
+        type: "`string | 'text/css' | false`",
+        default: '"text/css"',
+        description: '设置 link 标签的 type',
+      },
+      {
+        name: '`runtime`',
+        type: '`boolean`',
+        default: 'true',
+        description:
+          '是否注入 css 加载相关的 runtime 代码',
+      },
+      {
+        name: '`pathinfo`',
+        type: '`boolean`',
+        default: 'false',
+        description:
+          '产物中是否保留更详细的 css 路径信息',
+      },
+    ]}
+  />
+
+  loader 配置
+
+   <Table
+    header={[
+      {
+        name: '名称',
+        key: 'name',
+      },
+      {
+        name: '类型',
+        key: 'type',
+      },
+      {
+        name: '默认值',
+        key: 'default',
+      },
+      {
+        name: '描述',
+        key: 'description',
+      },
+    ]}
+    body={[
+      {
+        name: '`publicPath`',
+        type: '`string | ((resourcePath: string, context: string) => string)`',
+        default: 'output.publicPath',
+        description: 'css 模块中的 publicPath',
+      },
+      {
+        name: '`emit`',
+        type: '`boolean`',
+        default: 'true',
+        description: '是否提取出 css 文件，设置为 false 则不会产生 css 文件',
+      },
+      {
+        name: '`esModule`',
+        type: '`boolean`',
+        default: 'true',
+        description: '是否使用 es 模块语法进行 css module 类名导出',
+      },
+    ]}
+  />
+
+示例：
+
+```ts title="rspack.config.js"
+const rspack = require('@rspack/core');
+
+module.exports = {
+  plugins: [new rspack.CssExtractRspackPlugin({})],
+  module: {
+    rules: [
+      {
+        test: /\.css$/i,
+        use: [rspack.CssExtractRspackPlugin.loader, 'css-loader'],
+      },
+    ],
+  },
+};
+```