From edda795cba1e03bbe07f73744f9d7fc45e48d55b Mon Sep 17 00:00:00 2001 From: Fy <1114550440@qq.com> Date: Tue, 9 Apr 2024 17:54:16 +0800 Subject: [PATCH] docs: add document for CssExtractRspackPlugin (#6147) --- website/components/i18n/en.json | 2 +- website/components/i18n/zh.json | 2 +- website/docs/en/config/plugins.mdx | 166 +++++++++++++++++ .../docs/en/guide/migrate-from-webpack.mdx | 31 ++++ website/docs/zh/config/plugins.mdx | 169 ++++++++++++++++++ .../docs/zh/guide/migrate-from-webpack.mdx | 30 ++++ 6 files changed, 398 insertions(+), 2 deletions(-) diff --git a/website/components/i18n/en.json b/website/components/i18n/en.json index 2ba72439f5e..5b3fd47d221 100644 --- a/website/components/i18n/en.json +++ b/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" diff --git a/website/components/i18n/zh.json b/website/components/i18n/zh.json index c5e4f63bc80..2187a822b18 100644 --- a/website/components/i18n/zh.json +++ b/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 替代" diff --git a/website/docs/en/config/plugins.mdx b/website/docs/en/config/plugins.mdx index 74d4387ef3e..9f78bc38cbc 100644 --- a/website/docs/en/config/plugins.mdx +++ b/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 + + + +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; + 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 + + 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`', + 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 + +
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'] + } + ] + } +} +``` diff --git a/website/docs/en/guide/migrate-from-webpack.mdx b/website/docs/en/guide/migrate-from-webpack.mdx index a2d43714fab..3f748a0cc23 100644 --- a/website/docs/en/guide/migrate-from-webpack.mdx +++ b/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`. diff --git a/website/docs/zh/config/plugins.mdx b/website/docs/zh/config/plugins.mdx index 3928e6394fe..41bac8a1418 100644 --- a/website/docs/zh/config/plugins.mdx +++ b/website/docs/zh/config/plugins.mdx @@ -1205,3 +1205,172 @@ module.exports = { ``` 以上面的配置运行结果会是 `directory` 目录被移动到产物目录中的 `newdirectory` 目录，例如 `dist/newdirectory/directory/foo`。 + +#### CssExtractRspackPlugin + + + +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; + linkType?: string | 'text/css' | false; + runtime?: boolean; + pathinfo?: boolean; + } + + export interface LoaderOptions { + publicPath?: string | ((resourcePath: string, context: string) => string); + emit?: boolean; + esModule?: boolean; + } + ``` + + plugin 配置 + +
void)`', + default: 'undefined', + description: '决定 link 标签怎样插入到页面，如果传入 string 类型，则会视为 dom 选择器，link 标签会插入到该选择器对应的元素后。如果传入 function 类型，则会将 function 转成字符串，在运行时进行调用，参数是 link 标签', + }, + { + name: '`attributes`', + type: '`Record`', + 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 配置 + +
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'], + }, + ], + }, +}; +``` diff --git a/website/docs/zh/guide/migrate-from-webpack.mdx b/website/docs/zh/guide/migrate-from-webpack.mdx index c382180b66f..da867e83ad9 100644 --- a/website/docs/zh/guide/migrate-from-webpack.mdx +++ b/website/docs/zh/guide/migrate-from-webpack.mdx @@ -134,6 +134,36 @@ Rspack 内置支持了 css 模块类型 ，原生 css 模块类型内置了对 c }; ``` +### CssExtractPlugin + +如果依赖 css-loader，例如 css-loader 提供的一些更加定制化的配置项，仍然可以使用 style-loader + css-loader 方案，如果你想要在生产环境将 css 提取成单独的文件，可以使用 Rspack 内置的 CssExtractRspackPlugin 插件。 + +CssExtractRspackPlugin 插件功能和配置与 mini-css-extract-plugin 类似，使用前请确保开启了 `experiments.rspackFuture.newTreeshaking`，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" + ] + } + ] + } +} +``` + ### 使用 Asset Modules 来代替 file-loader、url-loader 和 raw-loader Rspack 对齐 webpack 5 的 Asset Modules，这意味着你可以使用 Asset Modules 来代替 file-loader 和 url-loader。