function StartDevServer(
options?: StartDevServerOptions,
-): Promise<StartServerResult>;
+): Promise<StartServerResult>;
- Example
启动 Dev Server：
-成功启动 Dev Server 后，可以看到以下日志信息：
startDevServer 会返回以下参数：
urls：访问 Dev Server 的 URLs
@@ -170,12 +170,12 @@ - Example
urls：访问 Server 的 URLs
@@ -262,18 +262,18 @@ - 类型
- Example
- Example
- 类型
- Example
- 类型
- Example
- 类型 @@ -354,20 +354,20 @@
- Example
- Example
- Example
-
@@ -435,15 +435,15 @@
callback: (params: { bundlerConfigs?: WebpackConfig[] | RspackConfig[]; }) => Promise<void> | void, -): void; +): void;
- Example
+});builder.onAfterBuild
- +;
onAfterBuild是在执行生产环境构建后触发的回调函数，你可以通过stats参数获取到构建结果信息：-
@@ -458,50 +458,50 @@
+): void;
- Example
+});builder.onBeforeStartDevServer
- +;
在启动开发服务器前调用。
- 类型
+- Example
+});builder.onAfterStartDevServer
- +;
在启动开发服务器后调用，你可以通过
port参数获得开发服务器监听的端口号。- 类型
+): void;- Example
+});builder.onDevCompileDone
- +;
在每次开发环境构建结束后调用，你可以通过
isFirstCompile来判断是否为首次构建。- 类型
+): void;- Example
} else { console.log('re-compile!'); } -}); +});
builder.onExit
- +;
在进程即将退出时调用，这个钩子只能执行同步代码。
- 类型
+- Example
+});builder.getBuilderConfig
- +;
获取 Builder 配置，该方法必须在
modifyBuilderConfig钩子执行完成后才能被调用。- 类型
+- Example
+});builder.getNormalizedConfig
- +;
获取归一化后的 Builder 配置，该方法必须在
modifyBuilderConfig钩子执行完成后才能被调用。相较于
getBuilderConfig方法，该方法返回的配置经过了归一化处理，配置的类型定义会得到收敛，比如config.html的undefined类型将被移除。推荐优先使用该方法获取配置。
- 类型
+- Example
+});builder.getHTMLPaths
- +;
获取所有 HTML 产物的路径信息。
该方法会返回一个对象，对象的 key 为 entry 名称，value 为 HTML 文件在产物目录下的相对路径。
- 类型
+- Example
\ No newline at end of file +});目录\ No newline at end of file diff --git a/modern-js/builder/api/builder-types.html b/modern-js/builder/api/builder-types.html index 75e29ae701..0eba4ba0ba 100644 --- a/modern-js/builder/api/builder-types.html +++ b/modern-js/builder/api/builder-types.html @@ -1,4 +1,4 @@ -目录Builder Types - Modern.js Builder +Builder Types - Modern.js Builder -Modern.js Builder Builder Types
+Modern.js Builder Builder Types
本章节描述了 Builder 提供的一些类型定义。
BuilderInstance
Builder 实例的类型。
+let builder: BuilderInstance;你可以通过泛型来传入 Provider 的类型，使 Builder 实例获得更准确的类型定义：
+let builder: BuilderInstance<BuilderWebpackProvider>;BuilderContext
Builder 实例中 context 属性的类型定义。
+const context: BuilderContext = builder.context;BuilderPlugin
Builder 插件的类型，需要配合 provider 中提供的
BuilderPluginAPI类型来使用。+};BuilderTarget
Builder 构建产物的类型。
-+BuilderEntry
对应
-createBuilder方法的entry选项的类型。+CreateBuilderOptions
对应
-createBuilder方法的入参类型。\ No newline at end of file +目录\ No newline at end of file diff --git a/modern-js/builder/api/config-dev.html b/modern-js/builder/api/config-dev.html index ead4872966..9a067bda99 100644 --- a/modern-js/builder/api/config-dev.html +++ b/modern-js/builder/api/config-dev.html @@ -1,4 +1,4 @@ -目录Dev Config - Modern.js Builder +Dev Config - Modern.js Builder -Modern.js Builder +};+};Dev Config
+Modern.js Builder +};Dev Config
本章节描述了 Builder 中与本地开发有关的配置。
dev.assetPrefix
- +;
- 类型：
boolean | string - 默认值：
'/'
@@ -25,9 +25,9 @@
Boolean dev: { assetPrefix: true, }, -};
对应 JS 文件在浏览器中加载的地址如下：
-+如果设置
assetPrefix为false或不设置，则默认使用/作为访问前缀。String 类型
当
@@ -35,23 +35,29 @@assetPrefix的值为string类型时，字符串会作为前缀，自动拼接到静态资源访问 URL 上：String dev: { assetPrefix: 'http://example.com/assets/', }, -};
对应 JS 文件在浏览器中加载的地址如下：
-+与原生配置的区别
dev.assetPrefix对应以下原生配置：-
-
- webpack 的 output.publicPath 配置。 -
- Rspack 的 output.publicPath 配置。 +
- webpack 的 output.publicPath 配置。 +
- Rspack 的 output.publicPath 配置。
它与原生配置的区别在于：
-
-
dev.assetPrefix仅在开发环境下生效。
-dev.assetPrefix默认会自动补全尾部的/。
-dev.assetPrefix的值会写入process.env.ASSET_PREFIX环境变量。
+-
+
+dev.assetPrefix仅在开发环境下生效。
+ -
+
+dev.assetPrefix默认会自动补全尾部的/。
+ -
+
+dev.assetPrefix的值会写入process.env.ASSET_PREFIX环境变量。
dev.beforeStartUrl
- +;
- 类型：
() => Promise<void> | void - 默认值：
undefined
@@ -64,9 +70,9 @@
await doSomeThing(); }, }, -};
dev.hmr
- +;
- 类型：
boolean - 默认值：
true
@@ -77,9 +83,9 @@ - 类型：
string - 默认值：
0.0.0.0
@@ -91,9 +97,9 @@ - 类型：
boolean | { key: string; cert: string } - 默认值：
false
@@ -101,13 +107,13 @@ - 类型：
number - 默认值：
8080
@@ -153,9 +159,9 @@ - 类型：
- 默认值：
true - 类型：
boolean | string | string[] | undefined - 默认值：
undefined
@@ -199,14 +205,14 @@ - 类型：
- 默认值：
false - 打包工具：
仅支持 webpack
@@ -31,7 +31,7 @@ - 类型：
boolean | PluginSourceBuildOptions - 默认值：
false
@@ -83,10 +83,10 @@ - 类型：
string - 默认值：
undefined
@@ -24,7 +24,7 @@ - 类型：
boolean | 'anonymous' | 'use-credentials' - 默认值：
false - 当传入
true时，它会被自动设置为crossorigin="anonymous"。 - 当传入
false时，它不会设置crossorigin属性。 anonymous：请求使用 CORS 头，并将证书标志设置为 "same-origin"。除非目标是相同的 origin，否则不会通过 cookie、客户端 SSL 证书或 HTTP 身份验证交换用户凭据。
-use-credentials：请求使用 CORS 头，证书标志设置为 "include"，并始终包含用户凭据。
+-
+
+anonymous：请求使用 CORS 头，并将证书标志设置为 "same-origin"。除非目标是相同的 origin，否则不会通过 cookie、客户端 SSL 证书或 HTTP 身份验证交换用户凭据。
+ -
+
+use-credentials：请求使用 CORS 头，证书标志设置为 "include"，并始终包含用户凭据。 - 类型：
boolean - 默认值：
false - 类型：
string - 默认值：
undefined
@@ -101,13 +105,13 @@ - 相对于项目根目录的相对路径。
- 类型：
Record<string, string> - 默认值：
undefined
@@ -135,7 +139,7 @@ - 页面
foo的 favicon 为./src/assets/foo.png。
- - 其他页面的 favicon 为
./src/assets/default.png。
+ -
+
页面
+foo的 favicon 为./src/assets/foo.png。
+ -
+
其他页面的 favicon 为
+./src/assets/default.png。 - 类型：
'head' | 'body'| 'true' | false - 默认值：
'head'
@@ -175,14 +183,14 @@ - 类型：
Record<string, boolean | string> - 默认值：
undefined
@@ -204,7 +212,7 @@ - 页面
foo的 script 标签会插入到body标签内。
- - 其他页面的 script 标签会插入到
head标签内。
+ -
+
页面
+foo的 script 标签会插入到body标签内。
+ -
+
其他页面的 script 标签会插入到
+head标签内。 - 类型：
Record<string, false | string | Record<string, string | boolean>> - 默认值：
undefined
@@ -234,9 +246,9 @@ - 类型：
Record<string, Meta> - 默认值：
undefined
@@ -272,7 +284,7 @@ - 类型：
string - 默认值：
'root'
@@ -298,29 +310,29 @@ - 类型：
'defer' | 'blocking' | 'module' - 默认值：
'defer'
@@ -331,7 +343,7 @@ - 类型：
ArrayOrNot<HtmlInjectTag | HtmlInjectTagHandler> - 默认值：
undefined
@@ -381,7 +393,7 @@ - 注入 CDN 上 路径确定 的静态资源 @@ -507,7 +519,7 @@
- 类型：
Record<string, ArrayOrNot<HtmlInjectTag | HtmlInjectTagHandler>> - 默认值：
undefined
@@ -554,7 +566,7 @@ - 类型：
string - 默认值：
- 类型：
Object - 默认值：
undefined
@@ -590,7 +602,7 @@ - 类型：
Object | Function - 默认值： @@ -621,8 +633,8 @@
- 类型：
Object - 默认值：
undefined
@@ -675,7 +687,7 @@ - 类型：
string - 默认值：
undefined
@@ -699,9 +711,9 @@ - 类型：
Record<string, string> - 默认值：
undefined
@@ -709,7 +721,7 @@ - 页面
foo的 title 为TikTok。
diff --git a/modern-js/builder/api/config-output.html b/modern-js/builder/api/config-output.html
index 77709a66d5..c8344473ea 100644
--- a/modern-js/builder/api/config-output.html
+++ b/modern-js/builder/api/config-output.html
@@ -1,4 +1,4 @@
- - 类型：
string - 默认值：
'/'
@@ -25,26 +25,32 @@ - webpack 的 output.publicPath 配置。 -
- Rspack 的 output.publicPath 配置。 +
- webpack 的 output.publicPath 配置。 +
- Rspack 的 output.publicPath 配置。
output.assetPrefix仅在生产环境下生效。
-output.assetPrefix默认会自动补全尾部的/。
-output.assetPrefix的值会写入process.env.ASSET_PREFIX环境变量。
+-
+
+output.assetPrefix仅在生产环境下生效。
+ -
+
+output.assetPrefix默认会自动补全尾部的/。
+ -
+
+output.assetPrefix的值会写入process.env.ASSET_PREFIX环境变量。 - 类型：
Object - 类型：
number
@@ -127,7 +133,7 @@ - 类型：
string | ((url: string) => boolean) | undefined
@@ -140,7 +146,7 @@ - 类型：
undefined | boolean | 'anonymous' | 'use-credentials'
@@ -154,7 +160,7 @@ - 类型：
undefined | (options: AssetsRetryHookContext) => void
@@ -170,7 +176,7 @@ - 类型：
undefined | (options: AssetsRetryHookContext) => void
@@ -186,7 +192,7 @@ - 类型：
undefined | (options: AssetsRetryHookContext) => void
@@ -202,7 +208,7 @@ - 类型：
boolean
@@ -216,7 +222,7 @@ - 类型：
'ascii' | 'utf8' - 默认值：
'ascii'
@@ -277,10 +283,10 @@ - 类型：
boolean - 默认值：
true
@@ -291,9 +297,9 @@ - 类型：
boolean | object - 默认值：
false
@@ -309,7 +315,7 @@ - rootValue。默认与 rootFontSize 相同
- unitPrecision: 5。精确位数
- propList: ['*']。支持转换的 CSS 属性
- 类型：
CopyPluginOptions | CopyPluginOptions['patterns'] - 默认值：
undefined
@@ -426,10 +432,10 @@ - 类型：
- 默认值：
undefined: 根据 output.disableCssModuleExtension 配置项决定为哪些样式文件启用 CSS 模块。
+undefined: 根据 output.disableCssModuleExtension 配置项决定为哪些样式文件启用 CSS 模块。true: 为所有匹配/\.module\.\w+$/i.test(filename)正则表达式的文件启用 CSS 模块。false: 禁用 CSS 模块。RegExp: 为所有匹配/RegExp/i.test(filename)正则表达式的文件禁用 CSS 模块。
@@ -477,7 +483,7 @@ - 类型：
string - 默认值： @@ -512,7 +518,7 @@
- 类型：
- 默认值：
dev.hmr dev: { hmr: false, }, -}; +};
dev.host
- +;
dev.host dev: { host: 'localhost', }, -}; +};
dev.https
- +;
dev.htt
配置该选项后，可以开启 Dev Server 对 HTTPS 的支持，同时会禁用 HTTP 服务器。
开启前：
+ > Network: http://192.168.0.1:8080/开启后：
+ > Network: https://192.168.0.1:8080/自动生成证书
-你可以直接将
-https设置为true，Builder 会基于 devcert 来自动生成 Dev Server 所需的 HTTPS 证书。使用这种方式时，你需要在当前项目中手动安装 devcert 依赖：
+你可以直接将
+https设置为true，Builder 会基于 devcert 来自动生成 Dev Server 所需的 HTTPS 证书。使用这种方式时，你需要在当前项目中手动安装 devcert 依赖：
+pnpm add devcert@1.2.2 -D然后配置
dev.https为true即可：+};该方式有一定局限性，由于 devcert 目前不支持 IP addresses，因此访问 Network 域名时，会遇到「您的连接不是私密连接」的问题。
此问题的解决方法为：点击 Chrome 浏览器问题页面的「高级」->「继续前往 192.168.0.1（不安全）」。
TIPhttps 代理自动安装证书需要获取 root 权限, 请根据提示输入密码即可。 密码仅在信任证书时使用，不会泄漏或者用于其他环节。
手动设置证书
你也可以在
-dev.https选项中手动传入 HTTPS 服务器所需要的证书和对应的私钥，这个参数将直接传递给 Node.js 中 https 模块的 createServer。具体可以参考 https.createServer。
+具体可以参考 https.createServer。
+};dev.port
- +;
示例 dev: { port: 3000, }, -}; +};
dev.progressBar
- +;
d | boolean | { id?: string; - }; + };
d dev: { progressBar: false, }, -}; +};
如果需要修改进度条左侧显示的文本内容，可以设置
id选项：+};dev.startUrl
- +;
dev. // 打开多个页面 startUrl: ['http://localhost:8080', 'http://localhost:8080/about'], }, -}; +};
端口号占位符
由于端口号可能会发生变动，你可以使用
<port>占位符来指代当前端口号，Builder 会自动将占位符替换为实际监听的端口号。+};打开指定浏览器
在 MacOS 上，通过设置环境变量
BROWSER，你可以指定 Dev Server 在启动时打开的浏览器，支持如下的值：-
diff --git a/modern-js/builder/api/config-experiments.html b/modern-js/builder/api/config-experiments.html
index 6a19d0a784..ba1de5236a 100644
--- a/modern-js/builder/api/config-experiments.html
+++ b/modern-js/builder/api/config-experiments.html
@@ -1,4 +1,4 @@
-
Experiments Config - Modern.js Builder +Experiments Config - Modern.js Builder -Modern.js Builder +};Experiments Config
+Modern.js Builder + };Experiments Config
本章节描述了 Builder 中的一些实验性配置，实验性配置可以开启 Builder 中尚未稳定的功能。
-如果你在使用实验性功能时遇到问题，请先关闭对应的配置，并通过 GitHub Issues 进行反馈。
+如果你在使用实验性功能时遇到问题，请先关闭对应的配置，并通过 GitHub Issues 进行反馈。
experiments.lazyCompilation
- +;
imports?: boolean; // 是否为入口模块开启延迟编译 entries?: boolean; - };
用于开启延迟编译（即按需编译）的能力。当开启此配置项时，Builder 会进行延迟编译，提升项目的编译启动速度。
延迟编译只在开发环境下生效。
延迟编译异步模块
-延迟编译 dynamic import 引入的异步模块：
+延迟编译 dynamic import 引入的异步模块：
+};开启
imports选项后，所有的异步模块只有在被请求时才触发编译。如果你的项目是一个单页应用（SPA），并通过 dynamic import 进行了路由拆分，那么会有明显的编译提速效果。延迟编译入口模块
除了延迟编译异步模块，你也可以选择同时延迟编译入口模块和异步模块。
@@ -50,13 +50,13 @@entries: true, }, }, -};
以上配置也可以简化为：
+};开启
entries选项后，当启动编译时，不会编译所有的页面，而是仅在路由跳转到对应的页面时，才对该页面进行编译。使用延迟编译入口模块时，有以下注意事项：
-
@@ -70,9 +70,9 @@
使用代理<
Lazy Compilation 依赖 webpack 在本地启动的开发服务器，当你将某个域名代理到 localhost 进行开发时，Lazy Compilation 将无法正常工作。因此，如果你需要使用代理时，请禁用 Lazy Compilation。
其他潜在的问题
考虑到 Lazy Compilation 仍然是 webpack 的实验性功能，因此你在使用过程中，可能会遇到一些潜在的问题，比如编译产物的行为变化，或是编译出现异常。
-当你遇到这些问题时，可以参考 webpack 的 Issues 寻找解决方案，也可以关闭
+lazyCompilation配置项。当你遇到这些问题时，可以参考 webpack 的 Issues 寻找解决方案，也可以关闭
lazyCompilation配置项。experiments.sourceBuild
- +;
experiments: { sourceBuild: true, }, -}; -
更多信息可参考「源码构建模式」。
+}; +更多信息可参考「源码构建模式」。
选项
-
+experiments.sourceBuild底层基于 Rsbuild 的 Source Build 插件 实现，你可以传入插件选项，比如：experiments.sourceBuild底层基于 Rsbuild 的 Source Build 插件 实现，你可以传入插件选项，比如：\ No newline at end of file +};目录\ No newline at end of file diff --git a/modern-js/builder/api/config-html.html b/modern-js/builder/api/config-html.html index a262f4154b..28d3200b74 100644 --- a/modern-js/builder/api/config-html.html +++ b/modern-js/builder/api/config-html.html @@ -1,4 +1,4 @@ -目录Html Config - Modern.js Builder +Html Config - Modern.js Builder -Modern.js Builder Html Config
+Modern.js Builder +};Html Config
本章节描述了 Builder 中与 HTML 有关的配置。
html.appIcon
- +;
示例 html: { appIcon: './src/assets/icon.png', }, -};
设置为绝对路径：
+};重新编译后，HTML 中自动生成了以下标签：
-+html.crossorigin
- +;
用于设置
+<script>和<style>标签的 crossorigin 属性。用于设置
<script>和<style>标签的 crossorigin 属性。示例
+示例
+};编译后，HTML 中的
-<script>标签变为：+
-<style>标签变为：+可选值
crossorigin可以被设置为以下几个值：-
-
html.disableHtmlFolder
- +;
移除 HTML 产物对应的文件夹。开启该选项后，生成的 HTML 文件目录会从
-[name]/index.html变为[name].html。示例
+示例
默认情况下，HTML 产物在
dist目录下的结构为：+ └── index.html开启
html.disableHtmlFolder配置:+};重新编译后，HTML 产物在 dist 中的目录结构如下：
+ └── main.html如果需要设置 HTML 文件在 dist 目录中的路径，请使用
output.distPath.html配置。html.favicon
- +;
html
配置该选项后，在编译过程中会自动将图标拷贝至 dist 目录下，并在 HTML 中添加相应的
-link标签。示例
+示例
设置为相对路径：
+};设置为绝对路径：
+};设置为 URL：
+};重新编译后，HTML 中自动生成了以下标签：
-+html.faviconByEntries
- +;
用于在多页面的场景下，为不同的页面设置不同的 favicon。
整体用法与
favicon一致，并且可以使用「入口名称」作为 key ，对各个页面进行单独设置。
-faviconByEntries的优先级高于favicon，因此会覆盖favicon中设置的值。示例
+示例
+};重新编译后，可以看到:
-
-
html.inject
- +;
默认 <body> <div id="root"></div> </body> -</html> +</html>
插入至 body 标签
添加如下配置，可以将 script 插入至 body 标签：
+};可以看到 script 标签生成在 body 标签尾部：
+</html>html.injectByEntries
- +;
用于在多页面的场景下，为不同的页面设置不同的 script 标签插入位置。
整体用法与
inject一致，并且可以使用「入口名称」作为 key ，对各个页面进行单独设置。
-injectByEntries的优先级高于inject，因此会覆盖inject中设置的值。示例
+示例
+};重新编译后，可以看到:
-
-
html.meta
- +;
String description: 'a description of the page', }, }, -}; +};
最终在 HTML 中生成的
-meta标签为：+Object 类型
当
meta对象的value为对象时，会将该对象的key: value映射为meta标签的属性。这种情况下默认不会设置
@@ -250,9 +262,9 @@name和content属性。Object }, }, }, -}; +};
最终在 HTML 中生成的
-meta标签为：+移除默认值
将
meta对象的value设置为false，则表示不生成对应的 meta 标签。比如移除框架预设的
@@ -262,9 +274,9 @@imagemode：移除 imagemode: false, }, }, -}; +};
html.metaByEntries
- +;
用于在多页面的场景下，为不同的页面设置不同的 meta 标签。
整体用法与
meta一致，并且可以使用「入口名称」作为 key ，对各个页面进行单独设置。
-metaByEntries的优先级高于meta，因此会覆盖meta中设置的值。示例
+示例
+};编译后，可以看到页面
-foo的 meta 为：+其他页面的 meta 为：
-+html.mountId
- +;
html
默认情况下，HTML 模板中包含了
root节点用于组件挂载，通过mountId可以修改该节点的 id。-示例
+</body> +示例
修改 DOM 挂载节点
id为app：+};编译后：
+</body>注意事项
更新相关代码
在修改
mountId后，如果你的代码中有获取root根节点的逻辑，请更新对应的值：+ReactDOM.createRoot(domNode).render(<App />);自定义模板
如果你自定义了 HTML 模板，请确保模板中包含
<div id="<%= mountId %>"></div>，否则mountId配置项无法生效。html.scriptLoading
- +;
defer +<body></body>
TIP当浏览器遇到带有 defer 属性的
<script>标签时，它会异步地下载脚本文件，不会阻塞页面的解析和渲染。在页面解析和渲染完成后，浏览器会按照<script>标签在文档中出现的顺序依次执行它们。blocking
@@ -341,25 +353,25 @@blocking inject: 'body', scriptLoading: 'blocking', }, -}; +};
当你需要设置
blocking时，建议把html.inject设置为body，避免页面渲染被阻塞。+</body>module
将
scriptLoading设置为module时，可以让脚本支持 ESModule 语法，同时浏览器也会自动默认延迟执行这些脚本，效果与defer类似。+};+<body></body>html.tags
- +;
对象形式< * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head#see_also} */ head?: boolean; -} +}
对象形式的配置项可以用于描述需要注入的标签，并可以通过参数控制注入的位置：
+};这样的配置将会在 HTML 的
head最后添加一个script标签：+</html>标签最终的插入位置由
head和append选项决定，两个配置相同的元素将被插入到相同区域，并且维持彼此之间的相对位置。标签中表示外部资源文件路径的字段会受到
@@ -426,7 +438,7 @@publicPath和hash选项的影响， 这些字段包括script标签的src和link标签的href。函数形式< export type HtmlInjectTagHandler = ( tags: HtmlInjectTag[], utils: HtmlInjectTagUtils, -) => HtmlInjectTag[] | void; +) => HtmlInjectTag[] | void;
html.tags也支持传入回调函数，通过在回调中编写逻辑可以任意修改标签列表，常用于修改标签列表或是在插入标签的同时确保其相对位置。回调函数接受 tags 列表作为参数，并需要修改或直接返回新的 tags 数组：
+};函数将在 HTML 处理流程的最后被执行，即如下的例子中不管回调函数在配置项中的位置如何， 参数
tags都会包含配置项中所有的对象形式配置。也因此在回调中修改
@@ -473,15 +485,15 @@appendpublicPathhash等属性都不会生效，因为这些属性都已经分别应用到了标签的位置和路径属性。函数形式< <!-- tags with `{ head: false, append: true }` here. --> <script src="//example.com/a.js"></script> </body> -</html> +</html>
限制
-这个配置用于在 Builder 构建完成后修改 HTML 产物的内容，并不会引入和解析新的模块。因此，它无法用于引入未编译的源码文件，也无法代替 source.preEntry 等配置。
+这个配置用于在 Builder 构建完成后修改 HTML 产物的内容，并不会引入和解析新的模块。因此，它无法用于引入未编译的源码文件，也无法代替 source.preEntry 等配置。
例如对于以下项目：
+└── modern.config.ts+};modern.config.ts这里的 tag 对象将会在简单处理后直接添加到 HTML 产物中，但对应的
polyfill.ts将不会被转译、打包，也因此应用会在处理这行脚本时出现 404 错误。+</body>合理的使用场景包括：
限制│ └── index.tsx ├── public │ └── service-worker.js -└── modern.config.ts +└── modern.config.ts
+};modern.config.ts得到的产物将会类似：
+</body>html.tagsByEntries
- +;
用于在多页面的场景下，为不同的页面注入不同的标签。
整体用法与
tags一致，并且可以使用「入口名称」作为 key ，对各个页面进行单独设置。
-tagsByEntries的优先级高于tags，因此会覆盖tags中设置的值。示例
+示例
+};编译后，可以看到页面
-foo注入标签：+其他页面则注入了：
-+html.template
- +;
定义 HTML 模板的文件路径，对应 html-webpack-plugin 的
-template配置项。示例
+定义 HTML 模板的文件路径，对应 html-webpack-plugin 的
+template配置项。示例
使用自定义的 HTML 模板文件替代默认模板，可以添加如下设置：
+};html.templateByEntries
- +;
用于在多页面的场景下，为不同的页面设置不同的 HTML 模板。
整体用法与
template一致，并且可以使用「入口名称」作为 key ，对各个页面进行单独设置。
-templateByEntries的优先级高于template，因此会覆盖template设置的值。示例
+示例
+};html.templateParameters
- +;
files: object; options: object; }; -}; -
定义 HTML 模板中的参数，对应 html-webpack-plugin 的
+}; +templateParameters配置项。你可以使用配置为对象或者函数。定义 HTML 模板中的参数，对应 html-webpack-plugin 的
templateParameters配置项。你可以使用配置为对象或者函数。如果是对象，会和默认参数合并。比如：
+};如果是函数，会传入默认参数，你可以返回一个对象，用于覆盖默认参数。比如：
-示例
+}; +示例
如果需要在 HTML 模板中使用
foo参数，可以添加如下设置：+};或者使用函数配置：
+};接下来，你可以在 HTML 模板中，通过
-<%= foo %>来读取参数：+经过编译后的最终 HTML 代码如下：
-+html.templateParametersByEntries
- +;
用于在多页面的场景下，为不同的页面设置不同的模板参数。
整体用法与
templateParameters一致，并且可以使用「入口名称」作为 key ，对各个页面进行单独设置。
-templateParametersByEntries的优先级高于templateParameters，因此会覆盖templateParameters中设置的值。示例
+示例
+};html.title
- +;
html.t html: { title: 'example', }, -}; +};
html.titleByEntries
- +;
用于在多页面的场景下，为不同的页面设置不同的
title。整体用法与
title一致，并且可以使用「入口名称」作为 key ，对各个页面进行单独设置。
-titleByEntries的优先级高于title，因此会覆盖title中设置的值。示例
+示例
+};重新编译后，可以看到:
Output Config - Modern.js Builder +Output Config - Modern.js Builder -Modern.js Builder +};Output Config
+Modern.js Builder +};Output Config
本章节描述了 Builder 中与构建产物有关的配置。
output.assetPrefix
- +;
示例 output: { assetPrefix: 'https://cdn.example.com/assets/', }, -};
构建之后，可以看到 JS 文件从以下地址加载：
+></script>与原生配置的区别
output.assetPrefix对应以下原生配置：-
-
它与原生配置的区别在于：
-
-
output.assetsRetry
- +;
onRetry?: (options: AssetsRetryHookContext) => void; onSuccess?: (options: AssetsRetryHookContext) => void; onFail?: (options: AssetsRetryHookContext) => void; -};
由于该能力会往 HTML 中注入额外的一些运行时代码，因此我们默认关闭了该能力，如果需要开启该能力，你可以添加以下配置：
+};当你开启该能力后，
assetsRetry的默认配置如下：+};同时你也可以使用以下的配置项，来定制你的重试逻辑。
assetsRetry.domain
-
@@ -98,7 +104,7 @@
asse domain: ['https://cdn1.com', 'https://cdn2.com', 'https://cdn3.com'], }, }, -}; +};
添加以上配置后，当
cdn1.com域名的资源加载失败时，请求域名会自动降级到cdn2.com。如果
cdn2.com的资源也请求失败，则会继续请求cdn3.com。assetsRetry.type
@@ -114,7 +120,7 @@assets type: ['script', 'link'], }, }, -}; +};
assetsRetry.max
assetsR max: 5, }, }, -}; +};
assetsRetry.test
assets test: /cdn\.example\.com/, }, }, -}; +};
assetsRetry.crossOrigin
crossOrigin: true, }, }, -}; +};
assetsRetry.onRetry
ass }, }, }, -}; +};
assetsRetry.onSuccess
a }, }, }, -}; +};
assetsRetry.onFail
asse }, }, }, -}; +};
assetsRetry.inlineScript
inlineScript: false, }, }, -}; +};
添加以上配置后，
assetsRetry的运行时代码会被抽取为一个独立的assets-retry.[version].js文件，并输出到产物目录下。这种方式的弊端在于，
assets-retry.[version].js自身有加载失败的可能性。如果出现这种情况，静态资源重试的逻辑就无法生效。因此，我们更推荐将运行时代码内联到 HTML 文件中。注意事项
@@ -241,7 +247,7 @@注意事 }, }, }, -}; +};
使用限制
以下场景
assetsRetry可能无法生效：微前端应用
@@ -251,7 +257,7 @@动
目前
assetsRetry无法对动态 import 资源生效，该功能正在支持中。自定义模版中的资源
-assetsRetry通过监听页面 error 事件来获悉当前资源是否加载失败需要重试。因此，如果自定义模版中的资源执行早于assetsRetry，那assetsRetry无法监听到该资源加载失败的事件，故无法 retry。如果想要
+assetsRetry对自定义模版中的资源生效，可参考 自定义插入示例 来修改 html.inject 配置和自定义模版。如果想要
assetsRetry对自定义模版中的资源生效，可参考 自定义插入示例 来修改 html.inject 配置和自定义模版。+</html>output.charset
- +;
ou output: { charset: 'utf8', }, -}; +};
当
output.charset为utf8时，Builder 会自动将<meta charset="utf-8">添加到生成的 HTML 文件中。output.cleanDistPath
- +;
output: { cleanDistPath: false, }, -}; +};
output.convertToRem
- +;
Boolean output: { convertToRem: true, }, -}; +};
此时，rem 配置默认如下：
+}Object 类型
当
output.convertToRem的值为object类型时，Builder 会根据当前配置进行 rem 处理。选项：
@@ -397,12 +403,12 @@Object
pxtorem objectrootValue。默认与 rootFontSize 相同 unitPrecision: 5。精确位数 propList: ['*']。支持转换的 CSS 属性 -postcss-pxtorem 插件属性 +postcss-pxtorem 插件属性 示例
+示例
+};output.copy
- +;
outpu output: { copy: [{ from: './src/assets', to: '' }], }, -}; -
更详细的配置项请参考：copy-webpack-plugin 文档。
+}; +更详细的配置项请参考：copy-webpack-plugin 文档。
output.cssModules
- +;
type CssModules = { auto?: boolean | RegExp | ((resourcePath: string) => boolean); exportLocalsConvention?: CssModuleLocalsConvention; -}; +};
+};自定义 CSS 模块配置。
cssModules.auto
auto 配置项允许基于文件名自动启用 CSS 模块。
@@ -463,7 +469,7 @@cssModu
类型说明：
-
-
cssModu }, }, }, -}; +};
cssModules.exportLocalsConvention
导出的类名称的样式。
-
@@ -502,9 +508,9 @@
exportLocalsConvention: 'camelCaseOnly', }, }, -}; +};
output.cssModuleLocalIdentName
- +;
+ : '[path][name]__[local]-[hash:base64:6]';
设置 CSS Modules 编译后生成的 className 格式。
默认值
@@ -521,7 +527,7 @@cssModuleLocalIdentName在开发环境和生产环境有不同的默认值。默认值 // 在开发环境下，值为 `.src-index-module__header--xxxxx` // 在生产环境下，值为 `.xxxxx` -console.log(styles.header); +console.log(styles.header);
模板字符串
在
cssModuleLocalIdentName中，你可以使用以下模板字符串：-
@@ -536,15 +542,15 @@
模板
-TIP在使用 Rspack 作为打包工具时, 暂不支持配置
<hashDigest>。示例
+示例
将
cssModuleLocalIdentName设置为其他值：+};output.dataUriLimit
- +;
font?: number; image?: number; media?: number; -}; +};
font: 10000, image: 10000, media: 10000, -}; +};
设置图片、字体、媒体等静态资源被自动内联为 base64 的体积阈值。
默认情况下，体积小于 10KB 的图片、字体、媒体等文件，会自动经过 Base64 编码，内联到页面中，不再会发送独立的 HTTP 请求。
你可以通过修改
@@ -573,7 +579,7 @@dataUriLimit参数来调整这个阈值。image：表示非 SVG 图片的体积阈值。 media：表示视频等媒体资源的体积阈值。
示例
+示例
修改图片资源的阈值为 5000 Bytes，设置视频资源不内联：
+};output.disableCssExtract
- +;
- 类型：
boolean - 默认值：
false
是否禁用 CSS 提取逻辑，并将 CSS 文件内联到 JS 文件中。
默认情况下，Builder 会把 CSS 提取为独立的
-.css文件，并输出到构建产物目录。设置该选项为true后，CSS 文件会被内联到 JS 文件中，并在运行时通过<style>标签插入到页面上。示例
+示例
+};output.disableCssModuleExtension
- +;
- 类型：
boolean - 默认值：
false
@@ -608,12 +614,12 @@ - 类型：
- 默认值：
- 类型：
boolean - 默认值：
false
@@ -714,10 +720,10 @@ - 类型：
- 默认值：
- 类型：
boolean - 默认值：
false
@@ -775,9 +781,9 @@ - 类型：
boolean - 默认值：
false
@@ -789,58 +795,58 @@ - 在开发环境构建时，类型错误不会阻塞编译流程。
- 在生产环境构建时，类型错误会导致构建失败，以保证生产环境代码的稳定性。
- 类型：
boolean - 默认值：
false - 类型：
boolean - 默认值：
false - 类型：
boolean - 默认值：
false - web 产物：
asset-manifest.json
- - node 产物：
asset-manifest-node.json
+ -
+
web 产物：
+asset-manifest.json
+ -
+
node 产物：
+asset-manifest-node.json - 类型：
boolean - 默认值：
false - 类型：
boolean - 默认值：
false - 类型：
boolean - 默认值：
false
@@ -934,43 +944,43 @@ - 类型：
- 默认值：
false - 类型：
- 默认值：
false name：文件名，比如static/css/main.18a568e5.css。
@@ -1065,16 +1075,16 @@ - 类型：
string | object | function | RegExp - 默认值：
undefined - 类型：
- 默认值：
image：表示非 SVG 图片的名称。media：表示视频等媒体资源的名称。
.sass、.scss和.less文件的处理规则与.css文件一致，也会受到disableCssModuleExtension的影响。-TIP我们不推荐开启此配置项，因为开启
disableCssModuleExtension后，CSS Modules 文件和普通 CSS 文件无法得到明确的区分，不利于长期维护。示例
+示例
+};规则
以下是对 CSS Modules 判断规则的详细解释：
未开启 disableCssModuleExtension（默认）
@@ -640,7 +646,7 @@TIP对于 node_modules 中的 CSS Modules 文件，请始终使用
*.module.css后缀。output.distPath
- +;
o media?: string; server?: string; worker?: string; -}; +};
o media: 'static/media', server: 'bundles', worker: 'worker', -}; +};
设置构建产物的输出目录，Builder 会根据产物的类型输出到对应的子目录下。
其中：
-
@@ -691,7 +697,7 @@
o
根目录
root是构建产物的根目录，可以为相对路径或绝对路径。如果root的值为相对路径，则会基于当前项目的根目录拼接为绝对路径。其他目录只能为相对路径，并且会相对于
-root进行输出。示例
+示例
以 JavaScript 文件为例，会输出到
distPath.root+distPath.js目录，即为dist/static/js。如果需要将 JavaScript 文件输出到
build/resource/js目录，可以这样设置：+};output.disableMinimize
- +;
output: { disableMinimize: true, }, -}; +};
TIP该配置项通常用于代码调试和问题排查，不建议在生产环境禁用代码压缩，否则会导致页面性能显著下降。
output.disableSourceMap
- +;
| { js?: boolean; css?: boolean; - }; + };
+};是否禁用 Source Map 生成。
什么是 Source MapSource Map 是保存源代码映射关系的信息文件，它记录了编译后的代码的每一个位置，以及所对应的编译前的位置。通过 Source Map，可以在调试编译后的代码时，直接查看对应的源代码。
默认情况下，Builder 的 Source Map 生成规则如下：
@@ -746,13 +752,13 @@output: { disableSourceMap: true, }, -}; +};
如果需要开启开发环境的 Source Map，并在生产环境禁用，可以设置为：
+};如果需要单独控制 JS 文件或 CSS 文件的 Source Map，可以参考下方设置：
+};output.disableSvgr
- +;
output: { disableSvgr: true, }, -}; +};
output.disableTsChecker
- +;
阻塞编
示例
+示例
禁用 TypeScript 类型检查：
+};禁用开发环境构建时的类型检查：
+};禁用生产环境构建时的类型检查：
+};TIP不建议在生产环境构建时禁用类型检查，这会导致线上代码的稳定性下降，请谨慎使用。
output.disableFilenameHash
- +;
移除生产环境的构建产物名称中的 hash 值。
在生产环境构建后，会自动在文件名中间添加 hash 值，如果不需要添加，可以通过
-output.disableFilenameHash配置来禁用该行为。示例
+示例
默认情况下，构建后的产物名称为：
+dist/static/js/main.18a568e5.js 2.24 KB 922 B添加
output.disableFilenameHash配置：+};重新构建，产物的名称变为：
+dist/static/js/main.js 2.24 KB 922 Boutput.disableInlineRuntimeChunk
- +;
用于控制是否将打包工具的 runtime 代码内联到 HTML 中。
什么是 runtimeChunk在生产环境下，Builder 默认会将 runtimeChunk 文件内联到 HTML 文件中，而不是写到产物目录中，这样做是为了减少文件请求的数量。
禁用内联
@@ -849,7 +855,7 @@禁用内 output: { disableInlineRuntimeChunk: true, }, -}; +};
合并到页面文件中
如果你不希望生成独立的 runtimeChunk 文件，而是想让 runtimeChunk 代码被打包到页面的 JS 文件里，可以这样设置：
+};output.enableAssetManifest
- +;
是否生成 manifest 文件，该文件包含所有构建产物的信息。
-示例
+示例
添加以下配置来开启：
+};开启后，当编译完成时，会自动生成
dist/asset-manifest.json文件：+}如果当前项目有多种类型构建产物，比如包含了 SSR 构建产物，那么会生成多份 manifest.json 文件。
-
-
output.enableAssetFallback
- +;
开启该选项后，当编译过程中遇到无法识别的文件类型时，会直接将该文件直接输出到产物目录；否则会抛出一个异常。
-示例
+示例
开启配置项：
+};在代码中引用一个未知类型的模块：
-+编译后，
foo.xxx会被自动输出到dist/static/media目录下。你可以通过
output.distPath.media和output.filename.media配置项来控制 fallback 后的输出路径和文件名称。TIP开启该配置会导致 webpack 配置中的 rules 结构变化，增加一层额外的
oneOf嵌套结构。大多数情况下，我们不推荐你使用此配置。output.enableLatestDecorators
- +;
是否要使用 新版 decorator 提案 进行编译。
-默认情况下，Builder 在编译装饰器时采用 旧版 decorator 提案。
+是否要使用 新版 decorator 提案 进行编译。
+默认情况下，Builder 在编译装饰器时采用 旧版 decorator 提案。
将
output.enableLatestDecorators设置为true时，Builder 会采用新版 decorator 提案 (2018-09 版本) 进行编译。+};output.enableCssModuleTSDeclaration
- +;
Example output: { enableCssModuleTSDeclaration: true, }, -}; +};
项目构建完成后，每个 CSS Module 文件都会生成一个
.d.ts文件。例如：+export default cssExports;output.enableInlineScripts
- +;
+ | ((params: { size: number; name: string }) => boolean);用来控制生产环境中是否用
<script>标签将产物中的 script 文件（.js 文件）inline 到 HTML 中。注意，如果开启了这个选项，那么 script 文件将不会被写入产物目录中，而只会以 inline 脚本的形式存在于 HTML 文件中。
-TIP当使用约定式路由时，如果开启了这个选项，需要将 output.splitRouteChunks 设置为 false。 +
-TIP当使用约定式路由时，如果开启了这个选项，需要将 output.splitRouteChunks 设置为 false。
示例
+示例
默认情况下，我们有这样的产物文件：
+dist/static/js/main.js开启
output.enableInlineScripts选项后：+};产物文件将变成：
+dist/static/css/style.css同时，
dist/static/js/main.js文件将被 inline 到index.html中：+</html>通过正则匹配
当你需要内联产物中的一部分 JS 文件时，你可以将
enableInlineScripts设置为一个正则表达式，匹配需要内联的 JS 文件的 URL。比如，将产物中的
@@ -986,7 +996,7 @@main.js内联到 HTML 中，你可以添加如下配置：通 output: { enableInlineScripts: /\/main\.\w+\.js$/, }, -}; +};
TIP生产环境的文件名中默认包含了一个 hash 值，比如
static/js/main.18a568e5.js。因此，在正则表达式中需要通过\w+来匹配 hash。通过函数匹配
@@ -1002,37 +1012,37 @@通 return size < 10 * 1000; }, }, -}; +};
output.enableInlineStyles
- +;
+ | ((params: { size: number; name: string }) => boolean);用来控制生产环境中是否用
<style>标签将产物中的 style 文件（.css 文件）inline 到 HTML 中。注意，如果开启了这个选项，那么 style 文件将不会被写入产物目录中，而只会以 inline 样式的形式存在于 HTML 文件中。
-TIP当使用约定式路由时，如果开启了这个选项，需要将 output.splitRouteChunks 设置为 false。 +
-TIP当使用约定式路由时，如果开启了这个选项，需要将 output.splitRouteChunks 设置为 false。
示例
+示例
默认情况下，我们有这样的产物文件：
+dist/static/js/main.js开启
output.enableInlineStyles选项后：+};产物文件将变成：
+dist/static/js/main.js同时，
dist/static/css/style.css文件将被 inline 到index.html中：-通过正则匹配
+</html> +通过正则匹配
当你需要内联产物中的一部分 CSS 文件时，你可以将
enableInlineStyles设置为一个正则表达式，匹配需要内联的 CSS 文件的 URL。比如，将产物中的
main.css内联到 HTML 中，你可以添加如下配置：+};-TIP生产环境的文件名中默认包含了一个 hash 值，比如
static/css/main.18a568e5.css。因此，在正则表达式中需要通过\w+来匹配 hash。通过函数匹配
+通过函数匹配
你也可以将
output.enableInlineStyles设置为一个函数，函数接收以下参数：通 return size < 10 * 1000; }, }, -}; +};
output.externals
- +;
在构建时，防止将代码中某些
-import的依赖包打包到 bundle 中，而是在运行时再去从外部获取这些依赖。详情请见: webpack 外部扩展 (Externals)
-示例
+详情请见: webpack 外部扩展 (Externals)
+示例
将
react-dom依赖从构建产物中剔除。为了在运行时获取这个模块,react-dom的值将全局检索ReactDOM变量。+};TIP当构建 Web Worker 产物时，externals 将不会生效。这是因为 Worker 环境不支持通过访问全局变量。
output.filename
- +;
o font?: string; image?: string; media?: string; -}; +};
o font: '[name].[contenthash:8][ext]', image: '[name].[contenthash:8][ext]', media: '[name].[contenthash:8][ext]', -}; +};
设置构建产物的名称。
在生产环境构建后，会自动在文件名中间添加 hash 值，如果不需要添加，可以通过
output.disableFilenameHash配置来禁用该行为。下面是各个文件类型的说明：
@@ -1130,7 +1140,7 @@o
示例
+示例
修改 JavaScript 文件的名称为
[name]_script.js：+};文件名中的 hash 值通常来说，我们只会在生产环境下设置文件名的 hash 值（即
-process.env.NODE_ENV === 'production'时）。如果你在开发环境下设置了文件名的 hash，那么可能会导致热更新不生效（尤其是 CSS 文件）。这是因为每次文件内容变化时，都会引起 hash 变化，导致 mini-css-extract-plugin 等工具无法读取到最新的文件内容。 +
如果你在开发环境下设置了文件名的 hash，那么可能会导致热更新不生效（尤其是 CSS 文件）。这是因为每次文件内容变化时，都会引起 hash 变化，导致 mini-css-extract-plugin 等工具无法读取到最新的文件内容。
异步模块的文件名
当你在代码中通过 dynamic import 的方式引入模块时，该模块会被单独打包成一个文件，它默认的命名规则如下：
@@ -1151,14 +1161,14 @@在开发环境下会基于模块路径生成名称，比如
dist/static/js/async/src_add_ts.js。 - 在生产环境下会是一个随机的数字 id，比如
dist/static/js/async/798.27e3083e.js，这是为了避免在生产环境中泄露源代码的路径，同时字符数也更少。 - 类型：
'linked' | 'inline' | 'none' - 默认值：
'linked'
@@ -1171,27 +1181,27 @@ none：移除所有 legal comments。- 类型：
string[] | Record<BuilderTarget, string[]> - 默认值：
undefined - 类型：
'entry' | 'usage' | 'ua' | 'off' - 默认值：
'entry'
@@ -1238,11 +1248,11 @@ - 类型：
'url' | 'component' - 默认值：
'url'
@@ -1251,12 +1261,12 @@ - 类型：
- 默认值：
- 打包工具：
仅支持 webpack - 类型：
Object | undefined - 添加环境变量
BUNDLE_ANALYZE=true，比如： - 配置
performance.bundleAnalyze来固定开启： - 开启 Server 模式会导致
build进程不能正常退出。
- - 开启 bundleAnalyzer 会降低构建性能。因此，在日常开发过程中不应该开启此配置项，建议通过
BUNDLE_ANALYZE环境变量来按需开启。
- - 由于
dev阶段不会进行代码压缩等优化，无法反映真实的产物体积，因此建议在build阶段分析产物体积。
+ -
+
开启 Server 模式会导致
+build进程不能正常退出。
+ -
+
开启 bundleAnalyzer 会降低构建性能。因此，在日常开发过程中不应该开启此配置项，建议通过
+BUNDLE_ANALYZE环境变量来按需开启。
+ -
+
由于
+dev阶段不会进行代码压缩等优化，无法反映真实的产物体积，因此建议在build阶段分析产物体积。 - 类型：
Object - 默认值：
{ strategy: 'split-by-experience' }
@@ -169,7 +175,7 @@ - 类型：
number
@@ -220,7 +226,7 @@ - 类型：
RegExp[] | Record<string, RegExp>
@@ -237,7 +243,7 @@ -
类型：
@@ -290,37 +296,37 @@undefined | string[]默认值：
undefined - 类型：
undefined | Array<string | PreconnectOption> - 默认值：
undefined - 类型：
undefined | true | PrefetchOption - 默认值：
undefined all-chunks: 预获取所有资源(当前页面)，包含所有异步和非异步资源。all-assets: 预获取所有资源，MPA 场景下会包含其他页面的资源。- 类型：
undefined | true | PreloadOption - 默认值：
undefined all-assets: 预加载所有资源，MPA 场景下会包含其他页面的资源。- 类型：
boolean - 默认值：
true
@@ -422,30 +428,30 @@ - 类型：
boolean - 默认值：
false - 类型：
boolean | ConsoleType[] - 默认值：
false
@@ -457,62 +463,62 @@ - 类型：
boolean - 默认值：
false - 类型：
boolean - 默认值：
true - 打包工具：
仅支持 webpack - 类型：
- 默认值：
undefined - 打包工具：
仅支持 webpack - 类型：
- 默认值：
false - 类型：
string[] - 默认值：
当前项目的 browserslist 配置 - 示例： @@ -116,7 +116,7 @@
- 类型：
Record<string, string | string[]> | Function - 默认值：
undefined - 类型：
'prefer-tsconfig' | 'prefer-alias' - 默认值：
'prefer-tsconfig'
@@ -108,7 +108,7 @@ source.alias:@common会使用 tsconfig paths 定义的值，指向./src/common-1
@@ -131,7 +131,7 @@ - tsconfig paths: @@ -143,7 +143,7 @@
source.alias:- 类型： RuleSetCondition[] +
- 类型： RuleSetCondition[]
- 默认值：
- 类型：
Array<string | RegExp> - 默认值：
[] - 类型：
Record<string, unknown> - 默认值：
{}
@@ -290,8 +290,8 @@ - 嵌套对象的父子键名之间会用
.连接作为需要替换的变量名。 - 以 typeof 开头的键名会用来替换 typeof 调用。
- 类型：
Record<string, JSONValue> | Function - 默认值： @@ -321,13 +321,13 @@
- 类型： @@ -350,7 +350,7 @@
- 类型：
Array<string | Regexp> | Function - 默认值：
undefined - 打包工具：
仅支持 webpack - 类型：
- 默认值：
- 类型：
boolean
@@ -519,10 +519,10 @@ - 类型：
string
@@ -530,10 +530,10 @@ - 类型：
boolean
@@ -541,12 +541,12 @@ - 类型：
boolean
@@ -554,12 +554,12 @@ - 类型：
((member: string) => string | undefined) | string
@@ -572,7 +572,7 @@ - 类型：
((member: string) => string | undefined) | string
@@ -585,9 +585,9 @@ - 类型：
string | string[] - 默认值：
undefined
@@ -595,13 +595,13 @@ - 类型：
string | Record<BuilderTarget, string> - 默认值：
undefined - 类型：
- 默认值：
undefined - 类型：
Object | Function - 默认值： @@ -21,8 +21,8 @@
- 类型：
Object | Function - 默认值：
undefined - Rspack 场景：在使用 Rspack 作为打包工具时，使用
tools.babel配置项将会明显拖慢 Rspack 构建速度。因为 Rspack 默认使用的是 SWC 编译，配置 Babel 会导致代码需要被编译两次，产生了额外的编译开销。 - webpack + SWC 场景：在使用 webpack 作为打包工具时，如果你使用了 Builder 的 SWC 插件进行代码编译，那么
tools.babel选项将不会生效。 - 类型：
(presets: BabelPlugin[]) => void
@@ -129,7 +129,7 @@ - 类型：
(plugins: string | string[]) => void
@@ -141,7 +141,7 @@ - 类型：
(presets: string | string[]) => void
@@ -153,12 +153,12 @@ - 类型：
(options: PresetEnvOptions) => void - 类型：
(options: PresetReactOptions) => void - 类型：
Function | undefined - 默认值：
undefined
@@ -210,290 +210,14 @@ - 类型：
'development' | 'production' | 'test'
- - 类型：
boolean
- - 类型：
'web' | 'node' | 'modern-web' | 'web-worker'
- - 类型：
boolean
- - 类型：
boolean
- - 类型：
typeof import('html-webpack-plugin') | import('@rspack/plugin-html')
- - 类型：
Object | Function - 默认值： @@ -508,12 +232,12 @@
- 打包工具：
仅支持 webpack - 类型：
Object | Function - 默认值：
undefined - 类型：
Object - 默认值：
{} - 类型：
Array
@@ -641,7 +365,7 @@ - 类型： @@ -655,7 +379,7 @@
- 默认值：
- 类型：
- 默认值：
- 类型：
Record<string, string>
@@ -711,7 +435,7 @@ - 类型：
boolean | ConnectHistoryApiFallbackOptions
@@ -724,14 +448,14 @@ - 类型：
boolean - 默认值：
true - 类型：
boolean | { key: string; cert: string }
@@ -748,7 +472,7 @@ - 类型：
boolean
@@ -772,7 +496,7 @@ - 默认值：
undefined - sockWrite。允许向 hmr 客户端传递一些消息，hmr 客户端将根据接收到的消息类型进行不同的处理。如果你发送一个 "content-changed " 的消息，页面将会重新加载。 @@ -812,7 +536,7 @@
- 类型：
Record<string, string> | Record<string, ProxyDetail>
@@ -827,8 +551,8 @@ - bypass：根据函数的返回值绕过代理。
@@ -890,7 +614,7 @@
proxy }, }, }, -}; +};
+};watch
- 类型：
boolean
@@ -911,7 +635,7 @@ - 类型：
false | Object | Function - 默认值： @@ -936,9 +660,9 @@
- 第一个参数是默认配置的对象，可以直接修改该对象。 @@ -962,14 +686,14 @@
- 类型：
Object | Function - 默认值： @@ -994,9 +718,9 @@
- 类型：
(excludes: RegExp | RegExp[]) => void - 类型：
Object | Function | undefined - 默认值： @@ -1056,11 +780,11 @@
- 类型：
Object | Function - 默认值： @@ -1106,9 +830,9 @@
- 类型：
(plugins: PostCSSPlugin | PostCSSPlugin[]) => void - 类型：
true | Object | Function | undefined - 默认值：
false - 类型：
Object | Function - 默认值： @@ -1213,9 +937,9 @@
- 类型：
(excludes: RegExp | RegExp[]) => void - 类型：
Object | Function - 默认值：
{} - 类型：
Object | Function | false - 默认值： @@ -1298,15 +1022,15 @@
- 类型：
Object | Function | undefined - 默认值： @@ -1334,12 +1058,12 @@
- 打包工具：
仅支持 webpack - 类型：
Object | Function | undefined - 默认值：
undefined - 打包工具：
仅支持 webpack - 类型：
Object | Function - 默认值： @@ -1434,9 +1158,9 @@
- 类型：
Object | Function | undefined - 默认值：
undefined - 打包工具：
仅支持 webpack - 类型：
boolean
@@ -1526,7 +1250,7 @@ - 类型：
'web' | 'node' | 'modern-web' | 'web-worker'
@@ -1541,7 +1265,7 @@ - 类型：
boolean
@@ -1556,7 +1280,7 @@ - 类型：
boolean
@@ -1571,7 +1295,7 @@ - 类型：
typeof import('webpack')
@@ -1584,7 +1308,7 @@ - 类型：
typeof import('html-webpack-plugin')
@@ -1596,12 +1320,12 @@ - 类型：
(rules: RuleSetRule | RuleSetRule[]) => void - 类型：
(plugins: WebpackPluginInstance | WebpackPluginInstance[]) => void
@@ -1645,7 +1369,7 @@ - 类型：
(plugins: WebpackPluginInstance | WebpackPluginInstance[]) => void
@@ -1665,25 +1389,25 @@ - 类型：
(name: string) => void - 类型：
(...configs: WebpackConfig[]) => WebpackConfig - 类型：
(name: string) => string - 类型：
Function | undefined - 默认值：
undefined
@@ -1714,8 +1438,8 @@ - 类型：
'development' | 'production' | 'test' - 类型：
boolean - 类型：
'web' | 'node' | 'modern-web' | 'web-worker' - 类型：
boolean - 类型：
boolean - 类型：
typeof import('webpack') - 类型：
typeof import('html-webpack-plugin') - 类型：
(name: string) => string - 类型：
Object | Function | undefined - 默认值：
undefined - 打包工具：
仅支持 Rspack - 类型：
'development' | 'production' | 'test' - 类型：
boolean - 类型：
'web' | 'node' | 'modern-web' | 'web-worker' - 类型：
boolean - 类型：
boolean - 类型：
typeof import('@rspack/core')
@@ -2265,12 +1989,12 @@ - 类型：
(rules: RuleSetRule | RuleSetRule[]) => void - 类型：
(plugins: RspackPluginInstance | RspackPluginInstance[]) => void - 类型：
(plugins: RspackPluginInstance | RspackPluginInstance[]) => void - 类型：
(name: string) => void - 类型：
(...configs: RspackConfig[]) => RspackConfig - 类型：
(name: string) => string - html.appIcon
- html.crossorigin
- html.disableHtmlFolder
- html.favicon
- html.faviconByEntries
- html.inject
- html.injectByEntries
- html.meta
- html.metaByEntries
- html.mountId
- html.scriptLoading
- html.tags
- html.tagsByEntries
- html.template
- html.templateByEntries
- html.templateParameters
- html.templateParametersByEntries
- html.title
- html.titleByEntries
- output.assetPrefix
- output.assetsRetry
- output.charset
- output.cleanDistPath
- output.convertToRem
- output.copy
- output.cssModules
- output.cssModuleLocalIdentName
- output.dataUriLimit
- output.disableCssExtract
- output.disableCssModuleExtension
- output.distPath
- output.disableMinimize
- output.disableSourceMap
- output.disableSvgr
- output.disableTsChecker
- output.disableFilenameHash
- output.disableInlineRuntimeChunk
- output.enableAssetManifest
- output.enableAssetFallback
- output.enableLatestDecorators
- output.enableCssModuleTSDeclaration
- output.enableInlineScripts
- output.enableInlineStyles
- output.externals
- output.filename
- output.legalComments
- output.overrideBrowserslist
- output.polyfill
- output.svgDefaultExport
- builder.context
- builder.build
- builder.startDevServer
- builder.serve
- builder.createCompiler
- builder.addPlugins
- builder.removePlugins
- builder.isPluginExists
- builder.inspectConfig
- builder.onBeforeCreateCompiler
- builder.onAfterCreateCompiler
- builder.onBeforeBuild
- builder.onAfterBuild
- builder.onBeforeStartDevServer
- builder.onAfterStartDevServer
- builder.onDevCompileDone
- builder.onExit
- builder.getBuilderConfig
- builder.getNormalizedConfig
- builder.getHTMLPaths
- html.appIcon
- html.crossorigin
- html.disableHtmlFolder
- html.favicon
- html.faviconByEntries
- html.inject
- html.injectByEntries
- html.meta
- html.metaByEntries
- html.mountId
- html.scriptLoading
- html.tags
- html.tagsByEntries
- html.template
- html.templateByEntries
- html.templateParameters
- html.templateParametersByEntries
- html.title
- html.titleByEntries
- output.assetPrefix
- output.assetsRetry
- output.charset
- output.cleanDistPath
- output.convertToRem
- output.copy
- output.cssModules
- output.cssModuleLocalIdentName
- output.dataUriLimit
- output.disableCssExtract
- output.disableCssModuleExtension
- output.distPath
- output.disableMinimize
- output.disableSourceMap
- output.disableSvgr
- output.disableTsChecker
- output.disableFilenameHash
- output.disableInlineRuntimeChunk
- output.enableAssetManifest
- output.enableAssetFallback
- output.enableLatestDecorators
- output.enableCssModuleTSDeclaration
- output.enableInlineScripts
- output.enableInlineStyles
- output.externals
- output.filename
- output.legalComments
- output.overrideBrowserslist
- output.polyfill
- output.svgDefaultExport
- builder.context
- builder.build
- builder.startDevServer
- builder.serve
- builder.createCompiler
- builder.addPlugins
- builder.removePlugins
- builder.isPluginExists
- builder.inspectConfig
- builder.onBeforeCreateCompiler
- builder.onAfterCreateCompiler
- builder.onBeforeBuild
- builder.onAfterBuild
- builder.onBeforeStartDevServer
- builder.onAfterStartDevServer
- builder.onDevCompileDone
- builder.onExit
- builder.getBuilderConfig
- builder.getNormalizedConfig
- builder.getHTMLPaths
- Example
- 类型
- Example
- 类型
- Example
- 类型
- Example
- 类型
- Example
- Example
- Example
- Example
- Example
- Example
- Example
- Example
-
@@ -303,7 +303,7 @@
onBefore callback: (params: { bundlerConfigs?: WebpackConfig[] | RspackConfig[]; }) => Promise<void> | void, -): void; +): void;
- Example
onBefore console.log('the bundler config is ', bundlerConfigs); }); }, -}); +});
onAfterBuild
- +;
onAfterBuild是在执行生产环境构建后触发的回调函数，你可以通过stats参数获取到构建结果信息：-
@@ -330,7 +330,7 @@
onAfterBu
+): void;- Example
onAfterBu console.log(stats?.toJson()); }); }, -}); +});
开发服务钩子
onBeforeStartDevServer
- +;
在启动开发服务器前调用。
- 类型
+- Example
console.log('before start!'); }); }, -}); +});
onAfterStartDevServer
- +;
在启动开发服务器后调用，你可以通过
port参数获得开发服务器监听的端口号。- 类型
+): void;- Example
console.log('this port is: ', port); }); }, -}); +});
onDevCompileDone
- +;
在每次开发环境构建结束后调用，你可以通过
isFirstCompile来判断是否为首次构建。- 类型
+): void;- Example
onDev } }); }, -}); +});
其他钩子
onExit
- +;
在进程即将退出时调用，这个钩子只能执行同步代码。
- 类型
+- Example
onExit console.log('exit!'); }); }, -});
\ No newline at end of file +});目录\ No newline at end of file diff --git a/modern-js/builder/en/api/builder-core.html b/modern-js/builder/en/api/builder-core.html index e45471d1bc..e4e7e8ae5d 100644 --- a/modern-js/builder/en/api/builder-core.html +++ b/modern-js/builder/en/api/builder-core.html @@ -1,4 +1,4 @@ -目录Builder Core - Modern.js Builder +Builder Core - Modern.js Builder -Modern.js Builder +console.log(mergedConfig); // { dev: { https: true } }Builder Core
+Modern.js Builder +});Builder Core
This section describes some of the core methods provided by Builder.
createBuilder
Create a Builder instance object.
@@ -26,7 +26,7 @@const builder = await createBuilder(provider, { // some options -});
builderRspackProvider
When
builderRspackProvideris passed, the Builder will use Rspack as the bundler for building.+});options
The second parameter of
createBuilderis a options object, you can pass in the following options:+};Description:
cwd: The root path of the current build, the default value isprocess.cwd().entry: Build entry object.
-target: Build target type, the default value is['web'], see chapter Build Target for details.
+target: Build target type, the default value is['web'], see chapter Build Target for details.framework: The name of the framework, a unique identifier, the default value is'modern.js'.configPath: The path to the framework config file (absolute path), this parameter affects the build cache update.
- Type
-+- Example
const mergedConfig = mergeBuilderConfig(config1, config2); -console.log(mergedConfig); // { dev: { https: true } }
@@ -97,7 +97,7 @@This method does not modify the original config object.
webpack<
- Example
- Type
- Type
- Type
- Type
- Type
- Type
- Type
- Type
- Type
- Example
- Example
urls: URLs to access dev server.
@@ -170,12 +170,12 @@ - Example
urls: URLs to access server.
@@ -262,18 +262,18 @@ - Type
- Example
- Example
- Type
- Example
- Type
- Example
- Type @@ -354,20 +354,20 @@
- Example
- Example
- Example
-
@@ -437,15 +437,15 @@
callback: (params: { bundlerConfigs?: WebpackConfig[] | RspackConfig[]; }) => Promise<void> | void, -): void; +): void;
- Example
+});builder.onAfterBuild
- +;
onAfterBuildis a callback function that is triggered after running the production build. You can access the build result information via the `stats' parameter:-
@@ -460,50 +460,50 @@
+): void;
- Example
+});builder.onBeforeStartDevServer
- +;
Called before starting the development server.
- Type
+- Example
+});builder.onAfterStartDevServer
- +;
Called after starting the development server, you can get the port number through the
portparameter.- Type
+): void;- Example
+});builder.onDevCompileDone
- +;
Called after each development environment build, you can use
isFirstCompileto determine whether it is the first build.- Type
+): void;- Example
} else { console.log('re-compile!'); } -}); +});
builder.onExit
- +;
Called when the process is going to exit, this hook can only execute synchronous code.
- Type
+- Example
+});builder.getBuilderConfig
- +;
Get the Builder config, this method must be called after the
modifyBuilderConfighook is executed.- Type
+- Example
+});builder.getNormalizedConfig
- +;
Get the normalized Builder config, this method must be called after the
modifyBuilderConfighook is executed.Compared with the
api.getBuilderConfigmethod, the config returned by this method has been normalized, and the type definition of the config will be narrowed. For example, theundefinedtype ofconfig.htmlwill be removed.It is recommended to use this method to get the Builder config.
- Type
+- Example
+});builder.getHTMLPaths
- +;
Get path information for all HTML assets.
This method will return an object, the key is the entry name and the value is the relative path of the HTML file in the dist directory.
- Type
+- Example
\ No newline at end of file +});ON THIS PAGE\ No newline at end of file diff --git a/modern-js/builder/en/api/builder-types.html b/modern-js/builder/en/api/builder-types.html index f1ca5f811b..dc5e371460 100644 --- a/modern-js/builder/en/api/builder-types.html +++ b/modern-js/builder/en/api/builder-types.html @@ -1,4 +1,4 @@ -ON THIS PAGEBuilder Types - Modern.js Builder +Builder Types - Modern.js Builder -Modern.js Builder Builder Types
+Modern.js Builder Builder Types
This section describes some of the type definitions provided by the Builder.
BuilderInstance
The type of the Builder instance.
+let builder: BuilderInstance;You can pass in the Provider type through generics to make the type definition of the Builder instance more accurate:
+let builder: BuilderInstance<BuilderWebpackProvider>;BuilderContext
The type of the context property in the Builder instance.
+const context: BuilderContext = builder.context;BuilderPlugin
The type of Builder plugin, should be used with the
BuilderPluginAPItype exported from the provider.+};BuilderTarget
The type of build target.
-+BuilderEntry
The type of the
-entryoption to thecreateBuildermethod.+CreateBuilderOptions
The param type of
-createBuildermethod.\ No newline at end of file +ON THIS PAGE\ No newline at end of file diff --git a/modern-js/builder/en/api/config-dev.html b/modern-js/builder/en/api/config-dev.html index 5d432bf799..6b518cd9e1 100644 --- a/modern-js/builder/en/api/config-dev.html +++ b/modern-js/builder/en/api/config-dev.html @@ -1,4 +1,4 @@ -ON THIS PAGEDev Config - Modern.js Builder +Dev Config - Modern.js Builder -Modern.js Builder +};+};Dev Config
+Modern.js Builder +};Dev Config
This section describes some dev configurations in Modern.js Builder.
dev.assetPrefix
- +;
- Type:
boolean | string - Default:
'/'
@@ -25,9 +25,9 @@
Boolean T dev: { assetPrefix: true, }, -};
The script URL will be:
-+If
assetPrefixis set tofalseor not set,/is used as the default value.String type
When the value of
@@ -35,23 +35,29 @@assetPrefixisstringtype, the string will be used as the URL prefix:String typ dev: { assetPrefix: 'http://example.com/assets/', }, -};
The script URL will be:
-+Differences from Native Configuration
dev.assetPrefixcorresponds to the following native configurations:-
-
- output.publicPath configuration in webpack. -
- output.publicPath configuration in Rspack. +
- output.publicPath configuration in webpack. +
- output.publicPath configuration in Rspack.
The differences from the native configuration are as follows:
-
-
dev.assetPrefixonly takes effect in the development environment.
-dev.assetPrefixautomatically appends a trailing/by default.
-- The value of
dev.assetPrefixis written to theprocess.env.ASSET_PREFIXenvironment variable.
+ -
+
+dev.assetPrefixonly takes effect in the development environment.
+ -
+
+dev.assetPrefixautomatically appends a trailing/by default.
+ -
+
The value of
+dev.assetPrefixis written to theprocess.env.ASSET_PREFIXenvironment variable.
dev.beforeStartUrl
- +;
- Type:
() => Promise<void> | void - Default:
undefined
@@ -64,9 +70,9 @@
await doSomeThing(); }, }, -};
dev.hmr
- +;
- Type:
boolean - Default:
true
@@ -77,9 +83,9 @@ - Type:
string - Default:
0.0.0.0
@@ -91,9 +97,9 @@ - Type:
boolean | { key: string; cert: string } - Default:
false
@@ -101,13 +107,13 @@ - Type:
number - Default:
8080
@@ -152,9 +158,9 @@ - Type:
- Default:
true - Type:
boolean | string | string[] | undefined - Default:
undefined
@@ -198,14 +204,14 @@ - Type:
- Default:
false - Bundler:
only support webpack
@@ -31,7 +31,7 @@ - Type:
boolean | PluginSourceBuildOptions - Default:
false
@@ -83,10 +83,10 @@ - Type:
string - Default:
undefined
@@ -24,7 +24,7 @@ - Type:
boolean | 'anonymous' | 'use-credentials' - Default:
false - If
trueis passed, it will automatically be set tocrossorigin="anonymous". - If
falseis passed, it will not set thecrossoriginattr. anonymous: Request uses CORS headers and credentials flag is set to 'same-origin'. There is no exchange of user credentials via cookies, client-side SSL certificates or HTTP authentication, unless destination is the same origin.
-use-credentials: Request uses CORS headers, credentials flag is set to 'include' and user credentials are always included.
+-
+
+anonymous: Request uses CORS headers and credentials flag is set to 'same-origin'. There is no exchange of user credentials via cookies, client-side SSL certificates or HTTP authentication, unless destination is the same origin.
+ -
+
+use-credentials: Request uses CORS headers, credentials flag is set to 'include' and user credentials are always included. - Type:
boolean - Default:
false - Type:
string - Default:
undefined
@@ -101,13 +105,13 @@ - a relative path relative to the project root directory.
- Type:
Record<string, string> - Default:
undefined
@@ -135,7 +139,7 @@ - The favicon for page
foois./src/assets/foo.png.
- - The favicon for other pages is
./src/assets/default.png.
+ -
+
The favicon for page
+foois./src/assets/foo.png.
+ -
+
The favicon for other pages is
+./src/assets/default.png. - Type:
'head' | 'body' | 'true' | false - Default:
'head'
@@ -175,14 +183,14 @@ - Type:
Record<string, boolean | string> - Default:
undefined
@@ -204,7 +212,7 @@ - The script tag of the page
foowill be injected inside thebodytag.
- - The script tag of other pages will be injected inside the
headtag.
+ -
+
The script tag of the page
+foowill be injected inside thebodytag.
+ -
+
The script tag of other pages will be injected inside the
+headtag. - Type:
Record<string, false | string | Record<string, string | boolean>> - Default:
undefined
@@ -234,9 +246,9 @@ - Type:
Record<string, Meta> - Default:
undefined
@@ -272,7 +284,7 @@ - Type:
string - Default:
'root'
@@ -298,29 +310,29 @@ - Type:
'defer' | 'blocking' | 'module' - Default:
'defer'
@@ -331,7 +343,7 @@ - Type:
ArrayOrNot<HtmlInjectTag | HtmlInjectTagHandler> - Default:
undefined
@@ -381,7 +393,7 @@ - Injecting static assets with determined paths on CDN. @@ -506,7 +518,7 @@
- Type:
Record<string, ArrayOrNot<HtmlInjectTag | HtmlInjectTagHandler>> - Default:
undefined
@@ -553,7 +565,7 @@ - Type:
string - Default:
- Type:
Object - Default:
undefined
@@ -589,7 +601,7 @@ - Type:
Object | Function - Default: @@ -620,8 +632,8 @@
- Type:
Object - Default:
undefined
@@ -676,7 +688,7 @@ - Type:
string - Default:
undefined
@@ -700,9 +712,9 @@ - Type:
Record<string, string> - Default:
undefined
@@ -710,7 +722,7 @@ - The title of the page
fooisTikTok.
diff --git a/modern-js/builder/en/api/config-output.html b/modern-js/builder/en/api/config-output.html
index 9f5fb1ced6..ef18398e09 100644
--- a/modern-js/builder/en/api/config-output.html
+++ b/modern-js/builder/en/api/config-output.html
@@ -1,4 +1,4 @@
- - Type:
string - Default:
'/'
@@ -25,26 +25,32 @@ - output.publicPath configuration in webpack. -
- output.publicPath configuration in Rspack. +
- output.publicPath configuration in webpack. +
- output.publicPath configuration in Rspack.
output.assetPrefixonly takes effect in the production environment.
-output.assetPrefixautomatically appends a trailing/by default.
-- The value of
output.assetPrefixis written to theprocess.env.ASSET_PREFIXenvironment variable.
+ -
+
+output.assetPrefixonly takes effect in the production environment.
+ -
+
+output.assetPrefixautomatically appends a trailing/by default.
+ -
+
The value of
+output.assetPrefixis written to theprocess.env.ASSET_PREFIXenvironment variable. - Type:
Object - Type:
number
@@ -127,7 +133,7 @@ - Type:
string | ((url: string) => boolean) | undefined
@@ -140,7 +146,7 @@ - Type:
undefined | boolean | 'anonymous' | 'use-credentials'
@@ -154,7 +160,7 @@ - Type:
undefined | (options: AssetsRetryHookContext) => void
@@ -170,7 +176,7 @@ - Type:
undefined | (options: AssetsRetryHookContext) => void
@@ -186,7 +192,7 @@ - Type:
undefined | (options: AssetsRetryHookContext) => void
@@ -202,7 +208,7 @@ - Type:
boolean
@@ -216,7 +222,7 @@ - Type:
'ascii' | 'utf8' - Default:
'ascii'
@@ -277,10 +283,10 @@ - Type:
boolean - Default:
true
@@ -291,9 +297,9 @@ - Type:
boolean | object - Default:
false
@@ -309,7 +315,7 @@ - rootValue (Default is the same as rootFontSize)
- unitPrecision: 5
- propList: ['*']
- Type:
CopyPluginOptions | CopyPluginOptions['patterns'] - Default:
undefined
@@ -426,10 +432,10 @@ - Type:
- Default:
undefined: According to the output.disableCssModuleExtension configuration option to determine which style files to enable CSS modules.
+undefined: According to the output.disableCssModuleExtension configuration option to determine which style files to enable CSS modules.true: enable CSS modules for all files matching/\.module\.\w+$/i.test(filename)regexp.false: disables CSS Modules.RegExp: enable CSS modules for all files matching/RegExp/i.test(filename)regexp.
@@ -477,7 +483,7 @@ - Type:
string - Default: @@ -512,7 +518,7 @@
- Type:
- Default:
dev.hmr dev: { hmr: false, }, -}; +};
dev.host
- +;
dev.host dev: { host: 'localhost', }, -}; +};
dev.https
- +;
dev.htt
After configuring this option, you can enable HTTPS Dev Server, and disabling the HTTP Dev Server.
HTTP:
+ > Network: http://192.168.0.1:8080/HTTPS:
+ > Network: https://192.168.0.1:8080/Automatically generate certificates
-You can directly set
-httpstotrue, Builder will automatically generate the HTTPS certificate based on devcert.When using this method, you need to manually install the devcert dependency in your project:
+You can directly set
+httpstotrue, Builder will automatically generate the HTTPS certificate based on devcert.When using this method, you need to manually install the devcert dependency in your project:
+pnpm add devcert@1.2.2 -DThen configure
dev.httpstotrue:+};The devcert has some limitations, it does not currently support IP addresses yet.
TIPThe https proxy automatically installs the certificate and needs root authority, please enter the password according to the prompt.The password is only used to trust the certificate, and will not be leaked or be used elsewhere.
Manually set the certificate
You can also manually pass in the certificate and the private key required in the
-dev.httpsoption. This parameter will be directly passed to the createServer method of the https module in Node.js.For details, please refer to https.createServer.
+For details, please refer to https.createServer.
+};dev.port
- +;
Example dev: { port: 3000, }, -}; +};
dev.progressBar
- +;
d | boolean | { id?: string; - }; + };
d dev: { progressBar: false, }, -}; +};
If you need to modify the text displayed on the left side of the progress bar, you can set the
idoption:+};dev.startUrl
- +;
dev. // Open multiple pages startUrl: ['http://localhost:8080', 'http://localhost:8080/about'], }, -}; +};
Port placeholder
Since the port number may change, you can use the
<port>placeholder to refer to the current port number, and Builder will automatically replace the placeholder with the actual listening port number.+};Open the specified browser
On MacOS, you can open the specified browser when Dev Server starts, by set environment variable
BROWSER, support values:-
diff --git a/modern-js/builder/en/api/config-experiments.html b/modern-js/builder/en/api/config-experiments.html
index 038645cd5d..f135b45e1f 100644
--- a/modern-js/builder/en/api/config-experiments.html
+++ b/modern-js/builder/en/api/config-experiments.html
@@ -1,4 +1,4 @@
-
Experiments Config - Modern.js Builder +Experiments Config - Modern.js Builder -Modern.js Builder +};Experiments Config
+Modern.js Builder + };Experiments Config
This section describes some experimental configs in the Builder, which can enable unstable features in Builder.
-If you meet issues with experimental features, please disable the config first and report through GitHub Issues.
+If you meet issues with experimental features, please disable the config first and report through GitHub Issues.
experiments.lazyCompilation
- +;
entries?: boolean; // Whether to enable lazy compilation for dynamic imports imports?: boolean; - };
Used to enable the lazy compilation (i.e. compile on demand). When this config is enabled, Builder will compile entrypoints and dynamic imports only when they are used. It will improve the compilation startup time of the project.
Lazy compilation only takes effect in the development.
Lazy Compilation for Dynamic Imports
-Lazy compile async modules introduced by dynamic import:
+Lazy compile async modules introduced by dynamic import:
+};When
importsoption is enabled, all async modules will only be compiled when requested. If your project is a single-page application, and routing is split through dynamic import, there will be a significant effect of speeding up compilation.Lazy Compilation for Entires
In addition to lazy compilation for async modules, you can also choose to lazily compile both entries and async modules at the same time.
@@ -50,13 +50,13 @@entries: true, }, }, -};
The above config can also be simplified to:
+};When
entriesoption is enabled, all pages will not be compiled when the compilation is started, and the page will be compiled only when you visit it.When using lazy compilation for entries, there are some considerations:
-
@@ -70,9 +70,9 @@
Use proxyLazy Compilation relies on the local development server of webpack. When you proxy a domain name to localhost, Lazy Compilation will not work properly. Therefore, if you need to develop with proxy, please disable Lazy Compilation.
Other Potential Issues
Considering that Lazy Compilation is still an experimental feature of webpack, you may encounter some potential issues while using it, such as changes in the behavior of compiled artifacts or compilation errors.
-When you encounter these issues, you can refer to webpack Issues to find solutions or disable the
+lazyCompilationconfiguration option.When you encounter these issues, you can refer to webpack Issues to find solutions or disable the
lazyCompilationconfiguration option.experiments.sourceBuild
- +;
experiments: { sourceBuild: true, }, -}; -
More detail can see "Source Code Build Mode"。
+}; +More detail can see "Source Code Build Mode"。
Options
-
+experiments.sourceBuildis implemented based on Rsbuild's Source Build plugin. You can pass plugin options like this:experiments.sourceBuildis implemented based on Rsbuild's Source Build plugin. You can pass plugin options like this:\ No newline at end of file +};ON THIS PAGE\ No newline at end of file diff --git a/modern-js/builder/en/api/config-html.html b/modern-js/builder/en/api/config-html.html index 5fd557f5e4..13c23ae344 100644 --- a/modern-js/builder/en/api/config-html.html +++ b/modern-js/builder/en/api/config-html.html @@ -1,4 +1,4 @@ -ON THIS PAGEHtml Config - Modern.js Builder +Html Config - Modern.js Builder -Modern.js Builder Html Config
+Modern.js Builder +};Html Config
This section describes some HTML configurations in Modern.js Builder.
html.appIcon
- +;
Example html: { appIcon: './src/assets/icon.png', }, -};
Set to an absolute path:
+};After recompiling, the following tags are automatically generated in the HTML:
-+html.crossorigin
- +;
Set the crossorigin attribute of the
+<script>and<style>tags.Set the crossorigin attribute of the
<script>and<style>tags.Example
+Example
+};After compilation, the
-<script>tag in HTML becomes:+The
-<style>tag becomes:+Optional Values
crossorigincan the set to the following values:-
-
html.disableHtmlFolder
- +;
Remove the folder of the HTML files. When this option is enabled, the generated HTML file path will change from
-[name]/index.htmlto[name].html.Example
+Example
By default, the structure of HTML files in the
distdirectory is:+ └── index.htmlEnable the
html.disableHtmlFolderconfig:+};After recompiling, the directory structure of the HTML files in dist is:
+ └── main.htmlIf you want to set the path of the HTML files, use the
output.distPath.htmlconfig.html.favicon
- +;
html
After config this option, the favicon will be automatically copied to the dist directory during the compilation, and the corresponding
-linktag will be added to the HTML.Example
+Example
Set as a relative path:
+};Set to an absolute path:
+};Set to a URL:
+};After recompiling, the following tags are automatically generated in the HTML:
-+html.faviconByEntries
- +;
Set different favicon for different pages.
The usage is same as
favicon, and you can use the "entry name" as the key to set each page individually.
-faviconByEntrieswill overrides the value set infavicon.Example
+Example
+};After recompiling, you will see:
-
-
html.inject
- +;
De <body> <div id="root"></div> </body> -</html> +</html>
Inject into body
Add the following config to inject script into the body tag:
+};You will see that the script tag is generated at the end of the body tag:
+</html>html.injectByEntries
- +;
Set different script tag inject positions for different pages.
The usage is same as
inject, and you can use the "entry name" as the key to set each page individually.
-injectByEntrieswill overrides the value set ininject.Example
+Example
+};After recompiling, you will see:
-
-
html.meta
- +;
String Typ description: 'a description of the page', }, }, -}; +};
The generated
-metatag in HTML is:+Object Type
When the
valueof ametaobject is an object, thekey: valueof the object is mapped to the attribute of themetatag.In this case, the
@@ -250,9 +262,9 @@nameandcontentproperties will not be set by default.Object Typ }, }, }, -}; +};
The
-metatag in HTML is:+Remove Default Value
Setting the
valueof themetaobject tofalseand the meta tag will not be generated.For example to remove the
@@ -262,9 +274,9 @@imagemode:R imagemode: false, }, }, -}; +};
html.metaByEntries
- +;
Set different meta tags for different pages.
The usage is same as
meta, and you can use the "entry name" as the key to set each page individually.
-metaByEntrieswill overrides the value set inmeta.Example
+Example
+};After compiling, you can see that the meta of the page
-foois:+The meta of other pages is:
-+html.mountId
- +;
html
By default, the
rootelement is included in the HTML template for component mounting, and the element id can be modified throughmountId.-Example
+</body> +Example
Set the
idtoapp:+};After compilation:
+</body>Notes
Update Relevant Code
After modifying
mountId, if there is logic in your code to obtain therootroot node, please update the corresponding value:+ReactDOM.createRoot(domNode).render(<App />);Custom Templates
If you customized the HTML template, please make sure that the template contains
<div id="<%= mountId %>"></div>, otherwise themountIdconfig will not take effect.html.scriptLoading
- +;
defer +<body></body>
TIPWhen the browser encounters a
<script>tag with the defer attribute, it will download the script file asynchronously without blocking the parsing and rendering of the page. After the page is parsed and rendered, the browser executes the<script>tags in the order they appear in the document.blocking
@@ -341,25 +353,25 @@blocking inject: 'body', scriptLoading: 'blocking', }, -}; +};
When you need to set
blocking, it is recommended to sethtml.injectto'body'to avoid page rendering being blocked.+</body>module
When
scriptLoadingis set tomodule, the script can support ESModule syntax, and the browser will automatically delay the execution of these scripts by default, which is similar todefer.+};+<body></body>html.tags
- +;
Tag Object * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head#see_also} */ head?: boolean; -} +}
A tag object can be used to describe the tag to be injected and the location of the injection can be controlled by the parameters.
+};It will add a
scripttag to the end of theheadof the HTML:+</html>The final insertion position of the tag is determined by the
headandappendoptions, and two elements with the same configuration will be inserted into the same area and hold their relative positions to each other.Fields in the tag that indicate the path to the external assets are affected by the
@@ -426,7 +438,7 @@publicPathandhashoptions. These fields includesrcfor thescripttag andhreffor thelinktag.Tags Handler< export type HtmlInjectTagHandler = ( tags: HtmlInjectTag[], utils: HtmlInjectTagUtils, -) => HtmlInjectTag[] | void; +) => HtmlInjectTag[] | void;
html.tagscan also accept functions that can arbitrarily modify tags by writing logic to the callback, often used to ensure the relative position of tags while inserting them.The callback function accepts a tag list as an argument and needs to modify or return a new tag array directly.
+};The function will be executed at the end of the HTML processing flow. In the example below, the 'tags' parameter will contain all tag objects that form config, regardless of the function's location in config.
Modifying the attributes
append,publicPath,hashin the callback will not take effect, because they have been applied to the tag's location and path attributes, respectively.So the end product will look like:
@@ -472,15 +484,15 @@Tags Handler< <!-- tags with `{ head: false, append: true }` here. --> <script src="//example.com/a.js"></script> </body> -</html> +</html>
Limitation
-This configuration is used to modify the content of HTML files after Builder completes building, and does not resolve or parse new modules. It cannot be used to import uncompiled source code files. Also cannot replace configurations such as source.preEntry.
+This configuration is used to modify the content of HTML files after Builder completes building, and does not resolve or parse new modules. It cannot be used to import uncompiled source code files. Also cannot replace configurations such as source.preEntry.
For example, for the following project:
+└── modern.config.ts+};modern.config.tsThe tag object here will be directly added to the HTML product after simple processing, but the
polyfill.tswill not be transpiled or bundled, so there will be a 404 error when processing this script in the application.+</body>Reasonable use cases include:
Limitation│ └── index.tsx ├── public │ └── service-worker.js -└── modern.config.ts +└── modern.config.ts
+};modern.config.tsThe result will seems like:
+</body>html.tagsByEntries
- +;
Used for multiple entry applications, injecting different tags for each entry.
The usage is the same as
tags, and you can use the "entry name" as the key to set each page individually.
-tagsByEntrieswill override the value set intags.Example
+Example
+};Compile the application and you can see a tag injected on the
-foopage:+And for any other pages:
-+html.template
- +;
Define the path to the HTML template, corresponding to the
-templateconfig of html-webpack-plugin.Example
+Define the path to the HTML template, corresponding to the
+templateconfig of html-webpack-plugin.Example
Replace the default template with a custom HTML template file, you can add the following config:
+};html.templateByEntries
- +;
Set different template file for different pages.
The usage is same as
template, and you can use the "entry name" as the key to set each page individually.
-templateByEntrieswill overrides the value set intemplate.Example
+Example
+};html.templateParameters
- +;
files: object; options: object; }; -}; -
Define the parameters in the HTML template, corresponding to the
+}; +templateParametersconfig of html-webpack-plugin. You can use the config as an object or a function.Define the parameters in the HTML template, corresponding to the
templateParametersconfig of html-webpack-plugin. You can use the config as an object or a function.If it is an object, it will be merged with the default parameters. For example:
+};If it is a function, the default parameters will be passed in, and you can return an object to override the default parameters. For example:
-Example
+}; +Example
To use the
fooparameter in the HTML template, you can add the following config:+};Or you can use a function to dynamically generate the parameters:
+};Then you can use the
fooparameter in the HTML template by<%= foo %>:+</script>The compiled HTML is:
-+html.templateParametersByEntries
- +;
Set different template parameters for different pages.
The usage is same as
templateParameters, and you can use the "entry name" as the key to set each page individually.
-templateParametersByEntrieswill overrides the value set intemplateParameters.Example
+Example
+};html.title
- +;
html.t html: { title: 'example', }, -}; +};
html.titleByEntries
- +;
Set different title for different pages.
The usage is same as
title, and you can use the "entry name" as the key to set each page individually.
-titleByEntrieswill overrides the value set intitle.Example
+Example
+};After recompiling, you can see:
Output Config - Modern.js Builder +Output Config - Modern.js Builder -Modern.js Builder +};Output Config
+Modern.js Builder +};Output Config
This section describes some output related configurations in Modern.js Builder.
output.assetPrefix
- +;
Example output: { assetPrefix: 'https://cdn.example.com/assets/', }, -};
After building, you can see that the JS files are loaded from:
+></script>Differences from Native Configuration
output.assetPrefixcorresponds to the following native configurations:-
-
The differences from the native configuration are as follows:
-
-
output.assetsRetry
- +;
onRetry?: (options: AssetsRetryHookContext) => void; onSuccess?: (options: AssetsRetryHookContext) => void; onFail?: (options: AssetsRetryHookContext) => void; -};
Since the ability will inject some extra runtime code into HTML, we have disabled this ability by default. If you need to enable it, you can configure it in the form of an object, for example:
+};When you enable this ability, the default config of
assetsRetryis as follows:+};At the same time, you can also customize your retry logic using the following configurations.
assetsRetry.domain
-
@@ -98,7 +104,7 @@
asse domain: ['https://cdn1.com', 'https://cdn2.com', 'https://cdn3.com'], }, }, -}; +};
After adding the above configuration, when assets fail to load from the
cdn1.comdomain, the request domain will automatically fallback tocdn2.com.If the assets request for
cdn2.comalso fails, the request will fallback tocdn3.com.assetsRetry.type
@@ -114,7 +120,7 @@assets type: ['script', 'link'], }, }, -}; +};
assetsRetry.max
assetsR max: 5, }, }, -}; +};
assetsRetry.test
assets test: /cdn\.example\.com/, }, }, -}; +};
assetsRetry.crossOrigin
crossOrigin: true, }, }, -}; +};
assetsRetry.onRetry
ass }, }, }, -}; +};
assetsRetry.onSuccess
a }, }, }, -}; +};
assetsRetry.onFail
asse }, }, }, -}; +};
assetsRetry.inlineScript
inlineScript: false, }, }, -}; +};
After adding the above configuration, the runtime code of
assetsRetrywill be extracted into a separateassets-retry.[version].jsfile and output to the dist directory.The downside is that
assets-retry.[version].jsitself may fail to load. If this happens, the assets retry will not work. Therefore, we prefer to inline the runtime code into the HTML file.Notes
@@ -241,7 +247,7 @@Notes }, }, }, -}; +};
Limitation
assetsRetrymay not work in the following scenarios:Micro-frontend application
@@ -251,7 +257,7 @@D
Currently,
assetsRetrycannot work on dynamically imported resources. This feature is being supported.Resources in custom templates
-assetsRetrylistens to the page error event to know whether the current resource fails to load and needs to be retried. Therefore, if the resource in the custom template is executed earlier thanassetsRetry, thenassetsRetrycannot listen to the event that the resource fails to load, so it cannot retry.If you want
+assetsRetryto work on resources in custom templates, you can refer to Custom Insertion Example to modify html.inject configuration and custom template.If you want
assetsRetryto work on resources in custom templates, you can refer to Custom Insertion Example to modify html.inject configuration and custom template.+</html>output.charset
- +;
ou output: { charset: 'utf8', }, -}; +};
Builder will automatically add
<meta charset="utf-8">to the generated HTML files ifoutput.charsetisutf8.output.cleanDistPath
- +;
output: { cleanDistPath: false, }, -}; +};
output.convertToRem
- +;
Boolean T output: { convertToRem: true, }, -}; +};
At this point, the rem configuration defaults as follows:
+}Object Type
When the value of
output.convertToRemisobjecttype, The Builder will perform Rem processing based on the current configuration.options:
@@ -397,12 +403,12 @@Object Typ
pxtorem objectrootValue (Default is the same as rootFontSize) unitPrecision: 5 propList: ['*'] -postcss-pxtorem options +postcss-pxtorem options Example
+Example
+};output.copy
- +;
outpu output: { copy: [{ from: './src/assets', to: '' }], }, -}; -
For more detailed configuration, please refer to: copy-webpack-plugin.
+}; +For more detailed configuration, please refer to: copy-webpack-plugin.
output.cssModules
- +;
type CssModules = { auto?: boolean | RegExp | ((resourcePath: string) => boolean); exportLocalsConvention?: CssModuleLocalsConvention; -}; +};
+};Setup css modules configuration.
cssModules.auto
The
@@ -463,7 +469,7 @@autoconfiguration option allows CSS modules to be automatically enabled based on their filenames.cssModu
Type description:
-
-
cssModu }, }, }, -}; +};
cssModules.exportLocalsConvention
Style of exported class names.
-
@@ -502,9 +508,9 @@
exportLocalsConvention: 'camelCaseOnly', }, }, -}; +};
output.cssModuleLocalIdentName
- +;
+ : '[path][name]__[local]-[hash:base64:6]';
Sets the format of the className generated by CSS Modules after compilation.
Default Value
@@ -521,7 +527,7 @@cssModuleLocalIdentNamehas different default values in development and production.Default // In development, the value is `.src-index-module__header--xxxxx` // In production, the value is `.xxxxx` -console.log(styles.header); +console.log(styles.header);
Template String
You can use the following template strings in
cssModuleLocalIdentName:-
@@ -536,15 +542,15 @@
Templa
-TIPWhen using Rspack as the bundler, currently does not support custom
<hashDigest>.Example
+Example
Set
cssModuleLocalIdentNameto other value:+};output.dataUriLimit
- +;
font?: number; image?: number; media?: number; -}; +};
font: 10000, image: 10000, media: 10000, -}; +};
Set the size threshold to inline static assets such as images and fonts.
By default, static assets will be Base64 encoded and inline into the page if the size is less than 10KB.
You can adjust the threshold by setting the
@@ -573,7 +579,7 @@dataUriLimitconfig.image: The threshold of non-SVG images. media: The threshold of media assets such as videos.
Example
+Example
Set the threshold of images to 5000 Bytes, and set media assets not to be inlined:
+};output.disableCssExtract
- +;
- Type:
boolean - Default:
false
Whether to disable CSS extract and inline CSS files into JS files.
By default, Builder will extract CSS into a separate
-.cssfile and output it to the dist directory. When this option is set totrue, CSS files will be inlined into JS files and inserted on the page at runtime via<style>tags.Example
+Example
+};output.disableCssModuleExtension
- +;
- Type:
boolean - Default:
false
@@ -608,12 +614,12 @@ - Type:
- Default:
- Type:
boolean - Default:
false
@@ -714,10 +720,10 @@ - Type:
- Default:
- Type:
boolean - Default:
false
@@ -774,9 +780,9 @@ - Type:
boolean - Default:
false
@@ -788,58 +794,58 @@ - In development build, type errors will not block the compilation process.
- In production build, type errors will cause the build to fail to ensure the stability of the production code.
- Type:
boolean - Default:
false - Type:
boolean - Default:
false - Type:
boolean - Default:
false - web artifact:
asset-manifest.json
- - node artifact:
asset-manifest-node.json
+ -
+
web artifact:
+asset-manifest.json
+ -
+
node artifact:
+asset-manifest-node.json - Type:
boolean - Default:
false - Type:
boolean - Default:
false - Type:
boolean - Default:
false - Type:
- Default:
false - Type:
- Default:
false name: The filename, such asstatic/css/main.18a568e5.css.
@@ -1063,9 +1073,9 @@ -
Type:
@@ -1075,8 +1085,8 @@string | object | function | RegExp - Type:
- Default:
image: The name of a non-SVG image.media: The name of a media asset, such as a video.
.sass,.scssand.lessfiles are also affected bydisableCssModuleExtension.-TIPWe do not recommend enabling this config, because after enabling
disableCssModuleExtension, CSS Modules files and ordinary CSS files cannot be clearly distinguished, which is not conducive to long-term maintenance.Example
+Example
+};Detailed
The following is a detailed explanation of the CSS Modules rules:
disableCssModuleExtension is false (default)
@@ -640,7 +646,7 @@TIPFor CSS Modules files inside node_modules, please always use the
*.module.csssuffix.output.distPath
- +;
o media?: string; server?: string; worker?: string; -}; +};
o media: 'static/media', server: 'bundles', worker: 'worker', -}; +};
Set the directory of the dist files. Builder will output files to the corresponding subdirectory according to the file type.
Detail:
-
@@ -691,7 +697,7 @@
o
Root Directory
The
rootis the root directory of the build artifacts and can be specified as a relative or absolute path. If the value ofrootis a relative path, it will be appended to the project's root directory to form an absolute path.Other directories can only be specified as relative paths and will be output relative to the
-rootdirectory.Example
+Example
The JavaScript files will be output to the
distPath.root+distPath.jsdirectory, which isdist/static/js.If you need to output JavaScript files to the
build/resource/jsdirectory, you can add following config:+};output.disableMinimize
- +;
output: { disableMinimize: true, }, -}; +};
TIPThis configuration is usually used for debugging and troubleshooting. It is not recommended to disable code minification in production environments, as it will significantly degrade the page performance.
output.disableSourceMap
- +;
| { js?: boolean; css?: boolean; - }; + };
+};Whether to disable Source Map generation.
What is a Source MapSource Map is an information file that saves the source code mapping relationship. It records each location of the compiled code and the corresponding pre-compilation location. With Source Map, you can directly view the source code when debugging the compiled code.
By default, Builder's Source Map generation rules are:
@@ -746,13 +752,13 @@output: { disableSourceMap: true, }, -}; +};
If you want to enable Source Map in development and disable it in the production, you can set to:
+};If you need to individually control the Source Map of JS files or CSS files, you can refer to the following settings:
+};output.disableSvgr
- +;
output: { disableSvgr: true, }, -}; +};
output.disableTsChecker
- +;
B
Example
+Example
Disable TypeScript type checker:
+};Disable type checker in development:
+};Disable type checker in production:
+};TIPIt is not recommended to disable type checker in production, which will reduce the stability of the production code, please use it with caution.
output.disableFilenameHash
- +;
Remove the hash from the name of static files after production build.
After the production build, there will be a hash in the middle of the filename by default. You can disable this behavior through the
-output.disableFilenameHashconfig.Example
+Example
By default, the filename is:
+dist/static/js/main.18a568e5.js 2.24 KB 922 BAdd
output.disableFilenameHashconfig:+};After rebuild, the filenames become:
+dist/static/js/main.js 2.24 KB 922 Boutput.disableInlineRuntimeChunk
- +;
Used to control whether to inline the bundler's runtime code into HTML.
What is runtimeChunkBuilder will generate a
-builder-runtime.jsfile in the dist directory, which is the runtime code of webpack or Rspack.runtimeChunk is a piece of runtime code, which is provided by webpack or Rspack, that contains the necessary module processing logic, such as module loading, module parsing, etc. See Runtime for details.
+runtimeChunk is a piece of runtime code, which is provided by webpack or Rspack, that contains the necessary module processing logic, such as module loading, module parsing, etc. See Runtime for details.
In the production environment, Builder will inline the runtimeChunk file into the HTML file by default instead of writing it to the dist directory. This is done to reduce the number of file requests.
Disable Inlining
@@ -848,7 +854,7 @@Disab output: { disableInlineRuntimeChunk: true, }, -}; +};
Merge Into Page Chunk
If you don't want to generate a separate runtimeChunk file, but want the runtimeChunk code to be bundled into the page chunk, you can set the config like this:
+};output.enableAssetManifest
- +;
Whether to generate a manifest file that contains information of all assets.
-Example
+Example
Enable asset manifest:
+};After compiler, there will be a
dist/manifest.jsonfile:+}If the current project has multiple types of build artifacts, such as including SSR build artifacts, multiple manifest.json files will be generated.
-
-
output.enableAssetFallback
- +;
If this option is enabled, all unrecognized files will be emitted to the dist directory; otherwise, an exception will be thrown.
-Example
+Example
Enable the config:
+};Import a module of unknown type in code:
-+After compilation,
foo.xxxwill be output to thedist/static/mediadirectory.You can control the output path and filename after fallback through the
output.distPath.mediaandoutput.filename.mediaconfigs.TIPEnabling this config will change the rules structure in the webpack config. In most cases, we do not recommend using this config.
output.enableLatestDecorators
- +;
Whether to use the new decorator proposal.
-By default, Builder uses the legacy decorator proposal when compiling decorators.
-When
+output.enableLatestDecoratorsis set totrue, the Builder will compile with the new decorator proposal (version 2018-09).By default, Builder uses the legacy decorator proposal when compiling decorators.
+When
output.enableLatestDecoratorsis set totrue, the Builder will compile with the new decorator proposal (version 2018-09).+};output.enableCssModuleTSDeclaration
- +;
Whether to generate a TypeScript declaration file for CSS modules.
-Example
+Example
Enable CSS module TypeScript declaration:
+};After building, there will be a
.d.tsfile for each CSS module file. For example+export default cssExports;output.enableInlineScripts
- +;
+ | ((params: { size: number; name: string }) => boolean);Whether to inline output scripts files (.js files) into HTML with
<script>tags in production mode.Note that, with this option on, the scripts files will no longer be written in dist directory, they will only exist inside the HTML file instead.
-TIPWhen using convention-based routing, you need to set output.splitRouteChunks to false if this option is turned on. +
-TIPWhen using convention-based routing, you need to set output.splitRouteChunks to false if this option is turned on.
Example
+Example
By default, we have following output files:
+dist/static/js/main.jsAfter turn on the
output.enableInlineScriptsoption:+};The output files will become:
+dist/static/css/style.cssAnd
dist/static/js/main.jswill be inlined inindex.html:+</html>Using RegExp
If you need to inline part of the JS files, you can set
enableInlineScriptsto a regular expression that matches the URL of the JS file that needs to be inlined.For example, to inline
@@ -984,7 +994,7 @@main.jsinto HTML, you can add the following configuration:Using Reg output: { enableInlineScripts: /\/main\.\w+\.js$/, }, -}; +};
TIPThe production filename includes a hash value by default, such as
static/js/main.18a568e5.js. Therefore, in regular expressions,\w+is used to match the hash.Using Function
@@ -1000,37 +1010,37 @@Using F return size < 10 * 1000; }, }, -}; +};
output.enableInlineStyles
- +;
+ | ((params: { size: number; name: string }) => boolean);Whether to inline output style files (.css files) into HTML with
<style>tags in production mode.Note that, with this option on, the style files will no longer be written in dist directory, they will only exist inside the HTML file instead.
-TIPWhen using convention-based routing, you need to set output.splitRouteChunks to false if this option is turned on. +
-TIPWhen using convention-based routing, you need to set output.splitRouteChunks to false if this option is turned on.
Example
+Example
By default, we have following output files:
+dist/static/js/main.jsAfter turn on the
output.enableInlineStylesoption:+};The output files will become:
+dist/static/js/main.jsAnd
dist/static/css/style.csswill be inlined inindex.html:-Using RegExp
+</html> +Using RegExp
If you need to inline part of the CSS files, you can set
enableInlineStylesto a regular expression that matches the URL of the CSS file that needs to be inlined.For example, to inline
main.cssinto HTML, you can add the following configuration:+};-TIPThe production filename includes a hash value by default, such as
static/css/main.18a568e5.css. Therefore, in regular expressions,\w+is used to match the hash.Using Function
+Using Function
You can also set
output.enableInlineStylesto a function that accepts the following parameters:Using F return size < 10 * 1000; }, }, -}; +};
output.externals
- +;
At build time, prevent some
-importdependencies from being packed into bundles in your code, and instead fetch them externally at runtime.For more information, please see: webpack Externals
-Example
+For more information, please see: webpack Externals
+Example
Exclude the
react-domdependency from the build product. To get this module at runtime, the value ofreact-domwill globally retrieve theReactDOMvariable.+};TIPWhen the build target is Web Worker, externals will not take effect. This is because the Worker environment can not access global variables.
output.filename
- +;
o font?: string; image?: string; media?: string; -}; +};
o font: '[name].[contenthash:8][ext]', image: '[name].[contenthash:8][ext]', media: '[name].[contenthash:8][ext]', -}; +};
Sets the filename of dist files.
After the production build, there will be a hash in the middle of the filename by default. This behavior can be disabled through the
output.disableFilenameHashconfig.The following are the details of each filename:
@@ -1132,7 +1142,7 @@o
Example
+Example
To set the name of the JavaScript file to
[name]_script.js, use the following configuration:+};Filename hashUsually, we only set the filename hash in the production mode (i.e., when
-process.env.NODE_ENV === 'production').If you set the filename hash in the development mode, it may cause HMR to fail (especially for CSS files). This is because every time the file content changes, the hash value changes, preventing tools like mini-css-extract-plugin from reading the latest file content. +
If you set the filename hash in the development mode, it may cause HMR to fail (especially for CSS files). This is because every time the file content changes, the hash value changes, preventing tools like mini-css-extract-plugin from reading the latest file content.
Filename of Async Modules
When you import a module via dynamic import, the module will be bundled into a single file, and its default naming rules are as follows:
@@ -1153,14 +1163,14 @@In the development environment, the filename will be generated based on the module path, such as
dist/static/js/async/src_add_ts.js. - In the production environment, it will be a random numeric id, such as
dist/static/js/async/798.27e3083e.js. This is to avoid leaking the source code path in the production environment, and the number of characters is also less. - Type:
'linked' | 'inline' | 'none' - Default:
'linked'
@@ -1173,27 +1183,27 @@ none: Remove all legal comments.- Type:
string[] | Record<BuilderTarget, string[] - Default:
undefined - Type:
'entry' | 'usage' | 'ua' | 'off' - Default:
'entry'
@@ -1240,11 +1250,11 @@ - Type:
'url' | 'component' - Default:
'url'
@@ -1253,12 +1263,12 @@ - Type:
- Default:
- Bundler:
only support webpack - Type:
Object | undefined - Add the environment variable
BUNDLE_ANALYZE=true, for example: - Configure
performance.bundleAnalyzeto enable it permanently: - Enabling the server mode will cause the
buildprocess to not exit normally.
- - Enabling
bundleAnalyzerwill reduce build speed. Therefore, this configuration should not be enabled during daily development, and it is recommended to enable it on demand through theBUNDLE_ANALYZEenvironment variable.
- - Since no code minification and other optimizations are performed in the
devphase, the real output size cannot be reflected, so it is recommended to analyze the output size in thebuildphase.
+ -
+
Enabling the server mode will cause the
+buildprocess to not exit normally.
+ -
+
Enabling
+bundleAnalyzerwill reduce build speed. Therefore, this configuration should not be enabled during daily development, and it is recommended to enable it on demand through theBUNDLE_ANALYZEenvironment variable.
+ -
+
Since no code minification and other optimizations are performed in the
+devphase, the real output size cannot be reflected, so it is recommended to analyze the output size in thebuildphase. - Type:
Object - Default:
{ strategy: 'split-by-experience' }
@@ -169,7 +175,7 @@ - Type:
number
@@ -234,7 +240,7 @@ - Type:
RegExp[] | Record<string, RegExp>
@@ -251,7 +257,7 @@ -
Type:
@@ -304,37 +310,37 @@undefined | string[]Default:
undefined - Type:
undefined | Array<string | PreconnectOption> - Default:
undefined - Type:
undefined | true | PrefetchOption - Default:
undefined all-chunks: prefetch all resources (on the current page), including all asynchronous and non-asynchronous resources.all-assets: prefetch all resources, and resources of other pages will be included in the MPA scenario.- Type:
undefined | true | PreloadOption - Default:
undefined all-assets: preload all resources, and resources of other pages will be included in the MPA scenario.- Type:
boolean - Default:
true
@@ -434,30 +440,30 @@ - Type:
boolean - Default:
false - Type:
boolean | ConsoleType[] - Default:
false
@@ -469,62 +475,62 @@ - Type:
boolean - Default:
false - Type:
boolean - Default:
true - Bundler:
only support webpack - Type:
- Default:
undefined - Bundler:
only support webpack - Type:
- Default:
false - Type:
string[] - Default:
The browserslist configuration of the current project - Example: @@ -116,7 +116,7 @@
- Type:
Record<string, string | string[]> | Function - Default:
undefined - Type:
'prefer-tsconfig' | 'prefer-alias' - Default:
'prefer-tsconfig'
@@ -108,7 +108,7 @@ source.alias:@commonwill use the value defined in tsconfig paths, pointing to./src/common-1
@@ -131,7 +131,7 @@ - tsconfig paths: @@ -143,7 +143,7 @@
source.alias:- Type: RuleSetCondition[] +
- Type: RuleSetCondition[]
- Default:
- Type:
Array<string | RegExp> - Default:
[] - Type:
Record<string, unknown> - Default:
{}
@@ -290,8 +290,8 @@ - If the value is an object all keys are defined the same way.
- If you prefix typeof to the key, it's only defined for typeof calls.
- Type:
Record<string, JSONValue> | Function - Default: @@ -322,13 +322,13 @@
- Type: @@ -351,7 +351,7 @@
- Type:
Array<string | Regexp> | Function - Default:
undefined - Bundler:
only support webpack - Type:
- Default:
- Type:
boolean
@@ -519,10 +519,10 @@ - Type:
string
@@ -530,10 +530,10 @@ - Type:
boolean
@@ -541,12 +541,12 @@ - Type:
boolean
@@ -554,12 +554,12 @@ - Type:
((member: string) => string | undefined) | string
@@ -572,7 +572,7 @@ - Type:
((member: string) => string | undefined) | string
@@ -585,9 +585,9 @@ - Type:
string | string[] - Default:
undefined
@@ -595,13 +595,13 @@ - Type:
string | Record<BuilderTarget, string> - Default:
undefined - Type:
- Default:
undefined - Type:
Object | Function - Default: @@ -21,8 +21,8 @@
- Type:
Object | Function - Default:
undefined - Rspack scenario: When using Rspack as the bundler, using the
tools.babeloption will significantly slow down the Rspack's build speed. This is because Rspack defaults to using SWC for compilation, and configuring Babel will cause the code to be compiled twice, resulting in additional compilation overhead. - webpack + SWC scenario: When using webpack as the bundler, if you use Builder's SWC plugin for code compilation, the
tools.babeloption will not take effect. - Type:
(presets: BabelPlugin[]) => void
@@ -130,7 +130,7 @@ - Type:
(plugins: string | string[]) => void
@@ -142,7 +142,7 @@ - Type:
(presets: string | string[]) => void
@@ -154,12 +154,12 @@ - Type:
(options: PresetEnvOptions) => void - Type:
(options: PresetReactOptions) => void - Type:
Function | undefined - Default:
undefined
@@ -207,286 +207,14 @@ - Type:
'development' | 'production' | 'test'
- - Type:
boolean
- - Type:
'web' | 'node' | 'modern-web' | 'web-worker'
- - Type:
boolean
- - Type:
boolean
- - Type:
typeof import('html-webpack-plugin') | import('@rspack/plugin-html')
- - Type:
Object | Function - Default: @@ -502,12 +230,12 @@
- Bundler:
only support webpack - Type:
Object | Function - Default:
undefined - Type:
Object - Default:
{} - Type:
Array
@@ -635,7 +363,7 @@ - Type: @@ -649,7 +377,7 @@
- Default:
- Type:
- Default:
- Type:
Record<string, string>
@@ -705,7 +433,7 @@ - Type:
boolean | ConnectHistoryApiFallbackOptions
@@ -718,14 +446,14 @@ - Type:
boolean - Default:
true - Type:
boolean | { key: string; cert: string }
@@ -742,7 +470,7 @@ - Type:
boolean
@@ -766,7 +494,7 @@ - Default:
undefined - sockWrite. Allow send some message to hmr client, and then the hmr client will take different actions depending on the message type. If you send a "content changed" message, the page will reload. @@ -806,7 +534,7 @@
- Type:
Record<string, string> | Record<string, ProxyDetail>
@@ -821,8 +549,8 @@ - bypass: bypass the proxy based on the return value of a function.
@@ -884,7 +612,7 @@
proxy }, }, }, -}; +};
+};watch
- Type:
boolean
@@ -905,7 +633,7 @@ - Type:
false | Object | Function - Default: @@ -930,9 +658,9 @@
- The first parameter is the default config, which can be modified directly. @@ -956,14 +684,14 @@
- Type:
Object | Function - Default: @@ -989,9 +717,9 @@
- Type:
(excludes: RegExp | RegExp[]) => void - Type:
Object | Function | undefined - Default: @@ -1051,11 +779,11 @@
- Type:
Object | Function - Default: @@ -1101,9 +829,9 @@
- Type:
(plugins: PostCSSPlugin | PostCSSPlugin[]) => void - Type:
true | Object | Function | undefined - Default:
false - Type:
Object | Function - Default: @@ -1208,9 +936,9 @@
- Type:
(excludes: RegExp | RegExp[]) => void - Type:
Object | Function - Default:
{} - Type:
Object | Function - Default: @@ -1296,8 +1024,8 @@
- Type:
Object | Function | undefined - Default: @@ -1332,12 +1060,12 @@
- Bundler:
only support webpack - Type:
Object | Function | undefined - Default:
undefined - Bundler:
only support webpack - Type:
Object | Function - Default: @@ -1432,9 +1160,9 @@
- Type:
Object | Function | undefined - Default:
undefined - Bundler:
only support webpack - Type:
boolean
@@ -1524,7 +1252,7 @@ - Type:
'web' | 'node' | 'modern-web' | 'web-worker'
@@ -1539,7 +1267,7 @@ - Type:
boolean
@@ -1554,7 +1282,7 @@ - Type:
boolean
@@ -1569,7 +1297,7 @@ - Type:
typeof import('webpack')
@@ -1582,7 +1310,7 @@ - Type:
typeof import('html-webpack-plugin')
@@ -1594,12 +1322,12 @@ - Type:
(rules: RuleSetRule | RuleSetRule[]) => void - Type:
(plugins: WebpackPluginInstance | WebpackPluginInstance[]) => void
@@ -1643,7 +1371,7 @@ - Type:
(plugins: WebpackPluginInstance | WebpackPluginInstance[]) => void
@@ -1663,25 +1391,25 @@ - Type:
(name: string) => void - Type:
(...configs: WebpackConfig[]) => WebpackConfig - Type:
(name: string) => string - Type:
Function | undefined - Default:
undefined
@@ -1708,8 +1436,8 @@ - Type:
'development' | 'production' | 'test' - Type:
boolean - Type:
'web' | 'node' | 'modern-web' | 'web-worker'
watchWhether to watch files change in directories such as
mock/,server/,api/.tools.htmlPlugin
- +;
minifyCSS: true, minifyURLs: true, }, -}; -
The configs of html-webpack-plugin or @rspack/plugin-html can be modified through
-tools.htmlPlugin.Object Type
+}; +The configs of html-webpack-plugin or @rspack/plugin-html can be modified through
+tools.htmlPlugin.Object Type
When
tools.htmlPluginisObjecttype, the value will be merged with the default config viaObject.assign.-Function Type
+}; +Function Type
When
tools.htmlPluginis a Function:Function } }, }, -}; +};
Boolean Type
The built-in
html-webpack-pluginplugins can be disabled by settools.htmlPlugintofalse.+};Disable JS/CSS minify
By default, Builder will compresses JavaScript/CSS code inside HTML during the production build to improve the page performance. This ability is often helpful when using custom templates or inserting custom scripts.
However, when
@@ -976,9 +704,9 @@output.enableInlineScriptsoroutput.enableInlineStylesis turned on, inline JavaScript/CSS code will be repeatedly compressed, which will have a certain impact on build performance. You can modify the default minify behavior by modifying thetools.htmlPlugin.minifyconfiguration.D } }, }, -}; +};
tools.less
- +;
tools. }, // CSS Source Map enabled by default in development environment sourceMap: isDev, -}; -
You can modify the config of less-loader via
-tools.less.Object Type
+}; +You can modify the config of less-loader via
+tools.less.Object Type
When
tools.lessis configured asObjecttype, it is merged with the default config through Object.assign in a shallow way. It should be noted thatlessOptionsis merged through deepMerge in a deep way. For example:-Function Type
+}; +Function Type
When
tools.lessis a Function, the default config is passed as the first parameter, which can be directly modified or returned as the final result. The second parameter provides some utility functions that can be called directly. For example:+};Modifying Less Version
In some scenarios, if you need to use a specific version of Less instead of the built-in Less v4 in Builder, you can install the desired Less version in your project and set it up using the
implementationoption of theless-loader.+};Util Function
-addExcludes
+addExcludes
addExcludes addExcludes(/node_modules/); }, }, -}; +};
tools.minifyCss
- +;
t }, ], }, -}; -
When building for production, Builder will minimize the CSS code through css-minimizer-webpack-plugin. The config of css-minimizer-webpack-plugin can be modified via
-tools.minifyCss.Object Type
+}; +When building for production, Builder will minimize the CSS code through css-minimizer-webpack-plugin. The config of css-minimizer-webpack-plugin can be modified via
+tools.minifyCss.Object Type
When
-tools.minifyCssisObjecttype, it will be merged with the default config viaObject.assign.For example, modify the
+presetconfig of cssnano:For example, modify the
presetconfig of cssnano:-Function Type
+}; +Function Type
When
tools.minifyCssisFunctiontype, the default config is passed in as the first parameter, the config object can be modified directly, or a value can be returned as the final result.+};tools.postcss
- +;
too // CSS Source Map enabled by default in development environment sourceMap: isDev, }, -}; -
Builder integrates PostCSS by default, you can configure postcss-loader through
-tools.postcss.Function Type
+}; +Builder integrates PostCSS by default, you can configure postcss-loader through
+tools.postcss.Function Type
When the value is a Function, the internal default config is passed as the first parameter, and the config object can be modified directly without returning, or an object can be returned as the final result; the second parameter is a set of tool functions for modifying the postcss-loader config.
For example, you need to add a PostCSS plugin on the basis of the original plugin, and push a new plugin to the postcssOptions.plugins array:
+};When you need to pass parameters to the PostCSS plugin, you can pass them in by function parameters:
+};tools.postcsscan return a config object and completely replace the default config:-Object Type
+}; +Object Type
When this value is an Object, it is merged with the default config via
Object.assign. Note thatObject.assignis a shallow copy and will completely overwrite the built-inpresetsorpluginsarray, please use it with caution.-Util Functions
-addPlugins
+}; +Util Functions
+addPlugins
addPlugins addPlugins([require('postcss-preset-env'), require('postcss-import')]); }, }, -}; +};
TIPBuilder uses the PostCSS v8 version. When you use third-party PostCSS plugins, please pay attention to whether the PostCSS version is compatible. Some legacy plugins may not work in PostCSS v8.
tools.pug
- +;
Configure the Pug template engine.
-Boolean Type
+Configure the Pug template engine.
+Boolean Type
Pug template engine is not enabled by default, you can enable it by setting
tools.pugtotrue.+};When enabled, you can use
-index.pugas the template file inhtml.templateconfig.Object Type
+Object Type
When
tools.terserisObjecttype, you can passing the Pug options:-For detailed options, please refer to Pug API Reference.
-Function Type
+}; +For detailed options, please refer to Pug API Reference.
+Function Type
When
tools.pugisFunctiontype, the default configuration is passed in as the first parameter, the configuration object can be modified directly, or a value can be returned as the final result.+};tools.sass
- +;
tools.
-You can modify the config of sass-loader via
-tools.sass.Object Type
+}; +You can modify the config of sass-loader via
+tools.sass.Object Type
When
tools.sassisObjecttype, it is merged with the default config through Object.assign. It should be noted thatsassOptionsis merged through deepMerge in a deep way.For example:
-Function Type
+}; +Function Type
When
tools.sassis a Function, the default config is passed as the first parameter, which can be directly modified or returned as the final result. The second parameter provides some utility functions that can be called directly. For Example:+};Modifying Sass Version
In some scenarios, if you need to use a specific version of Sass instead of the built-in Dart Sass v1 in Builder, you can install the desired Sass version in your project and set it up using the
implementationoption of thesass-loader.+};Utility Function
-addExcludes
+addExcludes
addExcludes addExcludes(/node_modules/); }, }, -}; +};
tools.styleLoader
- +;
The config of style-loader can be set through
+tools.styleLoader.The config of style-loader can be set through
tools.styleLoader.It is worth noting that Builder does not enable
-style-loaderby default. You can useoutput.disableCssExtractconfig to enable it.Object Type
+Object Type
When this value is an Object, it is merged with the default config via Object.assign. For example:
-Function Type
+}; +Function Type
When the value is a Function, the default config is passed in as the first parameter. You can modify the config object directly, or return an object as the final config. For example:
+};tools.styledComponents
- +;
// `pure` is enabled in production to reduce bundle size pure: isProd, transpileTemplateLiterals: true, -} -
+} +tools.styledComponentsconfig is corresponding to babel-plugin-styled-components, or @swc/plugin-styled-components when using SWC plugin.tools.styledComponentsconfig is corresponding to babel-plugin-styled-components, or @swc/plugin-styled-components when using SWC plugin.When the value is an Object, use the Object.assign function to merge with the default config. For example:
+};When the config is a Function, the first parameter is the default configuration, and the second parameter provides some utility functions that can be called directly:
+};The feature is enabled by default, and you can configure
tools.styledComponentstofalseto disable this behavior, which can improve build performance:+};tools.terser
- +;
tool safari10: true, }, }, -}; +};
When building for production, Builder will minimize the JavaScript code through terser-webpack-plugin. The config of terser-webpack-plugin can be modified via
-tools.terser.Object Type
+When building for production, Builder will minimize the JavaScript code through terser-webpack-plugin. The config of terser-webpack-plugin can be modified via
+tools.terser.Object Type
When
tools.terserisObjecttype, it will be merged with the default config viaObject.assign.For example, to exclude some files from minification:
-Function Type
+}; +Function Type
When
tools.terserisFunctiontype, the default config is passed in as the first parameter, the config object can be modified directly, or a value can be returned as the final result.-+Disable code minificationIf you need to disable code minification, you can use the output.disableMinimize configuration. +};
Disable code minificationIf you need to disable code minification, you can use the output.disableMinimize configuration.
tools.tsLoader
- +;
Alternatives for ts-loaderUsing babel-loader or Rspack instead of ts-loader can significantly improve compilation speed and provide better extendability.
-ts-loader cannot be used with certain features such as source.transformImport and tools.styledComponents provided by Babel & SWC. +
Alternatives for ts-loaderUsing babel-loader or Rspack instead of ts-loader can significantly improve compilation speed and provide better extendability.
+ts-loader cannot be used with certain features such as source.transformImport and tools.styledComponents provided by Babel & SWC.
-ts-loaderis not enabled by default in the project. Whentools.tsLoaderis not undefined, builder will use ts-loader instead of babel-loader to compile TypeScript code.Object Type
+Object Type
When this value is an Object, it is merged with the default configuration via Object.assign.
The default configuration is as follows:
+}You can override the default configuration via the
tools.tsLoaderconfiguration option:-Function Type
+}; +Function Type
When this value is a Function, the default configuration is passed in as the first parameter, the configuration object can be modified directly, or an object can be returned as the final configuration.The second parameter is the util functions to modify the
ts-loaderconfiguration. For example:-Util Functions
-addIncludes
-Deprecated, please use source.include instead, both have the same functionality.
-addExcludes
-Deprecated, please use source.exclude instead, both have the same functionality.
+}; +Util Functions
+addIncludes
+Deprecated, please use source.include instead, both have the same functionality.
+addExcludes
+Deprecated, please use source.exclude instead, both have the same functionality.
tools.tsChecker
- +;
t console.error(message.replace(/ERROR/g, 'Type Error')); }, }, -}, -
By default, the fork-ts-checker-webpack-plugin is enabled for type checking. You can use
-output.disableTsCheckerconfig to disable it.Object Type
+}, +By default, the fork-ts-checker-webpack-plugin is enabled for type checking. You can use
+output.disableTsCheckerconfig to disable it.Object Type
When the value of
tsCheckeris of type Object, it will be deeply merged with the default configuration.-Function Type
+}; +Function Type
When the value of
tsCheckeris of type Function, the default configuration will be passed as the first argument. You can directly modify the configuration object or return an object as the final configuration.+};tools.webpack
- +;
+tools.webpackis used to configure webpack.tools.webpackis used to configure webpack.
-tools.bundlerChainis also used to modify the webpack configuration, and the function is more powerful. It is recommended to usetools.bundlerChainfirst.Object Type
-
+tools.webpackcan be configured as an object to be deep merged with the built-in webpack configuration through webpack-merge.Object Type
+tools.webpackcan be configured as an object to be deep merged with the built-in webpack configuration through webpack-merge.For example, add
resolve.aliasconfiguration:-Function Type
+}; +Function Type
tools.webpackcan be configured as a function. The first parameter of this function is the built-in webpack configuration object, you can modify this object, and then return it. For example:+};TIPThe object returned by the
tools.webpackfunction is used directly as the final webpack configuration and is not merged with the built-in webpack configuration.Utils
@@ -1509,7 +1237,7 @@env return config; }, }, -}; +};
isProd
isProd return config; }, }, -}; +};
target
target return config; }, }, -}; +};
isServer
isServer return config; }, }, -}; +};
isWebWorker
isWebWorker return config; }, }, -}; +};
webpack
webpack return config; }, }, -}; +};
HtmlWebpackPlugin
HtmlWebp console.log(HtmlWebpackPlugin); }, }, -}; +};
addRules
Add additional webpack rules.
+Add additional webpack rules.
For example:
+};prependPlugins
prependPlug prependPlugins([new PluginA(), new PluginB()]); }, }, -}; +};
appendPlugins
appendPlugin appendPlugins([new PluginA(), new PluginB()]); }, }, -}; +};
removePlugin
Remove the internal webpack plugin, the parameter is the
-constructor.nameof the plugin.For example, remove the internal fork-ts-checker-webpack-plugin:
+For example, remove the internal fork-ts-checker-webpack-plugin:
+};mergeConfig
Used to merge multiple webpack configs, same as webpack-merge.
+Used to merge multiple webpack configs, same as webpack-merge.
+};getCompiledPath
Get the path to the builder built-in dependencies, same as webpackChain#getCompiledPath.
+Get the path to the builder built-in dependencies, same as webpackChain#getCompiledPath.
tools.webpackChain
- +;
-tools.webpackChainis executed earlier than tools.webpack and thus will be overridden by changes intools.webpack.Utils
-env
+Utils
+env
env } }, }, -}; -
isProd
+}; +isProd
isProd } }, }, -}; -
target
+}; +target
target } }, }, -};
- Type:
watch是否监听
mock/、server/、api/等目录的文件变化。tools.htmlPlugin
- +;
minifyCSS: true, minifyURLs: true, }, -}; -
通过
-tools.htmlPlugin可以修改 html-webpack-plugin 或 @rspack/plugin-html 的配置项。Object 类型
+}; +通过
+tools.htmlPlugin可以修改 html-webpack-plugin 或 @rspack/plugin-html 的配置项。Object 类型
当
tools.htmlPlugin的值为Object类型时，会与默认配置通过Object.assign合并。-Function 类型
+}; +Function 类型
当
tools.htmlPlugin为 Function 类型时：Functi } }, }, -}; +};
Boolean 类型
将
tools.htmlPlugin配置为false，可以禁用默认的html-webpack-plugin插件。+};禁用 JS / CSS 压缩
默认情况下，Builder 会在生产环境构建时压缩 HTML 内的 JavaScript / CSS 代码，从而提升页面性能。此能力通常在使用自定义模版或插入自定义脚本时会有帮助。然而，当开启
output.enableInlineScripts或output.enableInlineStyles时，会出现对 inline JavaScript / CSS 代码重复压缩的情况，对构建性能会有一定影响。你可以通过修改tools.htmlPlugin.minify配置项来修改默认的压缩行为。+};tools.less
- +;
tools. }, // 默认在开发环境下启用 CSS 的 Source Map sourceMap: isDev, -}; -
你可以通过
-tools.less修改 less-loader 的配置。Object 类型
+}; +你可以通过
+tools.less修改 less-loader 的配置。Object 类型
当
tools.less的值为Object类型时，会与默认配置通过 Object.assign 进行浅层合并，值得注意的是，lessOptions会通过 deepMerge 进行深层合并。-Function 类型
+}; +Function 类型
当
tools.less为 Function 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果，第二个参数提供了一些可以直接调用的工具函数：+};修改 Less 版本
在某些场景下，如果你需要使用特定的 Less 版本，而不是使用 Builder 内置的 Less v4，可以在项目中安装需要使用的 Less 版本，并通过
less-loader的implementation选项设置。-工具函数
-addExcludes
+}; +工具函数
+addExcludes
addExcludes addExcludes(/node_modules/); }, }, -}; +};
tools.minifyCss
- +;
t }, ], }, -}; -
在生产环境构建时，Builder 会通过 css-minimizer-webpack-plugin 对 CSS 代码进行压缩优化。可以通过
-tools.minifyCss修改 css-minimizer-webpack-plugin 的配置。Object 类型
+}; +在生产环境构建时，Builder 会通过 css-minimizer-webpack-plugin 对 CSS 代码进行压缩优化。可以通过
+tools.minifyCss修改 css-minimizer-webpack-plugin 的配置。Object 类型
当
-tools.minifyCss的值为Object类型时，会与默认配置通过Object.assign合并。例如下面修改 cssnano 的
+preset配置：例如下面修改 cssnano 的
preset配置：-Function 类型
+}; +Function 类型
当
tools.minifyCss配置为Function类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果。+};tools.postcss
- +;
too // 默认在开发环境下启用 CSS 的 Source Map sourceMap: isDev, }, -}; -
Builder 默认集成 PostCSS，你可以通过
-tools.postcss对 postcss-loader 进行配置。Function 类型
+}; +Builder 默认集成 PostCSS，你可以通过
+tools.postcss对 postcss-loader 进行配置。Function 类型
值为 Function 类型时，内部默认配置作为第一参数传入，可以直接修改配置对象不做返回，也可以返回一个对象作为最终结果；第二个参数为修改 postcss-loader 配置的工具函数集合。
例如，需要在原有插件的基础上新增一个 PostCSS 插件，在 postcssOptions.plugins 数组中 push 一个新的插件即可：
+};需要给 PostCSS 插件传递参数时，可以通过函数参数的形式进行传入：
+};tools.postcss可以返回一个配置对象，并完全替换默认配置：-Object 类型
+}; +Object 类型
当此值为 Object 类型时，与默认配置通过
Object.assign合并。注意Object.assign是浅拷贝，会完全覆盖内置的plugins数组，请谨慎使用。-工具函数
-addPlugins
+}; +工具函数
+addPlugins
addPlugins addPlugins([require('postcss-preset-env'), require('postcss-import')]); }, }, -}; +};
TIPBuilder 中使用的 PostCSS 版本为 v8，当你引入社区中的 PostCSS 插件时，请注意版本是否适配，部分旧版本插件可能无法在 PostCSS v8 下运行。
tools.pug
- +;
配置 Pug 模板引擎。
-Boolean 类型
+配置 Pug 模板引擎。
+Boolean 类型
Builder 默认不启用 Pug 模板引擎，你可以将
tools.pug设置为true来启用它。+};启用后，你可以在
-html.template中指定使用index.pug作为模板文件。Object 类型
+Object 类型
当
tools.terser的值为Object类型时，可以配置 Pug 模板引擎的选项：-详细参数请查看 Pug API Reference。
-Function 类型
+}; +详细参数请查看 Pug API Reference。
+Function 类型
当
tools.pug配置为Function类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果。+};tools.sass
- +;
tools.
-你可以通过
-tools.sass修改 sass-loader 的配置。Object 类型
+}; +你可以通过
+tools.sass修改 sass-loader 的配置。Object 类型
当
tools.sass的值为Object类型时，会与默认配置通过 Object.assign 进行浅层合并，值得注意的是，sassOptions会通过 deepMerge 进行深层合并。-Function 类型
+}; +Function 类型
当
tools.sass为 Function 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果，第二个参数提供了一些可以直接调用的工具函数：+};修改 Sass 版本
在某些场景下，如果你需要使用特定的 Sass 版本，而不是使用 Builder 内置的 Dart Sass v1，可以在项目中安装需要使用的 Sass 版本，并通过
sass-loader的implementation选项设置。-工具函数
-addExcludes
+}; +工具函数
+addExcludes
addExcludes addExcludes(/node_modules/); }, }, -}; +};
tools.styleLoader
- +;
通过
+tools.styleLoader可以设置 style-loader 的配置项。通过
tools.styleLoader可以设置 style-loader 的配置项。值得注意的是，Builder 默认不会开启
-style-loader，你可以通过output.disableCssExtract配置项来开启它。Object 类型
+Object 类型
当此值为 Object 类型时，与默认配置通过 Object.assign 合并。比如：
-Function 类型
+}; +Function 类型
当此值为 Function 类型时，默认配置作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终配置。比如：
+};tools.styledComponents
- +;
// 在生产环境构建时启用 `pure` 来优化包体积 pure: isProd, transpileTemplateLiterals: true, -} -
对应 babel-plugin-styled-components 或使用 SWC 时 @swc/plugin-styled-components 的配置。 值为
+} +Object类型时，利用 Object.assign 函数与默认配置合并。比如:对应 babel-plugin-styled-components 或使用 SWC 时 @swc/plugin-styled-components 的配置。 值为
Object类型时，利用 Object.assign 函数与默认配置合并。比如:+};值为
Function类型时，第一个参数为默认配置，第二个参数提供了一些可以直接调用的工具函数：+};该特性默认启用，你可以配置
tools.styledComponents为false来关闭该行为，关闭后可以提升编译性能：+};tools.terser
- +;
tool safari10: true, }, }, -}; +};
在生产环境构建时，Builder 会通过 terser-webpack-plugin 对 JavaScript 代码进行压缩优化。可以通过
-tools.terser修改 terser-webpack-plugin 的配置。Object 类型
+在生产环境构建时，Builder 会通过 terser-webpack-plugin 对 JavaScript 代码进行压缩优化。可以通过
+tools.terser修改 terser-webpack-plugin 的配置。Object 类型
当
tools.terser的值为Object类型时，会与默认配置通过Object.assign合并。例如通过
exclude排除部分文件的压缩：-Function 类型
+}; +Function 类型
当
tools.terser配置为Function类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果。-+禁用代码压缩如果你需要禁用代码压缩，可以使用 output.disableMinimize 配置项。 +};
禁用代码压缩如果你需要禁用代码压缩，可以使用 output.disableMinimize 配置项。
tools.tsLoader
- +;
不再推荐使用 ts-loader使用 babel-loader 或 Rspack 转译 TypeScript 代码的性能明显优于 ts-loader 且能够使用更多拓展能力。
-启用 ts-loader 时将无法使用 source.transformImport 和 tools.styledComponents 等由 Babel 和 SWC 提供支持的能力。 +
不再推荐使用 ts-loader使用 babel-loader 或 Rspack 转译 TypeScript 代码的性能明显优于 ts-loader 且能够使用更多拓展能力。
+启用 ts-loader 时将无法使用 source.transformImport 和 tools.styledComponents 等由 Babel 和 SWC 提供支持的能力。
项目中默认不开启 ts-loader，当
-tools.tsLoader不为 undefined 则表示开启 ts-loader，同时禁用 babel-loader 对 TypeScript 的编译。Object 类型
+Object 类型
当此值为 Object 类型时，与默认配置通过 Object.assign 合并。
默认配置如下:
+}你可以通过
tools.tsLoader配置项来覆盖默认配置:-Function 类型
+}; +Function 类型
当此值为 Function 类型时，默认配置作为第一参数传入，可以直接修改配置对象，也可以返回一个对象作为最终配置；第二个参数为修改
ts-loader配置工具函数集合：-工具函数
-addIncludes
-已废弃，请使用 source.include 代替，两者功能完全一致。
-addExcludes
-已废弃，请使用 source.exclude 代替，两者功能完全一致。
+}; +工具函数
+addIncludes
+已废弃，请使用 source.include 代替，两者功能完全一致。
+addExcludes
+已废弃，请使用 source.exclude 代替，两者功能完全一致。
tools.tsChecker
- +;
t console.error(message.replace(/ERROR/g, 'Type Error')); }, }, -}, -
默认情况下，Builder 会开启 fork-ts-checker-webpack-plugin 进行类型检查。你可以通过
-output.disableTsChecker配置项来关闭类型检查。Object 类型
+}, +默认情况下，Builder 会开启 fork-ts-checker-webpack-plugin 进行类型检查。你可以通过
+output.disableTsChecker配置项来关闭类型检查。Object 类型
当
tsChecker的值为 Object 类型时，会与默认配置进行深层合并。-Function 类型
+}; +Function 类型
当
tsChecker的值为 Function 类型时，默认配置会作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终配置。+};tools.webpack
- +;
+tools.webpack选项用于配置原生的 webpack。tools.webpack选项用于配置原生的 webpack。
-tools.bundlerChain同样可以修改 webpack 配置，并且功能更加强大，建议优先使用tools.bundlerChain。Object 类型
-
+tools.webpack可以配置为一个对象，这个对象将会和内置的 webpack 配置通过 webpack-merge 进行深层合并。Object 类型
+tools.webpack可以配置为一个对象，这个对象将会和内置的 webpack 配置通过 webpack-merge 进行深层合并。比如添加
resolve.alias配置：-Function 类型
+}; +Function 类型
tools.webpack也可以配置为一个函数，这个函数的第一个入参为内置的 webpack 配置对象，你可以对这个对象进行修改，然后返回一份新的配置。比如：+};TIPtools.webpack函数返回的对象会直接作为最终使用的 webpack 配置，不会再与内置的 webpack 配置进行合并。工具集合
@@ -1511,7 +1235,7 @@env return config; }, }, -}; +};
isProd
isProd return config; }, }, -}; +};
target
target return config; }, }, -}; +};
isServer
isServer return config; }, }, -}; +};
isWebWorker
isWebWorker return config; }, }, -}; +};
webpack
webpack return config; }, }, -}; +};
HtmlWebpackPlugin
HtmlWebp console.log(HtmlWebpackPlugin); }, }, -}; +};
addRules
添加额外的 webpack rules。
+添加额外的 webpack rules。
示例：
+};prependPlugins
prependPlug prependPlugins([new PluginA(), new PluginB()]); }, }, -}; +};
appendPlugins
appendPlugin appendPlugins([new PluginA(), new PluginB()]); }, }, -}; +};
removePlugin
删除内部的 webpack 插件，参数为该插件的
-constructor.name。例如，删除内部的 fork-ts-checker-webpack-plugin：
+例如，删除内部的 fork-ts-checker-webpack-plugin：
+};mergeConfig
用于合并多份 webpack 配置，等价于 webpack-merge。
+用于合并多份 webpack 配置，等价于 webpack-merge。
+};getCompiledPath
获取 builder 内置依赖的所在路径，等价于 webpackChain#getCompiledPath。
+获取 builder 内置依赖的所在路径，等价于 webpackChain#getCompiledPath。
tools.webpackChain
- +;
-tools.webpackChain的执行时机早于 tools.webpack，因此会被tools.webpack中的修改所覆盖。工具集合
-env
+工具集合
+env
env } }, }, -}; -
isProd
+}; +isProd
isProd } }, }, -}; -
target
+}; +target
target } }, }, -}; -
isServer
+}; +isServer
isServer } }, }, -}; -
isWebWorker
+}; +isWebWorker
isWebWorker } }, }, -}; -
webpack
+}; +webpack
webpack chain.plugin('my-progress').use(webpack.ProgressPlugin); }, }, -}; -
HtmlWebpackPlugin
+}; +HtmlWebpackPlugin
HtmlWebp console.log(HtmlWebpackPlugin); }, }, -}; -
getCompiledPath
+}; +getCompiledPath
getCompile // ... }, }, -}; +};
CHAIN_ID
Builder 中预先定义了一些常用的 Chain ID，你可以通过这些 ID 来定位到内置的 Rule 或 Plugin。
TIP请留意，下列的一部分 Rule 或 Plugin 并不是默认存在的，当你开启特定配置项、或是注册某些插件后，它们才会被包含在 webpack 配置中。
@@ -1872,15 +1596,15 @@CHAIN_ID.RULE
RULE.STYLUS处理 +stylus的规则处理 stylus的规则（依赖 Stylus 插件）- RULE.PUG处理 +pug的规则RULE.SVGRule for svg- RULE.VUE处理 +vue的规则RULE.PUG处理 pug的规则RULE.TOMLCHAIN_ID
使用示例
-使用示例可参考：WebpackChain 使用示例。
+使用示例可参考：WebpackChain 使用示例。
tools.rspack
- +;
-tools.rspack选项用于配置原生的 Rspack。Object 类型
-
+tools.rspack可以配置为一个对象，这个对象将会和内置的 Rspack 配置通过 webpack-merge 进行深层合并。
+tools.rspack选项用于配置原生的 Rspack。Object 类型
+tools.rspack可以配置为一个对象，这个对象将会和内置的 Rspack 配置通过 webpack-merge 进行深层合并。比如添加
resolve.alias配置：-Function 类型
+}; +Function 类型
tools.rspack也可以配置为一个函数，这个函数接收一个参数，即内置的 Rspack 配置对象，你可以对这个对象进行修改，然后返回一份新的配置。比如：+};-TIPtools.rspack函数返回的对象会直接作为最终使用的 Rspack 配置，不会再与内置的 Rspack 配置进行合并。工具集合
+工具集合
这个函数的第二个参数是一个对象，包含了一些工具函数和属性，详情如下：
-env
+env
env return config; }, }, -}; -
isProd
+}; +isProd
isProd return config; }, }, -}; -
target
+}; +target
target return config; }, }, -}; -
isServer
+}; +isServer
isServer return config; }, }, -}; -
isWebWorker
+}; +isWebWorker
isWebWorker return config; }, }, -}; +};
rspack
rspack return config; }, }, -}; -
addRules
+}; +addRules
添加额外的 Rspack rules。
+添加额外的 Rspack rules。
示例：
-prependPlugins
+}; +prependPlugins
prependPlug prependPlugins([new PluginA(), new PluginB()]); }, }, -}; -
appendPlugins
+}; +appendPlugins
appendPlugin appendPlugins([new PluginA(), new PluginB()]); }, }, -}; -
removePlugin
+}; +removePlugin
删除内部的 Rspack 插件，参数为该插件的
-constructor.name。例如，删除内部的 webpack-bundle-analyzer：
+例如，删除内部的 webpack-bundle-analyzer：
-mergeConfig
+}; +mergeConfig
用于合并多份 Rspack 配置，等价于 webpack-merge。
+用于合并多份 Rspack 配置，等价于 webpack-merge。
-getCompiledPath
+}; +getCompiledPath
getCompile // ... }, }, -};
\ No newline at end of file +};目录\ No newline at end of file diff --git a/modern-js/builder/api/index.html b/modern-js/builder/api/index.html index ba8077c15d..62966b0dd1 100644 --- a/modern-js/builder/api/index.html +++ b/modern-js/builder/api/index.html @@ -1,4 +1,4 @@ -目录API - Modern.js Builder +API - Modern.js Builder -Modern.js Builder \ No newline at end of file +API
配置
Node API
Modern.js Builder \ No newline at end of file diff --git a/modern-js/builder/api/plugin-core.html b/modern-js/builder/api/plugin-core.html index 34765e034a..2f115b8291 100644 --- a/modern-js/builder/api/plugin-core.html +++ b/modern-js/builder/api/plugin-core.html @@ -1,4 +1,4 @@ -API
配置
Node API
Plugin Core - Modern.js Builder +Plugin Core - Modern.js Builder -Modern.js Builder +};Plugin Core
+Modern.js Builder +};Plugin Core
本章节描述了 Builder 插件核心的类型定义和 API。
BuilderPlugin
插件对象的类型，插件对象包含以下属性：
@@ -25,7 +25,7 @@Bu post?: string[]; remove?: string[]; setup: (api: API) => Promise<void> | void; -};
你可以从
@modern-js/builder中导入该类型：+});前置插件
默认情况下，插件会按照添加顺序依次执行，通过
pre字段可以声明前置执行的插件。比如有下面两个插件：
@@ -50,7 +50,7 @@前置插 const builderPluginBar = { name: 'builder-plugin-bar', pre: ['builder-plugin-foo'], -};
Bar 插件在
pre字段中配置了 Foo 插件，因此 Foo 插件一定会在 Bar 插件之前执行。后置插件
同样的，通过
@@ -61,7 +61,7 @@post字段可以声明后置执行的插件。后置插 const builderPluginBar = { name: 'builder-plugin-bar', post: ['builder-plugin-foo'], -}; +};
Bar 插件在
post字段中配置了 Foo 插件，因此 Foo 插件一定会在 Bar 插件之后执行。移除插件
通过
@@ -72,11 +72,11 @@remove字段可以在一个插件中移除其他插件。移除插 const builderPluginBar = { name: 'builder-plugin-bar', remove: ['builder-plugin-foo'], -}; +};
比如同时注册上述的 Foo 和 Bar 插件，由于 Bar 插件声明 remove 了 Foo 插件，因此 Foo 插件不会生效。
BuilderPluginAPI
插件 API 对象的类型。插件 API 对象上挂载了提供给插件使用的上下文数据、工具函数和注册生命周期钩子的函数。
-关于生命周期钩子的完整介绍，请阅读 Plugin Hooks 章节。
+关于生命周期钩子的完整介绍，请阅读 Plugin Hooks 章节。
在使用 webpack-provider 或 rspack-provider 时，
BuilderPluginAPI的类型定义有一定不同，你可以根据插件的使用场景来引入对应的类型。适用于 webpack-provider 的插件
开发适用于 webpack-provider 的插件时，请从
@@ -91,7 +91,7 @@@modern-js/builder-webpack-provider中引入BuilderPluginAPI。config.devtool = false; }); }, -}); +});
适用于 rspack-provider 的插件
开发适用于 rspack-provider 的插件时，请从
@modern-js/builder-rspack-provider中引入BuilderPluginAPI。+});同时适用于 webpack-provider 和 rspack-provider 的插件
想要开发同时适用于 webpack-provider 和 rspack-provider 的插件时，请从
@modern-js/builder-shared中引入DefaultBuilderPlugin。需要注意的是，开发 webpack 和 Rspack 同时支持的插件，意味着不能使用任何带有 webpack 或 Rspack 标识的 api，如
-modifyWebpackConfig或modifyRspackConfig。可通过 modifyBundlerChain 修改同时适用于 webpack 和 Rspack 的配置。
+可通过 modifyBundlerChain 修改同时适用于 webpack 和 Rspack 的配置。
+});api.context
-api.context是一个只读对象，提供一些上下文信息。
+api.context的内容与builder.context完全一致，请参考 builder.context。api.context的内容与builder.context完全一致，请参考 builder.context。api.c setup(api) { console.log(api.context.distPath); }, -}); +});
api.getBuilderConfig
- +;
获取 Builder 配置，该方法必须在
modifyBuilderConfig钩子执行完成后才能被调用。+const config = api.getBuilderConfig(); console.log(config.html?.title); }, -}); +});
api.getNormalizedConfig
- +;
获取归一化后的 Builder 配置，该方法必须在
modifyBuilderConfig钩子执行完成后才能被调用。相较于
getBuilderConfig方法，该方法返回的配置经过了归一化处理，配置的类型定义会得到收敛，比如config.html的undefined类型将被移除。推荐优先使用该方法获取配置。
+const config = api.getNormalizedConfig(); console.log(config.html.title); }, -}); +});
api.isPluginExists
- +;
判断某个插件是否已经被注册。
+setup: api => { console.log(api.isPluginExists('builder-plugin-foo')); }, -}); +});
api.getHTMLPaths
- +;
获取所有 HTML 产物的路径信息。
该方法会返回一个对象，对象的 key 为 entry 名称，value 为 HTML 文件在产物目录下的相对路径。
+console.log(htmlPaths); // { main: 'html/main/index.html' }; }); }, -});
\ No newline at end of file +});目录\ No newline at end of file diff --git a/modern-js/builder/api/plugin-hooks.html b/modern-js/builder/api/plugin-hooks.html index 706d337626..a2c0a11170 100644 --- a/modern-js/builder/api/plugin-hooks.html +++ b/modern-js/builder/api/plugin-hooks.html @@ -1,4 +1,4 @@ -目录Plugin Hooks - Modern.js Builder +Plugin Hooks - Modern.js Builder -Modern.js Builder +): void;+});Plugin Hooks
+Modern.js Builder +): void;Plugin Hooks
本章节描述了 Builder 插件提供的生命周期钩子。
概览
通用钩子
@@ -51,7 +51,7 @@mo config: BuilderConfig, utils: ModifyWebpackChainUtils, ) => PromiseOrNot<BuilderConfig | void>, -): void;
mo }); }); }, -});
modifyBundlerChain
实验性什么是 BundlerChain- +;
Bundler chain 是 webpack chain 的子集，其中包含一部分 webpack chain API，你可以用它来同时修改 webpack 和 Rspack 的配置。
-通过 bundler chain 修改的配置，在 webpack 和 Rspack 构建时均可生效。需要注意的是，bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如，修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同)，或添加一个Rspack 兼容的 webpack 插件。
+通过 bundler chain 修改的配置，在 webpack 和 Rspack 构建时均可生效。需要注意的是，bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如，修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同)，或添加一个Rspack 兼容的 webpack 插件。
modifyBundlerChain用于调用 bundler chain 来修改 webpack / Rspack 的配置。你在使用 webpack-provider 或 rspack-provider 时都可以使用该 hook。-
@@ -96,7 +96,7 @@
chain: BundlerChain, utils: ModifyBundlerChainUtils, ) => Promise<void> | void, -): void;
chain.plugin('bundle-analyze').use(BundleAnalyzerPlugin); }); }, -}); +});
modifyWebpackChain
通过 webpack chain 来修改 webpack 配置。该方法仅在使用 webpack-provider 时调用。
-
@@ -135,7 +135,7 @@
mod chain: WebpackChain, utils: ModifyWebpackChainUtils, ) => Promise<void> | void, -): void; +): void;
mod } }); }, -}); +});
modifyWebpackConfig
修改最终的 webpack 配置对象，你可以直接修改传入的 config 对象，也可以返回一个新的对象来替换传入的对象。该方法仅在使用 webpack-provider 时调用。
该方法的调用时机晚于
@@ -179,7 +179,7 @@modifyWebpackChain钩子。mo config: WebpackConfig, utils: ModifyWebpackConfigUtils, ) => Promise<WebpackConfig | void> | WebpackConfig | void, -): void; +): void;
mo } }); }, -}); +});
modifyRspackConfig
修改最终的 Rspack 配置对象，你可以直接修改传入的 config 对象，也可以返回一个新的对象来替换传入的对象。该方法仅在使用 rspack-provider 时调用。
-
@@ -212,7 +212,7 @@
mod config: RspackConfig, utils: ModifyRspackConfigUtils, ) => Promise<RspackConfig | void> | RspackConfig | void, -): void; +): void;
mod } }); }, -}); +});
onBeforeCreateCompiler
- +;
onBeforeCreateCompiler是在创建底层 Compiler 实例前触发的回调函数，当你执行builder.startDevServer、builder.build或builder.createCompiler时，都会调用此钩子。你可以通过
bundlerConfigs参数获取到底层打包工具的最终配置数组：-
@@ -242,7 +242,7 @@
callback: (params: { bundlerConfigs: WebpackConfig[] | RspackConfig[]; }) => Promise<void> | void, -): void; +): void;
console.log('the bundler config is ', bundlerConfigs); }); }, -}); +});
onAfterCreateCompiler
- +;
onAfterCreateCompiler是在创建 Compiler 实例后、执行构建前触发的回调函数，当你执行builder.startDevServer、builder.build或builder.createCompiler时，都会调用此钩子。你可以通过
compiler参数获取到 Compiler 实例对象:-
@@ -270,7 +270,7 @@
+}) => Promise<void> | void;): void;console.log('the compiler is ', compiler); }); }, -}); +});
构建钩子
onBeforeBuild
- +;
onBeforeBuild是在执行生产环境构建前触发的回调函数，你可以通过bundlerConfigs参数获取到底层打包工具的最终配置数组：+new webpack.DefinePlugin();
@@ -106,7 +106,7 @@In most scenarios, it is recommended to import webpack from Builder instead of manually installing a "webpack" dependency, which can avoid multi-instance problems.
+In most scenarios, it is recommended to import HtmlWebpackPlugin from builder instead of manually installing a "html-webpack-plugin" dependency, which can avoid multi-instance problems.
\ No newline at end of file diff --git a/modern-js/builder/en/api/builder-instance.html b/modern-js/builder/en/api/builder-instance.html index 62aecda51f..f092064088 100644 --- a/modern-js/builder/en/api/builder-instance.html +++ b/modern-js/builder/en/api/builder-instance.html @@ -1,4 +1,4 @@ -ON THIS PAGEBuilder Instance - Modern.js Builder +Builder Instance - Modern.js Builder -Modern.js Builder +function Build(options?: BuildOptions): Promise<void>;Builder Instance
+Modern.js Builder +};+};Builder Instance
This section describes all the properties and methods on the Builder instance object.
builder.context
@@ -17,7 +17,7 @@builder.contextis a read-only object that provides some context infos.bu
+builder.context.target
Build target type, corresponding to the
targetoption ofcreateBuildermethod.-
@@ -27,49 +27,49 @@
b type Context = { target: BuilderTarget | BuilderTarget[]; -};
builder.context.rootPath
The root path of current build, corresponding to the
cwdoption ofcreateBuildermethod.+builder.context.srcPath
The absolute path to the src directory.
+builder.context.distPath
The absolute path of the output directory, corresponding to the
output.distPath.rootconfig inBuilderConfig.+builder.context.cachePath
The absolute path of the build cache files.
+builder.context.configPath
The absolute path to the framework config file, corresponding to the
configPathoption ofcreateBuildermethod.+builder.context.tsconfigPath
The absolute path of the tsconfig.json file, or
undefinedif the tsconfig.json file does not exist in current project.+builder.context.framework
The name of the framework, a unique identifier, the default value is
'modern.js'.+builder.context.devServer
Dev Server information, including the current Dev Server hostname and port number.
-
@@ -78,13 +78,13 @@
builder.context.bundlerType
The bundler type of current build.
+builder.build
Perform a production build.
-
@@ -97,21 +97,21 @@
bui compiler?: Compiler | MultiCompiler; }; -function Build(options?: BuildOptions): Promise<void>;
+Development environment build
If you need to perform a development build, you can set the
modeoption to'development'.+});Monitor file changes
If you need to watch file changes and re-build, you can set the
watchoption totrue.+});Custom Compiler
In some cases, you may want to use a custom compiler:
+});builder.startDevServer
Start the local Dev Server, based on the Modern.js Dev Server.
-
@@ -148,17 +148,17 @@
function StartDevServer( options?: StartDevServerOptions, -): Promise<StartServerResult>; +): Promise<StartServerResult>;
Start Dev Server:
-+After successfully starting Dev Server, you can see the following logs:
+ > Network: http://192.168.0.1:8080startDevServerreturns the following parameters:console.log(port); // 8080 // Close the dev server -await server.close(); +await server.close();
Disable Print URLs
Setting
printURLstofalseto disable the default URL output, so you can custom the logs.+});You can also directly configure
printURLsas a function to modify URLs, such as adding a subpath to each URL:+});Strict Port
When a port is occupied, Builder will automatically increment the port number until an available port is found.
Set
strictPorttotrueand Builder will throw an exception when the port is occupied.+});Custom Compiler
In some cases, you may want to use a custom compiler:
+});Get Port Silently
In some cases, the default startup port number is already occupied. In this situation, Builder will automatically increment the port number until it finds an available one. This process will output a prompt log. If you do not want this log, you can set
getPortSlientlytotrue.+});Custom Logger
By default, Builder uses
@modern-js/utils/loggerto output logs. You can customize the log output object through theloggerparameter.+});Then Builder will use the custom logger to output logs.
builder.serve
Start a server to preview the production build locally. This method should be executed after
@@ -245,12 +245,12 @@builder.build.bui server: Server; }; -function server(): Promise<StartServerResult>; +function server(): Promise<StartServerResult>;
Start the server：
-+servereturns the following parameters:bui console.log(port); // 8080 // Close the server -await server.close(); +await server.close();
builder.createCompiler
Create a Compiler object.
When the
targetoption ofcreateBuildercontains only one value, the return value isCompiler; whentargetcontains multiple values, the return value isMultiCompiler.++
@@ -288,7 +288,7 @@In most scenarios, you do not need to use this API unless you need to custom the Dev Server or other advanced scenarios.
function AddPlugins( plugins: BuilderPlugins[], options?: AddPluginsOptions, -): Promise<void>; +): Promise<void>;
builder.addPlugins([builderPluginFoo()], { before: 'bar' }); // Insert after the bar plugin -builder.addPlugins([builderPluginFoo()], { after: 'bar' }); +builder.addPlugins([builderPluginFoo()], { after: 'bar' });
builder.removePlugins
Removes one or more Builder plugins, which can be called multiple times.
This method needs to be called before compiling. If it is called after compiling, it will not affect the compilation result.
+builder.addPlugins(pluginFoo); // remove plugin -builder.removePlugins([pluginFoo.name]); +builder.removePlugins([pluginFoo.name]);
builder.isPluginExists
- +;
Determines whether a plugin has been registered.
++builder.isPluginExists(builderPluginFoo().name); // truebuilder.inspectConfig
Inspect the final generated builder config and bundler config.
TIPThe
-inspectConfigmethod does not support simultaneous use with thestartDevServer/buildmethod.When you need to view the complete builder and bundler configurations during the build process, you can use the debug mode or obtain them through hooks such as
onBeforeBuildandonBeforeCreateCompile. +When you need to view the complete builder and bundler configurations during the build process, you can use the debug mode or obtain them through hooks such as
onBeforeBuildandonBeforeCreateCompile.builderConfig: BuilderConfig; bundlerConfigs: BundlerConfigs[]; }; -}>; +}>;
Get the config content in string format:
+console.log(builderConfig, bundlerConfigs);Write the config content to disk:
+});builder.onBeforeCreateCompiler
- +;
onBeforeCreateCompileris a callback function that is triggered after the Compiler instance has been created, but before the build process begins. This hook is called when you runbuilder.startDevServer,builder.build, orbuilder.createCompiler.You can access the Compiler instance object through the
compilerparameter:-
@@ -385,15 +385,15 @@
callback: (params: { bundlerConfigs: WebpackConfig[] | RspackConfig[]; }) => Promise<void> | void, -): void; +): void;
+});builder.onAfterCreateCompiler
- +;
onAfterCreateCompileris a callback function that is triggered after the compiler instance has been created, but before the build process. This hook is called when you runbuilder.startDevServer,builder.build, orbuilder.createCompiler.You can access the Compiler instance object through the
compilerparameter:-
@@ -409,15 +409,15 @@
+}) => Promise<void> | void;): void;
+});builder.onBeforeBuild
- +;
onBeforeBuildis a callback function that is triggered before the production build is executed. You can access the final configuration array of the underlying bundler through the `bundlerConfigs' parameter:-src/index.tsIf you want to specify a fixed name for the async module, you can use the magic comments provided by the bundler to achieve this, using
+webpackChunkNameto specify the module name:+src/index.tsIf you want to specify a fixed name for the async module, you can use the magic comments provided by the bundler to achieve this, using
webpackChunkNameto specify the module name:+);src/index.tsAfter specifying the module name as above, the generated file will be
dist/static/js/async/my-chunk-name.js.output.legalComments
- +;
inline: Preserve all legal comments in original position.Example
+Example
Remove all legal comments:
+};output.overrideBrowserslist
- +;
Specifies the range of target browsers that the project is compatible with. This value will be used by @babel/preset-env and autoprefixer to identify the JavaScript syntax that need to be transformed and the CSS browser prefixes that need to be added.
+Specifies the range of target browsers that the project is compatible with. This value will be used by @babel/preset-env and autoprefixer to identify the JavaScript syntax that need to be transformed and the CSS browser prefixes that need to be added.
Priority
The
overrideBrowserslistconfig will override the.browserslistrcconfig file in the project and thebrowserslistfield in package.json.In most cases, it is recommended to use the
-.browserslistrcfile rather than theoverrideBrowserslistconfig. Because the.browserslistrcfile is the official config file, it is more general and can be recognized by other libraries in the community.Default Value
+Default Value
If there is no
-browserslistconfigs defined in the project, noroverrideBrowserslistdefined, then Builder will set the default browserslist to:-Example
++Example
An example compatible with mobile scenarios:
-Check out the browserslist documentation to learn more about browserslist.
+}; +Check out the browserslist documentation to learn more about browserslist.
Set according to Targets
When you build multiple targets at the same time, you can set different browser ranges for different targets. At this point, you need to set
overrideBrowserslistto an object whose key is the corresponding build target.For example to set different ranges for
@@ -1223,9 +1233,9 @@webandnode:S node: ['node >= 14'], }, }, -}; +};
output.polyfill
- +;
usageEquivalent to
useBuiltIns: 'usage'configuration in@babel/preset-env.ua
The Polyfill code is dynamically delivered according to the currently requested UA information.
-The dynamic delivery feature needs to be used with the upper-level framework. For more details, please refer to Modern.js - Polyfill At Runtime.
+The dynamic delivery feature needs to be used with the upper-level framework. For more details, please refer to Modern.js - Polyfill At Runtime.
off
Polyfill is not injected. When using this option, you need to ensure code compatibility yourself.
output.svgDefaultExport
- +;
When
output.svgDefaultExportis set tourl, the default export of SVG files is the URL of the file. For example:+console.log(logo); // => asset urlWhen
output.svgDefaultExportis set tocomponent, the default export of SVG files is the React component of the file. For example:+console.log(Logo); // => React ComponentAt this time, you can also specify the
?urlquery to import the URL, for example:\ No newline at end of file +console.log(logo); // => asset urlON THIS PAGE\ No newline at end of file diff --git a/modern-js/builder/en/api/config-performance.html b/modern-js/builder/en/api/config-performance.html index a444ad9b95..c2a99b8bd8 100644 --- a/modern-js/builder/en/api/config-performance.html +++ b/modern-js/builder/en/api/config-performance.html @@ -1,4 +1,4 @@ -ON THIS PAGEPerformance Config - Modern.js Builder +Performance Config - Modern.js Builder -Modern.js Builder +};Performance Config
+Modern.js Builder + | boolean;Performance Config
This section describes some performance related configurations in Modern.js Builder.
performance.buildCache
- +;
*/ cacheDigest?: Array<string | undefined>; } - | boolean;
+};cacheDirectory: './node_modules/.custom_cache/webpack', }, }, -};
You can also disable the build cache by setting it to
false:+};cacheDigest
cacheDigestis used to add some environment variables that will affect the build results. The Builder will set the cache name based on thecacheDigestcontent and the current build mode to ensure that different cacheDigests can hit different caches.Example
@@ -70,26 +70,26 @@Example cacheDigest: [process.env.APP_ID], }, }, -}; +};
performance.bundleAnalyze
- +;
Used to enable the webpack-bundle-analyzer plugin to analyze the size of the output.
+Used to enable the webpack-bundle-analyzer plugin to analyze the size of the output.
By default, Builder does not enable
webpack-bundle-analyzer. When this feature is enabled, the default configuration is as follows:+};Enable Bundle Analyze
You have two ways to enable
webpack-bundle-analyzerto analyze the size of the output files:+performance: { bundleAnalyze: {}, }, -}; +};
After enabling it, Builder will generate an HTML file that analyzes the size of the output files, and print the following log in the Terminal:
-+You can manually open the file in the browser and view the detail of the bundle size. When an area is larger, it indicates that its corresponding bundle size is larger.
Override Default Configuration
@@ -113,7 +113,7 @@} : {}, }, -}; +};
Size Types
In the
webpack-bundle-analyzerpanel, you can control size types in the upper left corner (default isParsed):-
@@ -129,15 +129,21 @@
Gen generateStatsFile: true, }, }, -}; +};
Notes
-
-
performance.chunkSplit
- +;
forceSplitting?: ForceSplitting; } -export type ChunkSplit = BaseChunkSplit | SplitBySize | SplitCustom; +export type ChunkSplit = BaseChunkSplit | SplitBySize | SplitCustom;
chunkSplit.strategy
Builder supports the following chunk splitting strategies:
-
@@ -220,7 +226,7 @@
chun minSize: 20000, }, }, -}; +};
chunkSplit.maxSize
chun maxSize: 50000, }, }, -}; +};
chunkSplit.forceSplitting
}, }, }, -}; +};
This is an easier way than configuring webpack's splitChunks directly.
@@ -272,7 +278,7 @@TIPChunks split using the
forceSplittingconfiguration will be inserted into the HTML file as resources requested for the initial screen using<script>tags. Therefore, please split them appropriately based on the actual scenario to avoid excessive size of initial screen resources.}, }, }, -}; +};
chunkSplit.override
When
performance.chunkSplit.strategyissplit-by-experience,split-by-module,split-by-sizeorsingle-vendor, you can specify the custom webpack chunk splitting config viaperformance.chunkSplit.override. This config will be merged with the webpack splitChunks config (thecacheGroupsconfig will also be merged). For example:+};When the Builder target is "node", since Node Bundles do not need to be splitted to optimize loading performance, the chunkSplit rule will not take effect.
performance.dnsPrefetch
- +;
Specifies that the user agent should preemptively perform DNS resolution for the target resource's origin, refer to dns-prefetch.
+Specifies that the user agent should preemptively perform DNS resolution for the target resource's origin, refer to dns-prefetch.
After this property is set, the domain name can be resolved before the resource is requested, reducing request latency and improving loading performance.
-See Using dns-prefetch for more details.
-Example
+See Using dns-prefetch for more details.
+Example
+};performance.preconnect
- +;
+}Specifies that the user agent should preemptively connect to the target resource's origin, refer to preconnect.
+Specifies that the user agent should preemptively connect to the target resource's origin, refer to preconnect.
Configuring this property will establish a connection with the server. If the site is HTTPS, this process includes DNS resolution, TCP connection establishment, and TLS handshake. Combining Preconnect and DnsPrefetch can further reduce the delay of cross-domain requests.
-Example
+Example
+};performance.prefetch
- +;
type?: IncludeType; include?: Filter; exclude?: Filter; -} +}
Specifies that the user agent should preemptively fetch and cache the target resource as it is likely to be required for a followup navigation. Refer to prefetch.
+Specifies that the user agent should preemptively fetch and cache the target resource as it is likely to be required for a followup navigation. Refer to prefetch.
Boolean Type
When setting
performance.prefetchtotrue, resources will be prefetched according to the following configuration:+}Object Type
When the value of
performance.prefetchisobjecttype, the Builder will enable the prefetch capability for the specified resource according to the current configuration.prefetch.type
@@ -367,7 +373,7 @@prefetch.type
Example
+Example
When you want to prefetch all image resources in png format on the current page, you can configure it as follows:
+};performance.preload
- +;
type?: IncludeType; include?: Filter; exclude?: Filter; -} +}
Specifies that the user agent must preemptively fetch and cache the target resource for current navigation according to the potential destination given by the as attribute (and the priority associated with the corresponding destination). Refer to preload.
-Boolean Type
+Specifies that the user agent must preemptively fetch and cache the target resource for current navigation according to the potential destination given by the as attribute (and the priority associated with the corresponding destination). Refer to preload.
+Boolean Type
When setting
performance.preloadtotrue, resources will be preloaded according to the following configuration:-Object Type
+} +Object Type
When the value of
performance.preloadisobjecttype, the Builder will enable the preload capability for the specified resource according to the current configuration.preload.type
The
@@ -411,7 +417,7 @@typefield controls which resources will be pre-fetched, and supports secondary filtering of specified resources throughincludeandexclude.preload.type
all-chunks: preload all resources (on the current page), including all asynchronous and non-asynchronous resources.Example
+Example
When you want to preload all image resources in png format on the current page, you can configure it as follows:
+};performance.printFileSize
- +;
dist/static/js/lib-react.09721b5c.js 152.6 kB 49.0 kB dist/html/main/index.html 5.8 kB 2.5 kB dist/static/js/main.3568a38e.js 3.5 kB 1.4 kB - dist/static/css/main.03221f72.css 1.4 kB 741 B -
Example
+ dist/static/css/main.03221f72.css 1.4 kB 741 B +Example
Disable the logs:
+};performance.profile
- +;
Whether capture timing information for each module, same as the profile config of webpack / Rspack.
-Example
+Whether capture timing information for each module, same as the profile config of webpack / Rspack.
+Example
+};When turned on, webpack / Rspack generates a JSON file with some statistics about the module that includes information about timing information for each module.
performance.removeConsole
- +;
Remove performance: { removeConsole: true, }, -}; +};
Remove specific console
You can also specify to remove only certain types of
console.xx, such asconsole.logandconsole.warn:+};The following types of console are currently supported:
-+performance.removeMomentLocale
- +;
Whether to remove the locales of moment.js.
+Whether to remove the locales of moment.js.
moment.jscontains a lot of locales by default, which will increase the bundle size.When
moment.jsis used in the project, it is recommended to enable this option to automatically exclude all locales:+};Once enabled, you can load a specific locale via:
+moment.locale('zh-cn');performance.transformLodash
- +;
Specifies whether to modularize the import of lodash and remove unused lodash modules to reduce the code size of lodash.
-This optimization is implemented using babel-plugin-lodash and swc-plugin-lodash under the hood.
-Example
+Specifies whether to modularize the import of lodash and remove unused lodash modules to reduce the code size of lodash.
+This optimization is implemented using babel-plugin-lodash and swc-plugin-lodash under the hood.
+Example
This option is enabled by default, and Builder will automatically redirects the code references of
lodashto sub-paths.For example:
+_.map([1, 2, 3], addOne);input.jsThe transformed code will be:
+_map([1, 2, 3], addOne);output.jsDisabling the Transformation
In some cases, the import transformation of
lodashmay generate unexpected code. In such cases, you can manually disable this optimization:\ No newline at end of file +};ON THIS PAGE\ No newline at end of file diff --git a/modern-js/builder/en/api/config-security.html b/modern-js/builder/en/api/config-security.html index ec420a35d0..889ba4aeaa 100644 --- a/modern-js/builder/en/api/config-security.html +++ b/modern-js/builder/en/api/config-security.html @@ -1,4 +1,4 @@ -ON THIS PAGESecurity Config - Modern.js Builder +Security Config - Modern.js Builder -Modern.js Builder + };Security Config
+Modern.js Builder + | boolean;Security Config
This section describes some security related configurations in Modern.js Builder.
security.sri
- +;
secu enabled?: 'auto' | boolean; hashLoading?: 'eager' | 'lazy'; } - | boolean;
Adding an integrity attribute (
-integrity) to sub-resources introduced by HTML allows the browser to verify the integrity of the introduced resource, thus preventing tampering with the downloaded resource.Enabling this option will set the webpack output.crossOriginLoading configuration option to
+anonymous.Enabling this option will set the webpack output.crossOriginLoading configuration option to
anonymous.Introduce SRI
Subresource Integrity (SRI) is a security feature that enables browsers to verify that resources they fetch (for example, from a CDN) are delivered without unexpected manipulation. It works by allowing you to provide a cryptographic hash that a fetched resource must match.
For script tags, the result is to refuse to execute the code; for CSS links, the result is not to load the styles.
-For more on subresource integrity, see Subresource Integrity - MDN.
+For more on subresource integrity, see Subresource Integrity - MDN.
Example
By default,
SRIis not turned on, and when it is, its default configuration is as follows:+}You can customize the configuration options according to your own needs:
+};security.checkSyntax
- +;
targets?: string[]; exclude?: RegExp | RegExp[]; ecmaVersion?: EcmaVersion; - };
Enabl security: { checkSyntax: true, }, -}; +};
When you enable
checkSyntax, Builder will perform the detection during production builds. If any incompatible advanced syntax is detected in the build artifacts, error logs will be printed to the terminal, and the current build process will be terminated.Error Logs
The format of the error logs is as follows, including the source file, artifact location, error reason, and source code:
@@ -88,7 +88,7 @@Error Logs< > 12 | console.log(() => { 13 | return a + b; 14 | }); - 15 | + 15 |
TIPCurrently, syntax checking is implemented based on AST parser. Each time it performs a check, it can only identify the first incompatible syntax found in the file. If there are multiple incompatible syntaxes in the file, you need to fix the detected syntax and re-run the check.output.disableMinimize to true and rebuild again.
If the corresponding source location is not shown in the log, try setting
Solutions
@@ -104,7 +104,7 @@checkSy
+targetsis the target browser range of the project. Its value is a standard browserslist array. If you are not familiar with the usage of browserslist, please refer to "Browserslist".targetsis the target browser range of the project. Its value is a standard browserslist array. If you are not familiar with the usage of browserslist, please refer to "Browserslist".Builder will read the value of
targetsand automatically deduce the minimum ECMAScript syntax version that can be used in the build artifacts, such asES5orES6.checkSy targets: ['chrome >= 53'], }, }, -}; +};
Builder will deduce that the ECMAScript syntax version that can be used with
chrome >= 53isES6. When the build artifacts containES2016or higher syntax, it triggers syntax error prompts.@@ -136,7 +136,7 @@TIPPlease note that Builder does not support automatic analysis of syntax versions above ES6 based on
targets. If the syntax version compatible with your build artifacts exceeds ES6, please usecheckSyntax.ecmaVersionto set it.che ecmaVersion: 2020, }, }, -}; +};
At this time, the build artifacts can include all syntax supported by
ES2020, such as optional chaining.checkSyntax.exclude
-
@@ -154,4 +154,4 @@
checkSy exclude: /node_modules\/foo/, }, }, -};
\ No newline at end of file +};ON THIS PAGE\ No newline at end of file diff --git a/modern-js/builder/en/api/config-source.html b/modern-js/builder/en/api/config-source.html index a7053a030c..89c9f1003c 100644 --- a/modern-js/builder/en/api/config-source.html +++ b/modern-js/builder/en/api/config-source.html @@ -1,4 +1,4 @@ -ON THIS PAGESource Config - Modern.js Builder +Source Config - Modern.js Builder -Modern.js Builder Source Config
+Modern.js Builder +};+};Source Config
This section describes configs related to source code parsing and compilation in Modern.js Builder.
source.alias
- +;
Create aliases to import or require certain modules, same as the resolve.alias config of webpack and Rspack.
-TIPFor TypeScript projects, you only need to configure compilerOptions.paths in the
tsconfig.jsonfile. The Builder will automatically recognize it, so there is no need to configure thesource.aliasoption separately. For more details, please refer to Path Aliases. +Create aliases to import or require certain modules, same as the resolve.alias config of webpack and Rspack.
+TIPFor TypeScript projects, you only need to configure compilerOptions.paths in the
tsconfig.jsonfile. The Builder will automatically recognize it, so there is no need to configure thesource.aliasoption separately. For more details, please refer to Path Aliases.Object Type
The
@@ -27,7 +27,7 @@aliascan be an Object, and the relative path will be automatically converted to absolute path.Object Typ '@common': './src/common', }, }, -};
With above configuration, if
@common/Foo.tsxis import in the code, it will be mapped to the<project>/src/common/Foo.tsxpath.Function Type
The
@@ -37,7 +37,7 @@aliascan be a function, it will accept the previous alias object, and you can modify it.Function alias['@common'] = './src/common'; }, }, -};
You can also return a new object as the final result in the function, which will replace the previous alias object.
+};Exact Matching
By default,
source.aliaswill automatically match sub-paths, for example, with the following configuration:+};It will match as follows:
+import b from '@common/util'; // resolved to `./src/common/util`You can add the
$symbol to enable exact matching, which will not automatically match sub-paths.+};It will match as follows:
+import b from '@common/util'; // remains as `@common/util`Handling npm packages
You can use
aliasto resolve an npm package to a specific directory.For example, if multiple versions of the
@@ -86,11 +86,11 @@reactare installed in the project, you can aliasreactto the version installed in the rootnode_modulesdirectory to avoid bundling multiple copies of the React code.react: path.resolve(__dirname, './node_modules/react'), }, }, -}; +};
When using alias to handle npm packages, please be aware of whether different major versions of the package are being used in the project.
For example, if a module or npm dependency in your project uses the React 18 API, and you alias React to version 17, the module will not be able to reference the React 18 API, resulting in code exceptions.
source.aliasStrategy
- +;
prefer "@common/*": ["./src/common-1/*"] } } -} +}
prefer '@utils': './src/utils', }, }, -}; +};
Since the tsconfig paths have a higher priority, the following will happen:
prefer-al source: { aliasStrategy: 'prefer-alias', }, -}; +};
For example, if the following configurations are set at the same time:
prefer-al "@utils/*": ["./src/utils/*"] } } -} +}
prefer-al '@common': './src/common-2', }, }, -}; +};
Since the tsconfig paths are only used to provide types, only the
@commonalias will be effective, pointing to the./src/common-2directory.In most cases, you don't need to use
prefer-alias, but you can consider using it if you need to dynamically generate some alias configurations. For example, generating thealiasoption based on environment variables:+};source.include
- +;
-
-
+];The
source.includeis used to specify additional JavaScript files that need to be compiled.To avoid redundant compilation, by default, Rsbuild only compiles JavaScript files in the current directory and TypeScript and JSX files in all directories. It does not compile JavaScript files under node_modules.
-Through the
+source.includeconfig, you can specify directories or modules that need to be compiled by Rsbuild. The usage ofsource.includeis consistent with Rule.include in Rspack, which supports passing in strings or regular expressions to match the module path.Through the
source.includeconfig, you can specify directories or modules that need to be compiled by Rsbuild. The usage ofsource.includeis consistent with Rule.include in Rspack, which supports passing in strings or regular expressions to match the module path.For example:
+};Compile Npm Packages
A typical usage scenario is to compile npm packages under node_modules, because some third-party dependencies have ES6+ syntax, which may cause them to fail to run on low-version browsers. You can solve the problem by using this config to specify the dependencies that need to be compiled.
Take
@@ -207,7 +207,7 @@query-stringas an example, you can add the following config:C /\/node_modules\/query-string\//, ], }, -}; +};
The above two methods match the absolute paths of files using "path prefixes" and "regular expressions" respectively. It is worth noting that all referenced modules in the project will be matched. Therefore, you should avoid using overly loose values for matching to prevent compilation performance issues or compilation errors.
Compile Sub Dependencies
When you compile an npm package via
@@ -219,7 +219,7 @@source.include, Builder will only compile the matching module by default, not the Sub Dependencies of the module./\/node_modules\/decode-uri-component\//, ], }, -}; +};
Compile Libraries in Monorepo
When developing in Monorepo, if you need to refer to the source code of other libraries in Monorepo, you can add the corresponding library to
source.include:+};Compile CommonJS Module
Babel cannot compile CommonJS modules by default, and if you compile a CommonJS module, you may get a runtime error message
exports is not defined.When you need to compile a CommonJS module using
@@ -247,27 +247,27 @@source.include, you can set Babel'ssourceTypeconfiguration tounambiguous.config.sourceType = 'unambiguous'; }, }, -}; -
Setting
+}; +sourceTypetounambiguousmay have some other effects, please refer to Babel official documentation.Setting
sourceTypetounambiguousmay have some other effects, please refer to Babel official documentation.Matching Symlink
If you match a module that is symlinked to the current project, then you need to match the real path of the module, not the symlinked path.
For example, if you symlink the
-packages/foopath in Monorepo to thenode_modules/foopath of the current project, you need to match thepackages/foopath, not thenode_modules/foopath.This behavior can be controlled via webpack's resolve.symlinks config.
+This behavior can be controlled via webpack's resolve.symlinks config.
Precautions
Note that
source.includeshould not be used to compile the entirenode_modulesdirectory. For example, the following usage is wrong:+};If you compile the entire
node_modules, not only will the build time be greatly increased, but also unexpected errors may occur. Because most of the npm packages innode_modulesare already compiled, there is usually no need for a second compilation. In addition, exceptions may occur after npm packages such ascore-jsare compiled.source.exclude
- +;
Specifies JavaScript/TypeScript files that do not need to be compiled. The usage is consistent with Rule.exclude in webpack, which supports passing in strings or regular expressions to match the module path.
+Specifies JavaScript/TypeScript files that do not need to be compiled. The usage is consistent with Rule.exclude in webpack, which supports passing in strings or regular expressions to match the module path.
For example:
+};source.define
- +;
sou
For more information please visit webpack - DefinePlugin.
-TIPWhen using Rspack as the bundler, the supported types can be found in Rspack.builtins.define. +
For more information please visit webpack - DefinePlugin.
+TIPWhen using Rspack as the bundler, the supported types can be found in Rspack.builtins.define.
Example
+};Expressions will be replaced with the corresponding code fragments:
+const foo = 1 + 1;source.globalVars
- +;
// The environment variable `process.env.NODE_ENV` will be added by default, // so you don't need to set it in manually. 'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV), -}; +};
Used to define global variables. It can replace expressions like
process.env.FOOin your code after compile. Such as:-Example
+console.log('development'); +Example
In the following example, the
ENABLE_VCONSOLEandAPP_CONTEXTare injected into the code:+};You can use them directly in your code:
+console.log(APP_CONTEXT);Function Usage
Functio
+) => Record<string, JSONValue> | void;You can set
source.globalVarsto a function to dynamically setting some environment variables.For example, dynamically set according to the build target:
+};Difference with define
You can take
source.globalVarsas the syntax sugar ofsource.define, the only difference is thatsource.globalVarswill automatically stringify the value, which makes it easier to set the value of global variables. The values ofglobalVarsshould be JSON-safe to ensure it can be serialized.-Precautions
+}; +Precautions
source.globalVarsinjects environment variables through string replacement, so it cannot take effect on dynamic syntaxes such as destructuring.When using destructuring assignment, Builder will not be able to determine whether the variable
NODE_ENVis associated with the expressionprocess.env.NODE_ENVto be replaced, so the following usage is invalid:+// ❌ Won't get a string.source.moduleScopes
- +;
Restrict importing paths. After configuring this option, all source files can only import code from the specific paths, and import code from other paths is not allowed.
-Example
+Example
First, we configure
moduleScopesto only include thesrcdirectory:+};Then we import the
-utils/amodule outside thesrcdirectory insrc/App.tsx:+After compiling, there will be a reference path error:
If we configure the
@@ -409,15 +409,15 @@utilsdirectory inmoduleScopes, the error will disappear.Example source: { moduleScopes: ['./src', './utils'], }, -}; +};
Array Type
You can directly set several paths like this:
-Function Type
+}; +Function Type
moduleScopesalso supports setting as a function, which can be modified instead of overriding the default value:+};source.transformImport
- -Used to import the code and style of the component library on demand, which is equivalent to babel-plugin-import.
-The difference between it and babel-plugin-import is that
+source.transformImportis not coupled with Babel. Builder will automatically identify whether the currently used tools is Babel, SWC or Rspack, and apply the corresponding on-demand import configuration.;
+Used to import the code and style of the component library on demand, which is equivalent to babel-plugin-import.
+The difference between it and babel-plugin-import is that
source.transformImportis not coupled with Babel. Builder will automatically identify whether the currently used tools is Babel, SWC or Rspack, and apply the corresponding on-demand import configuration.transformToDefaultImport?: boolean; customName?: ((member: string) => string | undefined) | string; customStyleName?: ((member: string) => string | undefined) | string; - }>; + }>;
When the Ant Design component library <= 4.x version is installed in the project, Builder will automatically add the following default configurations:
+When the Ant Design component library <= 4.x version is installed in the project, Builder will automatically add the following default configurations:
-When the Arco Design component library is installed in the project, Builder will automatically add the following default configurations:
+}; +When the Arco Design component library is installed in the project, Builder will automatically add the following default configurations:
+];-TIPWhen you add configurations for
antdor@arco-design/web-react, the priority will be higher than the default configurations mentioned above.Example
+Example
When using the above antd default configuration:
+};The source code is as follows:
-+It will be transformed into:
+import 'antd/es/button/style';Disable Default Config
You can manually set
transformImport: falseto disable the default config.+};For example, if you use
externalsto avoid bundling antd, becausetransformImportwill convert the imported path of antd by default, the matching path changes and externals cannot take effect. At this time, you can disabletransformImportto avoid this problem.Configuration
libraryName
@@ -509,9 +509,9 @@libraryDi
Used to splice the transformed path, the splicing rule is
${libraryName}/${libraryDirectory}/${member}, where member is the imported member.Example:
-+Out:
-+style
styleDetermines whether to import related styles. If it is
true, the path${libraryName}/${libraryDirectory}/${member}/stylewill be imported. If it isfalseorundefined, the style will not be imported.When it is set to
-true:+Out:
+import 'foo/lib/button/style';styleLibraryDirectory
styl
This configuration is used to splice the import path when importing styles. If this configuration is specified, the
styleconfiguration option will be ignored. The spliced import path is${libraryName}/${styleLibraryDirectory}/${member}.When it is set to
-styles:+Out:
+import 'foo/styles/button';camelToDashComponentName
c
Whether to convert camelCase imports to kebab-case.
Example:
-+Out:
+import ButtonGroup from 'foo/ButtonGroup';transformToDefaultImport
t
Whether to convert import statements to default imports.
Example:
-+Out:
+import { Button } from 'foo/button';customName
customName
Customize the imported path after conversion. The input is the imported member. For example, configure it as
-(member) => `my-lib/${member}`, which will convertimport { foo } from 'bar'toimport foo from 'my-lib/foo'.When using Rspack to build, function configurations cannot be used, but you can use handlebars template strings. For the above function configuration, you can use the following template instead of
+my-lib/{{ member }}, or use some built-in helper methods, such asmy-lib/{{ kebabCase member }}to convert it to kebab-case format. In addition to kebabCase, there are also camelCase, snakeCase, upperCase, and lowerCase that can be used.When using Rspack to build, function configurations cannot be used, but you can use handlebars template strings. For the above function configuration, you can use the following template instead of
my-lib/{{ member }}, or use some built-in helper methods, such asmy-lib/{{ kebabCase member }}to convert it to kebab-case format. In addition to kebabCase, there are also camelCase, snakeCase, upperCase, and lowerCase that can be used.customStyleName
customStyl
Customize the imported style path after conversion. The input is the imported member. For example, configure it as
-(member) => `my-lib/${member}`, which will convertimport { foo } from 'bar'toimport foo from 'my-lib/foo'.When using Rspack to build, function configurations cannot be used, but you can use handlebars template strings. For the above function configuration, you can use the following template instead of
+my-lib/{{ member }}, or use some built-in helper methods, such asmy-lib/{{ kebabCase member }}to convert it to kebab-case format. In addition to kebabCase, there are also camelCase, snakeCase, upperCase, and lowerCase that can be used.When using Rspack to build, function configurations cannot be used, but you can use handlebars template strings. For the above function configuration, you can use the following template instead of
my-lib/{{ member }}, or use some built-in helper methods, such asmy-lib/{{ kebabCase member }}to convert it to kebab-case format. In addition to kebabCase, there are also camelCase, snakeCase, upperCase, and lowerCase that can be used.source.preEntry
- +;
s
Add a script before the entry file of each page. This script will be executed before the page code. It can be used to execute global logics, such as injecting polyfills, setting global styles, etc.
Add a single script
First create a
-src/polyfill.tsfile:+Then configure
src/polyfill.tstosource.preEntry:+};Re-run the compilation and visit any page, you can see that the code in
src/polyfill.tshas been executed, and theI am a polyfillis logged in the console.Add global style
You can also configure the global style through
@@ -609,34 +609,34 @@source.preEntry, this CSS code will be loaded earlier than the page code, such as introducing anormalize.cssfile:Add globa source: { preEntry: './src/normalize.css', }, -}; +};
Add multiple scripts
You can add multiple scripts by setting
preEntryto an array, and they will be executed in array order:+};source.resolveExtensionPrefix
- +;
Add a prefix to resolve.extensions.
+Add a prefix to resolve.extensions.
If multiple files share the same name but have different extensions, Builder will resolve the one with the extension listed first in the array and skip the rest.
-Example
+Example
+};With the configuration above, the extensions array will become:
+const extensions = ['.web.js', '.js', '.web.ts' , '.ts', ...];When
import './foo'in the code, thefoo.web.jsfile will be resolved first, then thefoo.jsfile.Set according to Targets
When you build multiple targets at the same time, you can set different extension prefix for different targets. At this point, you need to set
@@ -650,27 +650,27 @@resolveExtensionPrefixto an object whose key is the corresponding build target.S }, }, }, -}; +};
When
import './foo'in the code, thefoo.node.jsfile will be resolved for node target, and thefoo.web.jsfile will be resolved for web target.source.resolveMainFields
- +;
+type ResolveMainFields = Fields | Record<BuilderTarget, Fields>;This config will determine which field of
-package.jsonyou use to import thenpmmodule. Same as the resolve.mainFields config of webpack.Example
+This config will determine which field of
+package.jsonyou use to import thenpmmodule. Same as the resolve.mainFields config of webpack.Example
-Set according to Targets
+}; +Set according to Targets
When you build multiple targets at the same time, you can set different mainFields for different targets. At this point, you need to set
resolveMainFieldsto an object whose key is the corresponding build target.For example to set different mainFields for
webandnode:\ No newline at end of file +};ON THIS PAGE\ No newline at end of file diff --git a/modern-js/builder/en/api/config-tools.html b/modern-js/builder/en/api/config-tools.html index 11257943b2..ed5ef79a4c 100644 --- a/modern-js/builder/en/api/config-tools.html +++ b/modern-js/builder/en/api/config-tools.html @@ -1,4 +1,4 @@ -ON THIS PAGETools Config - Modern.js Builder +Tools Config - Modern.js Builder -Modern.js Builder Tools Config
+Modern.js Builder +-Tools Config
This section describes some low-level tools configurations in Modern.js Builder.
tools.autoprefixer
- +;
// Depends on the browserslist config in the project // and the `output.overrideBrowserslist` (higher priority) config overrideBrowserslist: browserslist, -}
You can modify the config of autoprefixer by
+}tools.autoprefixer.You can modify the config of autoprefixer by
tools.autoprefixer.Object Type
When
tools.autoprefixeris configured asObjecttype, it is merged with the default config through Object.assign. For example:+};Function Type
When
tools.autoprefixeris a Function, the default config is passed as the first parameter and can be directly modified or returned as the final result. For example:+};tools.babel
- +;
With
+tools.babelyou can modify the options of babel-loader.With
tools.babelyou can modify the options of babel-loader.Usage Scenarios
Please note the limitations of
tools.babelin the following usage scenarios:Function Type
+Function Type
When
tools.babelis of typeFunction, the default Babel configuration will be passed as the first parameter. You can directly modify the configuration object or return an object as the finalbabel-loaderconfiguration.+};The second parameter of the
tools.babelfunction provides some more convenient utility functions. Please continue reading the documentation below.-TIPThe above example is just for reference, usually you don't need to manually configure
babel-plugin-import, because the Builder already provides a more generalsource.transformImportconfiguration.Object Type
+Object Type
When
tools.babel's type isObject, the config will be shallow merged with default config byObject.assign.@@ -95,7 +95,7 @@CAUTIONNote that
Object.assignis a shallow copy and will completely overwrite the built-inpresetsorpluginsarray, please use it with caution.Object Typ ], }, }, -}; +};
Util Functions
When
tools.babelis a Function, the tool functions available for the second parameter are as follows:addPlugins
@@ -118,7 +118,7 @@addPlugins ]); }, }, -}; +};
addPresets
addPresets addPresets(['@babel/preset-env']); }, }, -}; +};
removePlugins
removePlugin removePlugins('babel-plugin-import'); }, }, -}; +};
removePresets
removePreset removePresets('@babel/preset-env'); }, }, -}; +};
modifyPresetEnvOptions
Modify the configuration of @babel/preset-env, the configuration you pass in will be shallowly merged with default config. For example:
+Modify the configuration of @babel/preset-env, the configuration you pass in will be shallowly merged with default config. For example:
+};modifyPresetReactOptions
Modify the configuration of @babel/preset-react, the configuration you pass in will be shallowly merged with default config. For example:
+Modify the configuration of @babel/preset-react, the configuration you pass in will be shallowly merged with default config. For example:
+};addIncludes
-Deprecated, please use source.include instead, both have the same functionality.
+Deprecated, please use source.include instead, both have the same functionality.
addExcludes
-Deprecated, please use source.exclude instead, both have the same functionality.
+Deprecated, please use source.exclude instead, both have the same functionality.
Debugging Babel Configuration
-After modifying the
+babel-loaderconfiguration throughtools.babel, you can view the final generated configuration in Builder debug mode.After modifying the
babel-loaderconfiguration throughtools.babel, you can view the final generated configuration in Builder debug mode.First, enable debug mode by using the
DEBUG=builderparameter:+DEBUG=builder pnpm buildThen open the generated
(webpack|rspack).config.web.jsfile and search for thebabel-loaderkeyword to see the completebabel-loaderconfiguration.tools.bundlerChain
- +;
You can modify the webpack and Rspack configuration by configuring
tools.bundlerChainwhich is type ofFunction. The function receives two parameters, the first is the original bundler chain object, and the second is an object containing some utils.What is BundlerChainBundler chain is a subset of webpack chain, which contains part of the webpack chain API that you can use to modify both webpack and Rspack configuration.
-Configurations modified via bundler chain will work on both webpack and Rspack builds. Note that the bundler chain only supports modifying the configuration of the non-differentiated parts of webpack and Rspack. For example, modifying the devtool configuration option (webpack and Rspack have the same devtool property value type), or adding an Rspack-compatible webpack plugin.
+Configurations modified via bundler chain will work on both webpack and Rspack builds. Note that the bundler chain only supports modifying the configuration of the non-differentiated parts of webpack and Rspack. For example, modifying the devtool configuration option (webpack and Rspack have the same devtool property value type), or adding an Rspack-compatible webpack plugin.
-tools.bundlerChainis executed earlier than tools.webpackChain / tools.webpack / tools.rspack and thus will be overridden by changes in others.Utils
-env
--
-
The
-envparameter can be used to determine whether the current environment is development, production or test. For example:-isProd
--
-
The
-isProdparameter can be used to determine whether the current environment is production. For example:-target
--
-
The
-targetparameter can be used to determine the current environment. For example:-isServer
--
-
Determines whether the target environment is
-node, equivalent totarget === 'node'.-isWebWorker
--
-
Determines whether the target environment is
-web-worker, equivalent totarget === 'web-worker'.-HtmlPlugin
--
-
The HtmlPlugin instance in webpack or Rspack:
--CHAIN_ID
-Some common Chain IDs are predefined in the Builder, and you can use these IDs to locate the built-in Rule or Plugin.
--TIPPlease note that some of the rules or plugins listed below are not available by default. They will only be included in the Rspack or webpack configuration when you enable specific options or register certain plugins.
-For example, the
RULE.STYLUSrule exists only when the Stylus plugin is registered. -CHAIN_ID.RULE
-- -
-- - - -ID -Description -- -RULE.MJSRule for -mjs- -RULE.CSSRule for -css- -RULE.LESSRule for -less- -RULE.SASSRule for -sass- -RULE.STYLUSRule for -stylus- -RULE.TOMLRule for -toml- -RULE.YAMLRule for -yaml- -RULE.WASMRule for -WASM- - -RULE.NODERule for -nodeCHAIN_ID.ONE_OF
-
-ONE_OF.XXXcan match a certain type of rule in the rule array.- -
-- - - -ID -Description -- -ONE_OF.SVGRules for SVG, automatic choice between data URI and separate file -- -ONE_OF.SVG_URLRules for SVG, output as a separate file -- -ONE_OF.SVG_INLINERules for SVG, inlined into bundles as data URIs -- - -ONE_OF.SVG_ASSETSRules for SVG, automatic choice between data URI and separate file -CHAIN_ID.USE
-
-USE.XXXcan match a certain loader.- -
-- - - -ID -Description -- -USE.LESScorrespond to -less-loader- -USE.SASScorrespond to -sass-loader- -USE.STYLUScorrespond to -stylus-loader- -USE.VUEcorrespond to -vue-loader- -USE.TOMLcorrespond to -toml-loader- -USE.YAMLcorrespond to -yaml-loader- -USE.NODEcorrespond to -node-loader- -USE.SVGRcorrespond to -@svgr/webpack- -USE.POSTCSScorrespond to -postcss-loader- - -USE.RESOLVE_URL_LOADER_FOR_SASScorrespond to -resolve-url-loaderCHAIN_ID.PLUGIN
-
-PLUGIN.XXXcan match a certain webpack plugin.- -
-- - - -ID -Description -- -PLUGIN.HTMLcorrespond to -HtmlPlugin, you need to splice the entry name when using:${PLUGIN.HTML}-${entryName}- -PLUGIN.APP_ICONcorrespond to -AppIconPlugin- -PLUGIN.INLINE_HTMLcorrespond to -InlineChunkHtmlPlugin- -PLUGIN.BUNDLE_ANALYZERcorrespond to -WebpackBundleAnalyzer- -PLUGIN.VUE_LOADER_PLUGINcorrespond to -VueLoaderPlugin- - -PLUGIN.AUTO_SET_ROOT_SIZEcorrespond to automatically set root font size plugin in Builder -CHAIN_ID.MINIMIZER
-
-MINIMIZER.XXXcan match a certain minimizer.- -
-- - - -ID -Description -- -MINIMIZER.JScorrespond to -TerserWebpackPluginorSwcJsMinimizerRspackPlugin- - -MINIMIZER.CSScorrespond to -CssMinimizerWebpackPluginExamples
-For usage examples, please refer to: WebpackChain usage examples.
+For more information, please refer to Rsbuild#tools.bundlerChain
tools.cssExtract
- +;
chunkFilename: `${cssPath}/async/${cssFilename}`, ignoreOrder: true, }, -}; +};
The config of mini-css-extract-plugin can be modified through
-tools.cssExtract.Object Type
+The config of mini-css-extract-plugin can be modified through
+tools.cssExtract.Object Type
When this value is an Object, it is merged with the default config via Object.assign. For example:
-Function Type
+}; +Function Type
When the value a Function, the default config is passed in as the first parameter. You can modify the config object directly, or return an object as the final config. For example:
-For more config details, please refer to mini-css-extract-plugin.
+}; +For more config details, please refer to mini-css-extract-plugin.
tools.cssLoader
- +;
The config of css-loader can be modified through
+tools.cssLoader. The default config is as follows:The config of css-loader can be modified through
tools.cssLoader. The default config is as follows:-+TIPWhen using Rspack as the bundler, this configuration is only supported when set disableCssExtract is true.
-To modify CSS Modules configuration, it is recommended to use the output.cssModules configuration. +}
-TIPWhen using Rspack as the bundler, this configuration is only supported when set disableCssExtract is true.
+To modify CSS Modules configuration, it is recommended to use the output.cssModules configuration.
Object Type
+Object Type
When this value is an Object, it is merged with the default config via deep merge. For example:
-Function Type
+}; +Function Type
When the value is a Function, the default config is passed in as the first parameter. You can modify the config object directly, or return an object as the final config. For example:
+};tools.devServer
- +;
The config of DevServer can be modified through
-tools.devServer.+};TIPModern.js does not directly use webpack-dev-server or @rspack/dev-server, but implement DevServer based on webpack-dev-middleware. +
TIPModern.js does not directly use webpack-dev-server or @rspack/dev-server, but implement DevServer based on webpack-dev-middleware.
Options
after
@@ -601,7 +329,7 @@after ], }, }, -};
webpack-dev-serveruses Express as the server-side framework. Modern.js does not use any framework, and thereqandresin the above middleware are all native Node objects. Therefore, the Express middleware used inwebpack-dev-servermay not be directly usable in Modern.js.If you want to migrate the Express middleware used in
webpack-dev-server, you can use the following method to pass the Express app as middleware:+};before
before ], }, }, -}; +};
client
client port?: string; /** Specify a host to use */ host?: string; -} +}
client host: '', // By default it is set to "location.protocol === 'https:' ? 'wss' : 'ws'"" protocol: '', -}; +};
The config of HMR client, which are usually used to set the WebSocket URL of HMR.
compress
-
@@ -676,21 +404,21 @@
compress compress: false, }, }, -}; +};
devMiddleware
+}-The config of devMiddleware. Current options is the subset of webpack-dev-middleware.
+} +The config of devMiddleware. Current options is the subset of webpack-dev-middleware.
headers
headers }, }, }, -}; +};
historyApiFallback
history historyApiFallback: true, }, }, -}; -
For more options and information, see the connect-history-api-fallback documentation.
+}; +For more options and information, see the connect-history-api-fallback documentation.
hot
Enable Hot Module Replacement feature.
+Enable Hot Module Replacement feature.
https
https }, }, }, -}; +};
liveReload
setupMidd ) => void; }, ) => void ->; +>;
setupMidd ], }, }, -}; +};
It is possible to use some server api to meet special scenario requirements:
setupMidd ], }, }, -}; +};
proxy
proxy }, }, }, -}; -
A request to /api/users will now proxy the request to http://localhost:3000/api/users.
+}; +A request to /api/users will now proxy the request to http://localhost:3000/api/users.
If you don't want /api to be passed along, we need to rewrite the path:
-The DevServer Proxy makes use of the http-proxy-middleware package. Check out its documentation for more advanced usages.
+}; +The DevServer Proxy makes use of the http-proxy-middleware package. Check out its documentation for more advanced usages.
The full type definition of DevServer Proxy is:
+ | ProxyDetail;In addition to the http-proxy-middleware option, we also support the bypass and context configuration:
- 类型：
console.log(port); // 8080
// 关闭 Dev Server
-await server.close();
+await server.close();
自定义 URL 输出
将 printURLs 设置为 false 可以禁用默认的 URL 输出，此时你可以输出自定义的日志内容。
你也可以直接将 printURLs 配置为一个函数来修改 URL，比如给每个 URL 增加一个子路径：
严格限制端口
当端口被占用时，Builder 会自动递增端口号，直至找到一个可用端口。
如果你希望在端口被占用时抛出异常，可以将 strictPort 设置为 true。
自定义 Compiler
个别情况下，你可能希望使用自定义的 compiler：
静默获取端口号
某些情况下，默认启动的端口号已经被占用，此时 Builder 会自动递增端口号，直至找到一个可用端口。这个过程会输出提示日志，如果你不希望这段日志，可以将 getPortSliently 设置为 true。
自定义日志输出对象
默认情况下，Builder 会使用 @modern-js/utils/logger 来输出日志，你可以通过 logger 参数来自定义日志输出对象。
这样，Builder 会使用你自定义的日志输出对象来输出日志。
builder.serve
在本地启动 Server 来预览生产环境构建的产物，需要在 builder.build 方法之后执行。
bui
server: Server;
};
-function server(): Promise<StartServerResult>;
+function server(): Promise<StartServerResult>;
启动 Server：
-serve 会返回以下参数：
bui
console.log(port); // 8080
// 关闭 Server
-await server.close();
+await server.close();
builder.createCompiler
创建一个 compiler 对象。
当 createBuilder 的 target 选项包含一个值时，返回值为 Compiler；当 target 包含多个值时，返回值为 MultiCompiler。
@@ -288,7 +288,7 @@大部分场景下，不需要使用该 API，除非需要进行自定义 Dev Server 等高级操作。
function AddPlugins(
plugins: BuilderPlugins[],
options?: AddPluginsOptions,
-): Promise<void>;
+): Promise<void>;
@@ -298,14 +298,14 @@ builder.addPlugins([builderPluginFoo()], { before: 'bar' });
// 在 bar 插件之后插入
-builder.addPlugins([builderPluginFoo()], { after: 'bar' });
+builder.addPlugins([builderPluginFoo()], { after: 'bar' });
builder.removePlugins
builder.removePlugins
移除一个或多个 builder 插件，可以被多次调用。
该方法需要在开始编译前调用，如果在开始编译之后调用，则不会影响编译结果。
builder.addPlugins(pluginFoo);
// 移除插件
-builder.removePlugins([pluginFoo.name]);
+builder.removePlugins([pluginFoo.name]);
builder.isPluginExists
-
+
;
判断某个插件是否已经被注册。
builder.inspectConfig
查看 Builder 内部最终生成的 builder 配置和 bundler 配置。
builderConfig: BuilderConfig;
bundlerConfigs: BundlerConfigs[];
};
-}>;
+}>;
拿到字符串格式的 Config 内容：
直接将配置内容写入到磁盘上：
builder.onBeforeCreateCompiler
- +;
onBeforeCreateCompiler 是在创建底层 Compiler 实例前触发的回调函数，当你执行 builder.startDevServer、builder.build 或 builder.createCompiler 时，都会调用此钩子。
你可以通过 bundlerConfigs 参数获取到底层打包工具的最终配置数组：
-
@@ -383,15 +383,15 @@
callback: (params: {
bundlerConfigs: WebpackConfig[] | RspackConfig[];
}) => Promise<void> | void,
-): void;
+): void;
+});
builder.onAfterCreateCompiler
-
+
;
onAfterCreateCompiler 是在创建 Compiler 实例后、执行构建前触发的回调函数，当你执行 builder.startDevServer、builder.build 或 builder.createCompiler 时，都会调用此钩子。
你可以通过 compiler 参数获取到 Compiler 实例对象:
-
@@ -407,15 +407,15 @@
+}) => Promise<void> | void;): void;
+});
builder.onBeforeBuild
-
+
;
onBeforeBuild 是在执行生产环境构建前触发的回调函数，你可以通过 bundlerConfigs 参数获取到底层打包工具的最终配置数组：
如果你希望为异步模块指定一个固定的名称，可以通过打包工具提供的 magic comments 来实现，通过 webpackChunkName 指定模块名称：
如果你希望为异步模块指定一个固定的名称，可以通过打包工具提供的 magic comments 来实现，通过 webpackChunkName 指定模块名称：
通过以上写法指定模块名称后，生成的文件会是 dist/static/js/async/my-chunk-name.js。
output.legalComments
- +;
inline：保留所有 legal comments。
示例
+示例
移除所有 legal comments。
output.overrideBrowserslist
- +;
指定项目兼容的目标浏览器范围。该值会被 @babel/preset-env 和 autoprefixer 用来确定需要转换的 JavaScript 语法特性和需要添加的 CSS 浏览器前缀。
+指定项目兼容的目标浏览器范围。该值会被 @babel/preset-env 和 autoprefixer 用来确定需要转换的 JavaScript 语法特性和需要添加的 CSS 浏览器前缀。
优先级
overrideBrowserslist 配置的优先级高于项目中的 .browserslistrc 配置文件和 package.json 中的 browserslist 字段。
大多数场景下，推荐优先使用 .browserslistrc 文件，而不是使用 overrideBrowserslist 配置。因为 .browserslistrc 文件是官方定义的配置文件，通用性更强，可以被社区中的其他库识别。
默认值
+默认值
如果项目中没有定义任何 browserslist 相关的配置，也没有定义 overrideBrowserslist，那么 Builder 会设置默认值为：
示例
+示例
下面是兼容移动端 H5 场景的示例：
可以查看 browserslist 文档 来了解如何自定义浏览器范围。
+}; +可以查看 browserslist 文档 来了解如何自定义浏览器范围。
根据产物类型设置
当你同时构建多种类型的产物时，你可以为不同的产物类型设置不同的目标浏览器范围。此时，你需要把 overrideBrowserslist 设置为一个对象，对象的 key 为对应的产物类型。
比如为 web 和 node 设置不同的范围：
node: ['node >= 14'],
},
},
-};
+};
output.polyfill
-
+
;
usage等价于 @babel/preset-env 的 useBuiltIns: 'usage' 配置。
ua
根据当前请求的 UA 信息，动态下发 Polyfill 代码。
-动态下发能力需要与上层框架结合使用，详情可参考 Modern.js - 运行时按需 Polyfill。
+动态下发能力需要与上层框架结合使用，详情可参考 Modern.js - 运行时按需 Polyfill。
off
不注入 Polyfill。使用此选项时，需要自行保证代码的兼容性。
output.svgDefaultExport
-
+;
当 output.svgDefaultExport 配置为 url 时，SVG 文件的默认导出是文件的 URL。例如：
+console.log(logo); // => 资源 url
当 output.svgDefaultExport 配置为 component 时，SVG 文件的默认导出是文件的 React 组件。例如：
+console.log(Logo); // => React 组件
此时，你也可以通过指定 ?url 的 query 来导入 url，比如：
目录
\ No newline at end of file
+console.log(logo); // => 资源 url目录
\ No newline at end of file
diff --git a/modern-js/builder/api/config-performance.html b/modern-js/builder/api/config-performance.html
index aa3cc36627..e4a614e51a 100644
--- a/modern-js/builder/api/config-performance.html
+++ b/modern-js/builder/api/config-performance.html
@@ -1,4 +1,4 @@
-Performance Config - Modern.js Builder
+Performance Config - Modern.js Builder
-Modern.js Builder Performance Config
+Modern.js Builder Performance Config
本章节描述了 Builder 中与性能有关的配置。
performance.buildCache
-
+;
@@ -26,13 +26,13 @@ */
cacheDigest?: Array<string | undefined>;
}
- | boolean;
+ | boolean;
+};
@@ -45,13 +45,13 @@ cacheDirectory: './node_modules/.custom_cache/webpack',
},
},
-};
+};如果不希望缓存，你也可以将 buildCache 置为 false 将其禁用掉：
+};
cacheDigest
cacheDigest 用来添加一些会对构建结果产生影响的环境变量。Builder 将根据 cacheDigest 内容和当前构建模式来设置缓存名称，来确保不同的 cacheDigest 可以命中不同的缓存。
示例
@@ -70,26 +70,26 @@ 示例 cacheDigest: [process.env.APP_ID],
},
},
-};
+};
performance.bundleAnalyze
-
+;
-用于开启 webpack-bundle-analyzer 插件来分析产物体积。
+用于开启 webpack-bundle-analyzer 插件来分析产物体积。
默认情况下，Builder 不会开启 webpack-bundle-analyzer。当开启该功能后，内部的默认配置如下:
+};
启用 Bundle Analyze
你有两种方式开启 webpack-bundle-analyzer 来分析构建产物的体积:
-
+
@@ -97,9 +97,9 @@
performance: {
bundleAnalyze: {},
},
-};
+};
在启用后，Builder 会生成一个分析构建产物体积的 HTML 文件，并在 Terminal 中打印以下日志：
-
+
手动在浏览器中打开该文件，可以看到打包产物的瓦片图；区块的面积越大，说明该模块的体积越大。
覆盖默认配置
@@ -113,7 +113,7 @@ 覆
}
: {},
},
-};
+};
Size 类型
在 webpack-bundle-analyzer 的面板中，你可以在左上角控制 Size 类型（默认为 Parsed）：
@@ -129,15 +129,21 @@ 生
generateStatsFile: true,
},
},
-};
+};
注意事项
-
performance.chunkSplit
-
+
;
forceSplitting?: ForceSplitting;
}
-export type ChunkSplit = BaseChunkSplit | SplitBySize | SplitCustom;
+export type ChunkSplit = BaseChunkSplit | SplitBySize | SplitCustom;
chunkSplit.strategy
Builder 支持设置以下几种拆包策略：
@@ -206,7 +212,7 @@ chun
minSize: 20000,
},
},
-};
+};
chunkSplit.maxSize
chun
maxSize: 50000,
},
},
-};
+};
chunkSplit.forceSplitting
},
},
},
-};
+};
相比直接配置 webpack 的 splitChunks，这是一个更加简便的方式。
TIP注意，通过 forceSplitting 配置拆分的 chunk 会通过 <script> 标签插入到 HTML 文件中，作为首屏请求的资源。因此，请根据实际场景来进行适当地拆分，避免首屏资源体积过大。
@@ -258,7 +264,7 @@
},
},
},
-};
+};
chunkSplit.override
当 performance.chunkSplit.strategy 为 split-by-experience、split-by-module、split-by-size 或 single-vendor 时，可以通过 performance.chunkSplit.override 配置项来自定义 webpack 拆包配置，此配置会和 webpack 的 splitChunks 配置进行合并（cacheGroups 配置也会合并）。比如:
+};
当 Builder 构建 "node" 类型的产物时，由于 Node Bundles 不需要通过拆包来优化加载性能，因此 chunkSplit 规则不会生效。
performance.dnsPrefetch
-
+;
-为哪些资源配置 dns-prefetch 属性。
+为哪些资源配置 dns-prefetch 属性。
配置该属性可以在请求资源之前解析域名，降低请求延迟，提升加载性能。
-更多信息可参考：Using dns-prefetch
-示例
+更多信息可参考：Using dns-prefetch
+示例
+};
performance.preconnect
-
+;
+}
-为哪些资源配置 preconnect 属性。
+为哪些资源配置 preconnect 属性。
配置该属性会预先建立与服务器的连接，如果站点是 HTTPS 的，则此过程包括 DNS 解析，建立 TCP 连接以及执行 TLS 握手。将 Preconnect 和 DnsPrefetch 结合使用可进一步减少跨域请求的延迟。
-示例
+示例
+};
performance.prefetch
-
+;
@@ -332,17 +338,17 @@ type?: IncludeType;
include?: Filter;
exclude?: Filter;
-}
+}
-
为哪些资源配置 prefetch 属性。
+为哪些资源配置 prefetch 属性。
该属性用于配置在将来某些导航下可能需要的资源，此时，浏览器通常在空闲状态时获取此资源。
Boolean 类型
当设置 performance.prefetch 为 true，将根据如下配置对资源进行预获取:
+}
Object 类型
当 performance.prefetch 的值为 object 类型时，Builder 会根据当前配置对指定资源开启 prefetch 能力。
prefetch.type
@@ -354,7 +360,7 @@ prefetch.type
-示例
+示例
当你希望对当前页面中所有 png 格式的图片资源进行预获取时，可以配置如下：
+};
performance.preload
-
+;
@@ -377,18 +383,18 @@ type?: IncludeType;
include?: Filter;
exclude?: Filter;
-}
+}
-
为哪些资源配置 preload 属性。
+为哪些资源配置 preload 属性。
该属性通常用于配置当前导航下可能需要的资源，此时，浏览器通常以中等优先级（不是布局阻塞）获取此资源。
-Boolean 类型
+Boolean 类型
当设置 performance.preload 为 true，将根据如下配置对资源进行预加载:
-Object 类型
+}
+Object 类型
当 performance.preload 的值为 object 类型时，Builder 会根据当前配置对指定资源开启 preload 能力。
preload.type
type 字段控制了哪些资源会被预加载，同时支持通过 include 和 exclude 对指定资源进行二次过滤。
@@ -399,7 +405,7 @@ preload.typeall-chunks: 预加载所有资源(当前页面)，包含所有异步和非异步资源。
-示例
+示例
当你希望对当前页面中所有 png 格式的图片资源进行预加载时，可以配置如下：
+};
performance.printFileSize
-
+;
dist/static/js/lib-react.09721b5c.js 152.6 kB 49.0 kB
dist/html/main/index.html 5.8 kB 2.5 kB
dist/static/js/main.3568a38e.js 3.5 kB 1.4 kB
- dist/static/css/main.03221f72.css 1.4 kB 741 B
-示例
+ dist/static/css/main.03221f72.css 1.4 kB 741 B
+示例
禁用相关日志：
+};
performance.profile
-
+;
-是否捕获每个模块的耗时信息，对应 webpack / Rspack 的 profile 配置。
-示例
+是否捕获每个模块的耗时信息，对应 webpack / Rspack 的 profile 配置。
+示例
+};
开启后，Webpack / Rspack 生成一些有关模块的统计数据的 JSON 文件会将模块构建的耗时信息也包含进去。
performance.removeConsole
-
+;
移
performance: {
removeConsole: true,
},
-};
+};
移除特定的 console
你也可以指定仅移除特定类型的 console.xx，比如移除 console.log 和 console.warn：
+};
目前支持配置以下类型的 console：
-
+
performance.removeMomentLocale
-
+;
-是否移除 moment.js 的语言包文件。
+是否移除 moment.js 的语言包文件。
moment.js 默认包含了大量的语言包文件，会导致打包后的包体积增大。
当项目中使用了 moment.js 时，推荐开启此选项，自动排除所有的语言包文件：
+};
开启后，可以通过以下方式来加载语言包文件：
+moment.locale('zh-cn');
performance.transformLodash
-
+;
-是否模块化 lodash 的导入，删除未使用的 lodash 模块，从而减少 lodash 代码体积。
-这项优化基于 babel-plugin-lodash 和 swc-plugin-lodash 实现。
-示例
+是否模块化 lodash 的导入，删除未使用的 lodash 模块，从而减少 lodash 代码体积。
+这项优化基于 babel-plugin-lodash 和 swc-plugin-lodash 实现。
+示例
该选项默认开启，Builder 会自动将 lodash 的代码引用指向子路径。
比如：
input.js
+_.map([1, 2, 3], addOne);
转换后的代码为：
output.js
+_map([1, 2, 3], addOne);
关闭转换
在个别情况下，lodash 的 import 转换可能会生成不符合预期的代码，此时你可以手动关闭这项优化：
目录
\ No newline at end of file
+};目录
\ No newline at end of file
diff --git a/modern-js/builder/api/config-security.html b/modern-js/builder/api/config-security.html
index 70f786e165..3272842037 100644
--- a/modern-js/builder/api/config-security.html
+++ b/modern-js/builder/api/config-security.html
@@ -1,4 +1,4 @@
-Security Config - Modern.js Builder
+Security Config - Modern.js Builder
-Modern.js Builder Security Config
+Modern.js Builder Security Config
本章节描述了 Builder 中与安全有关的配置。
security.sri
-
+;
@@ -21,24 +21,24 @@ secu
enabled?: 'auto' | boolean;
hashLoading?: 'eager' | 'lazy';
}
- | boolean;
+ | boolean;
为 HTML 所引入的子资源添加完整性属性 —— integrity，使浏览器能够验证引入资源的完整性，以此防止下载的资源被篡改。
-启动该选项后会将 webpack 的 output.crossOriginLoading 配置项设置为 anonymous。
+启动该选项后会将 webpack 的 output.crossOriginLoading 配置项设置为 anonymous。
SRI 介绍
子资源完整性 Subresource Integrity（SRI）是专门用来校验资源的一种方案，它读取资源标签中的 integrity 属性，将其中的信息摘要值，和资源实际的信息摘要值进行对比，如果发现无法匹配，那么浏览器就会拒绝执行资源。
对于 script 标签来说，结果为拒绝执行其中的代码；对于 CSS link 来说，结果为不加载其中的样式。
-关于 SRI 的更多内容，可以查看 Subresource Integrity - MDN。
+关于 SRI 的更多内容，可以查看 Subresource Integrity - MDN。
示例
默认情况下，不会开启 SRI，当开启之后它的默认配置如下：
+}
你可以按照你自己的需求自定义配置项:
+};
security.checkSyntax
-
+;
@@ -60,7 +60,7 @@ targets?: string[];
exclude?: RegExp | RegExp[];
ecmaVersion?: EcmaVersion;
- };
@@ -71,7 +71,7 @@ 启用检
security: {
checkSyntax: true,
},
-};
+};
当你开启 checkSyntax 后，Builder 会在生产环境构建时进行检测，当在构建产物中检测到不兼容的高级语法后，会将错误日志打印在终端，并退出当前构建流程。
错误日志
错误日志的格式如下所示，包含代码来源文件、产物位置、错误原因、源代码等信息：
@@ -88,7 +88,7 @@ 错误日
> 12 | console.log(() => {
13 | return a + b;
14 | });
- 15 |
+ 15 |
TIP目前语法检测是基于 AST parser 来实现的，每次检测时，只能找出文件中的第一个不兼容语法。如果一个文件中存在多个不兼容语法，你需要修复已发现的语法，并重新执行检测。output.disableMinimize 设置为 true 后再重新构建。
如果日志中没有显示对应的源码位置，可以尝试将
解决方法
@@ -104,7 +104,7 @@ checkSy
-targets 表示项目的目标浏览器范围，它的值为标准的 browserslist 数组，如果你不了解 browserslist 的用法，请参考 「设置浏览器范围」。
+targets 表示项目的目标浏览器范围，它的值为标准的 browserslist 数组，如果你不了解 browserslist 的用法，请参考 「设置浏览器范围」。
Builder 会读取 targets 的值，并自动推导出构建产物中可以使用的最低 ECMAScript 语法版本，比如 ES5 或 ES6。
checkSy
targets: ['chrome >= 53'],
},
},
-};
+};
Builder 会推导出 chrome >= 53 可以使用的 ECMAScript 语法版本为 ES6，当构建产物中包含 es2016 或更高的语法时，就会触发语法错误提示。
TIP请留意，Builder 不支持基于 targets 来自动分析 ES6 以上的语法版本，如果你的构建产物兼容的语法版本超过 ES6，请通过 checkSyntax.ecmaVersion 进行设置。
@@ -136,7 +136,7 @@ che
ecmaVersion: 2020,
},
},
-};
+};
此时，构建产物中可以包含 ES2020 支持的所有语法，比如 optional chaining。
checkSyntax.exclude
@@ -154,4 +154,4 @@ checkSy
exclude: /node_modules\/foo/,
},
},
-};目录
\ No newline at end of file
+};目录
\ No newline at end of file
diff --git a/modern-js/builder/api/config-source.html b/modern-js/builder/api/config-source.html
index 8507013ef3..b8ae4a97bf 100644
--- a/modern-js/builder/api/config-source.html
+++ b/modern-js/builder/api/config-source.html
@@ -1,4 +1,4 @@
-Source Config - Modern.js Builder
+Source Config - Modern.js Builder
-Modern.js Builder Source Config
+Modern.js Builder Source Config
本章节描述了 Builder 中与源代码解析、编译方式相关的配置。
source.alias
-
+;
-设置文件引用的别名，对应 webpack 和 Rspack 的 resolve.alias 配置。
-TIP对于 TypeScript 项目，你只需要在 tsconfig.json 中配置 compilerOptions.paths 即可，Builder 会自动识别它，不需要额外配置 source.alias 字段，详见 「路径别名」。
+
设置文件引用的别名，对应 webpack 和 Rspack 的 resolve.alias 配置。
+TIP对于 TypeScript 项目，你只需要在 tsconfig.json 中配置 compilerOptions.paths 即可，Builder 会自动识别它，不需要额外配置 source.alias 字段，详见 「路径别名」。
Object 类型
alias 的值可以定义为 Object 类型，其中的相对路径会自动被 Builder 转换为绝对路径。
@@ -27,7 +27,7 @@ Object
'@common': './src/common',
},
},
-};
+};
以上配置完成后，如果你在代码中引用 @common/Foo.tsx, 则会映射到 <project>/src/common/Foo.tsx 路径上。
Function 类型
alias 的值定义为函数时，可以接受预设的 alias 对象，并对其进行修改。
@@ -37,7 +37,7 @@ Functi
alias['@common'] = './src/common';
},
},
-};
也可以在函数中返回一个新对象作为最终结果，新对象会覆盖预设的 alias 对象。
+};精确匹配
默认情况，source.alias 会自动匹配子路径，比如以下配置：
+};
它的匹配结果如下：
+import b from '@common/util'; // 解析为 `./src/common/util`
你可以添加 $ 符号来开启精确匹配，开启后将不会自动匹配子路径。
+};
它的匹配结果如下：
+import b from '@common/util'; // 保持 `@common/util` 不变
处理 npm 包
你可以使用 alias 将某个 npm 包指向统一的目录。
比如项目中安装了多份 react，你可以将 react 统一指向根目录的 node_modules 中安装的版本，避免出现打包多份 React 代码的问题。
@@ -86,11 +86,11 @@ 处理
react: path.resolve(__dirname, './node_modules/react'),
},
},
-};
+};
当你在使用 alias 处理 npm 包时，请留意项目中是否使用了这个包不同的 major 版本。
比如你的项目中某个模块或 npm 依赖使用了 React 18 的 API，如果你将 React alias 到 17 版本，就会导致该模块无法引用到 React 18 的 API，导致代码异常。
source.aliasStrategy
-
+;
prefer
"@common/*": ["./src/common-1/*"]
}
}
-}
+}
@@ -119,7 +119,7 @@ prefer
'@utils': './src/utils',
},
},
-};
+};
由于 tsconfig paths 的优先级更高，所以：
prefer-al
source: {
aliasStrategy: 'prefer-alias',
},
-};
+};
比如同时配置以下内容：
prefer-al
"@utils/*": ["./src/utils/*"]
}
}
-}
+}
@@ -153,7 +153,7 @@ prefer-al
'@common': './src/common-2',
},
},
-};
+};
由于 tsconfig paths 只用于提供类型，所以最终只有 @common 别名生效，并指向 ./src/common-2 目录。
大部分情况下你不需要使用 prefer-alias，但当你需要动态生成一些别名配置时，可以考虑使用它。比如，基于环境变量来生成 alias 选项：
+};
source.include
-
+;
-
+];
source.include 用于指定额外需要编译的 JavaScript 文件。
为了避免二次编译，默认情况下，Rsbuild 只会编译当前目录下的 JavaScript 文件，以及所有目录下的 TypeScript 和 JSX 文件，不会编译 node_modules 下的 JavaScript 文件。
-通过 source.include 配置项，可以指定需要 Rsbuild 额外进行编译的目录或模块。source.include 的用法与 Rspack 中的 Rule.include 一致，支持传入字符串、正则表达式来匹配模块的路径。
+通过 source.include 配置项，可以指定需要 Rsbuild 额外进行编译的目录或模块。source.include 的用法与 Rspack 中的 Rule.include 一致，支持传入字符串、正则表达式来匹配模块的路径。
比如:
+};
编译 npm 包
比较典型的使用场景是编译 node_modules 下的 npm 包，因为某些第三方依赖存在 ES6+ 的语法，这可能导致在低版本浏览器上无法运行，你可以通过该选项指定需要编译的依赖，从而解决此类问题。
以 query-string 为例，你可以做如下的配置：
@@ -207,7 +207,7 @@ 编译
/\/node_modules\/query-string\//,
],
},
-};
+};
上述两种方法分别通过 "路径前缀" 和 "正则表达式" 来匹配文件的绝对路径，值得留意的是，项目中所有被引用的模块都会经过匹配，因此你不能使用过于松散的值进行匹配，避免造成编译性能问题或编译异常。
编译 npm 包的子依赖
当你通过 source.include 编译一个 npm 包时，Builder 默认只会编译匹配到的模块，不会编译对应模块的子依赖。
@@ -219,7 +219,7 @@ /\/node_modules\/decode-uri-component\//,
],
},
-};
+};
编译 Monorepo 中的其他库
在 Monorepo 中进行开发时，如果需要引用 Monorepo 中其他库的源代码，也可以直接在 source.include 进行配置:
+};
编译 CommonJS 模块
Babel 默认无法编译 CommonJS 模块，如果你编译了一个 CommonJS 模块，可能会出现 exports is not defined 的运行时报错信息。
当你需要使用 source.include 来编译 CommonJS 模块时，可以将 Babel 的 sourceType 配置设置为 unambiguous：
@@ -247,27 +247,27 @@ config.sourceType = 'unambiguous';
},
},
-};
-
将 sourceType 设置为 unambiguous 可能会产生一些其他影响，请参考 Babel 官方文档。
+};
+将 sourceType 设置为 unambiguous 可能会产生一些其他影响，请参考 Babel 官方文档。
匹配 Symlink
如果你匹配的模块是通过 symlink 链接到当前项目中的，那么需要匹配这个模块的真实路径，而不是 symlink 后的路径。
比如，你将 Monorepo 中的 packages/foo 路径 symlink 到当前项目的 node_modules/foo 路径下，则需要去匹配 packages/foo 路径，而不是 node_modules/foo 路径。
-该行为可以通过 webpack 的 resolve.symlinks 配置项来进行控制。
+该行为可以通过 webpack 的 resolve.symlinks 配置项来进行控制。
注意事项
注意，source.include 不应该被用于编译整个 node_modules 目录，比如下面的写法是错误的：
+};
如果你对整个 node_modules 进行编译，不仅会使编译时间大幅度增加，并且可能会产生不可预期的错误。因为 node_modules 中的大部分 npm 包发布的已经是编译后的产物，通常没必要经过二次编译。此外，core-js 等 npm 包被编译后可能会出现异常。
source.exclude
-
+;
-指定不需要编译的 JavaScript/TypeScript 文件。用法与 webpack 中的 Rule.exclude 一致，支持传入字符串或正则表达式来匹配模块的路径。
+指定不需要编译的 JavaScript/TypeScript 文件。用法与 webpack 中的 Rule.exclude 一致，支持传入字符串或正则表达式来匹配模块的路径。
比如:
+};
source.define
-
+;
sou
-更多细节参考 webpack - DefinePlugin。
-TIP在使用 Rspack 作为打包工具时，支持的类型可参考 Rspack.builtins.define
+
更多细节参考 webpack - DefinePlugin。
+TIP在使用 Rspack 作为打包工具时，支持的类型可参考 Rspack.builtins.define
示例
+};
表达式会被替换为对应的代码段：
+const foo = 1 + 1;
source.globalVars
-
+;
+};
用于在构建时将类似 process.env.FOO 的全局变量表达式替换为指定的值，比如：
-示例
+console.log('development');
+示例
在下方示例中，会在代码中注入 ENABLE_VCONSOLE 和 APP_CONTEXT 两个环境变量：
+};
你可以在代码中直接使用它们：
+console.log(APP_CONTEXT);
函数用法
函数用
+) => Record<string, JSONValue> | void;
你可以将 source.globalVars 设置为一个函数，从而动态设置一些环境变量的值。
比如，根据当前的构建产物类型进行动态设置：
+};
与 define 的区别
source.globalVars 是 source.define 的一个语法糖，它们之间唯一的区别是，source.globalVars 会自动将传入的值进行 JSON 序列化处理，这使得设置全局变量的值更加方便。注意 globalVars 的每个值都需要是可以被 JSON 序列化的值。
-注意事项
+};
+注意事项
source.globalVars 是通过字符串替换的形式来注入环境变量的，因此它无法对「解构赋值」等动态写法生效。
在使用解构赋值时，Builder 将无法判断变量 NODE_ENV 是否与要替换的表达式 process.env.NODE_ENV 存在关联，因此以下使用方式是无效的：
+// ❌ Won't get a string.
source.moduleScopes
-
+;
限制源代码的引用路径。配置该选项后，所有源文件只能从约定的目录下引用代码，从其他目录引用代码会产生对应的报错提示。
-示例
+示例
首先我们配置 moduleScopes 仅包含 src 目录：
+};
然后在 src/App.tsx 中导入 src 目录外部的 utils/a 模块:
-
+
在编译时，会提示引用路径错误:
通过该选项配置 utils 目录，再进行编译，则不会出现错误提示。
@@ -408,15 +408,15 @@ 示例 source: {
moduleScopes: ['./src', './utils'],
},
-};
+};
Array 类型
当 moduleScopes 的值为 Array 类型时，可以直接设置若干个代码路径，比如添加以下配置：
-Function 类型
+};
+Function 类型
moduleScopes 也支持通过函数的形式来进行修改，避免覆盖默认值：
+};
source.transformImport
-
-用于按需引入组件库的代码和样式，能力等价于 babel-plugin-import。
-它与 babel-plugin-import 的区别在于，source.transformImport 不与 Babel 耦合。Builder 会自动识别当前使用的编译工具是 Babel、SWC 还是 Rspack，并添加相应的按需引入配置。
+;
+用于按需引入组件库的代码和样式，能力等价于 babel-plugin-import。
+它与 babel-plugin-import 的区别在于，source.transformImport 不与 Babel 耦合。Builder 会自动识别当前使用的编译工具是 Babel、SWC 还是 Rspack，并添加相应的按需引入配置。
@@ -443,17 +443,17 @@ transformToDefaultImport?: boolean;
customName?: ((member: string) => string | undefined) | string;
customStyleName?: ((member: string) => string | undefined) | string;
- }>;
+ }>;
-
当项目中安装了 Ant Design 组件库 <= 4.x 版本时，Builder 会自动添加以下默认配置：
+当项目中安装了 Ant Design 组件库 <= 4.x 版本时，Builder 会自动添加以下默认配置：
-当项目中安装了 Arco Design 组件库 时，Builder 会自动添加以下默认配置：
+};
+当项目中安装了 Arco Design 组件库 时，Builder 会自动添加以下默认配置：
+];
TIP当你添加了 antd 或 @arco-design/web-react 相关的配置时，优先级会高于上述默认配置。
-示例
+示例
当使用上述 antd 默认配置：
+};
源代码如下：
-
+
会被转换成：
+import 'antd/es/button/style';
禁用默认配置
你可以手动设置 transformImport: false 来关掉 transformImport 的默认行为。
+};
比如，当你使用了 externals 来避免打包 antd 时，由于 transformImport 默认会转换 antd 的引用路径，导致匹配的路径发生了变化，因此 externals 无法正确生效，此时你可以设置关闭 transformImport 来避免该问题。
配置
libraryName
@@ -508,9 +508,9 @@ libraryDi
用于拼接转换后的路径，拼接规则为 ${libraryName}/${libraryDirectory}/${member}，其中 member 为引入成员。
示例：
-
+
转换结果:
-
+
style
style确定是否需要引入相关样式，若为 true，则会引入路径 ${libraryName}/${libraryDirectory}/${member}/style。
若为 false 或 undefined 则不会引入样式。
当配置为 true 时：
-
+
转换结果:
+import 'foo/lib/button/style';
styleLibraryDirectory
styl
该配置用于拼接引入样式时的引入路径，若该配置被指定，则 style 配置项会被忽略。拼接引入路径为 ${libraryName}/${styleLibraryDirectory}/${member}。
当配置为 styles 时：
-
+
转换结果:
+import 'foo/styles/button';
camelToDashComponentName
c
是否需要将 camelCase 的引入转换成 kebab-case。
示例：
-
+
转换结果：
+import ButtonGroup from 'foo/ButtonGroup';
transformToDefaultImport
t
是否将导入语句转换成默认导入。
示例：
-
+
转换结果：
+import { Button } from 'foo/button';
customName
customName
自定义转换后的导入路径，输入是引入的成员，例如配置成 (member) => `my-lib/${member}` ，会将 import { foo } from 'bar' 转换成 import foo from 'my-lib/foo'。
-在使用 Rspack 构建时，不能使用函数配置，但可以使用 handlebars 模版字符串，对于上面的函数配置，在使用模版字符串时可以用以下模版代替 my-lib/{{ member }}，也可以使用一些内置帮助方法，例如 my-lib/{{ kebabCase member }} 来转换成 kebab-case 格式，除了 kebabCase 以外还有 camelCase，snakeCase，upperCase，lowerCase 可以使用。
+在使用 Rspack 构建时，不能使用函数配置，但可以使用 handlebars 模版字符串，对于上面的函数配置，在使用模版字符串时可以用以下模版代替 my-lib/{{ member }}，也可以使用一些内置帮助方法，例如 my-lib/{{ kebabCase member }} 来转换成 kebab-case 格式，除了 kebabCase 以外还有 camelCase，snakeCase，upperCase，lowerCase 可以使用。
customStyleName
customStyl
自定义转换后的样式导入路径，输入是引入的成员，例如配置成 (member) => `my-lib/${member}` ，会将 import { foo } from 'bar' 转换成 import foo from 'my-lib/foo'。
-在使用 Rspack 构建时，不能使用函数配置，但可以使用 handlebars 模版字符串，对于上面的函数配置，在使用模版字符串时可以用以下模版代替 my-lib/{{ member }}，也可以使用一些内置帮助方法，例如 my-lib/{{ kebabCase member }} 来转换成 kebab-case 格式，除了 kebabCase 以外还有 camelCase，snakeCase，upperCase，lowerCase 可以使用。
+在使用 Rspack 构建时，不能使用函数配置，但可以使用 handlebars 模版字符串，对于上面的函数配置，在使用模版字符串时可以用以下模版代替 my-lib/{{ member }}，也可以使用一些内置帮助方法，例如 my-lib/{{ kebabCase member }} 来转换成 kebab-case 格式，除了 kebabCase 以外还有 camelCase，snakeCase，upperCase，lowerCase 可以使用。
source.preEntry
-
+;
s
在每个页面的入口文件前添加一段代码，这段代码会早于页面的代码执行，因此可以用于执行一些全局的代码逻辑，比如注入 polyfill、设置全局样式等。
添加单个脚本
首先创建一个 src/polyfill.ts 文件：
-
+
然后将 src/polyfill.ts 配置到 source.preEntry 上：
+};
重新运行编译并访问任意页面，可以看到 src/polyfill.ts 中的代码已经执行，并在 console 中输出了对应的内容。
添加全局样式
你也可以通过 source.preEntry 来配置全局样式，这段 CSS 代码会早于页面代码加载，比如引入一个 normalize.css 文件：
@@ -609,35 +609,35 @@ 添加
source: {
preEntry: './src/normalize.css',
},
-};
+};
添加多个脚本
你可以将 preEntry 设置为数组来添加多个脚本，它们会按数组顺序执行：
+};
source.resolveExtensionPrefix
-
+;
-用于为 resolve.extensions 添加统一的前缀。
+用于为 resolve.extensions 添加统一的前缀。
如果多个文件拥有相同的名称，但具有不同的文件后缀，Builder 会根据 extensions 数组的顺序进行识别，解析数组中第一个被识别的文件，并跳过其余文件。
-示例
+示例
下面是配置 .web 前缀的例子。
+};
配置完成后，extensions 数组会发生以下变化：
+const extensions = ['.web.js', '.js', '.web.ts' , '.ts', ...];
在代码中 import './foo' 时，会优先识别 foo.web.js 文件，再识别 foo.js 文件。
根据产物类型设置
当你同时构建多种类型的产物时，你可以为不同的产物类型设置不同的 extension 前缀。此时，你需要把 resolveExtensionPrefix 设置为一个对象，对象的 key 为对应的产物类型。
@@ -651,27 +651,27 @@
},
},
},
-};
+};
在代码中 import './foo' 时，对于 node 产物，会优先识别 foo.node.js 文件，而对于 web 产物，则会优先识别 foo.web.js 文件。
source.resolveMainFields
-
+;
+type ResolveMainFields = Fields | Record<BuilderTarget, Fields>;
-该配置项将决定你使用 package.json 哪个字段导入 npm 模块。对应 webpack 的 resolve.mainFields 配置。
-示例
+该配置项将决定你使用 package.json 哪个字段导入 npm 模块。对应 webpack 的 resolve.mainFields 配置。
+示例
-根据产物类型设置
+};
+根据产物类型设置
当你同时构建多种类型的产物时，你可以为不同的产物类型设置不同的 mainFields。此时，你需要把 resolveMainFields 设置为一个对象，对象的 key 为对应的产物类型。
比如为 web 和 node 设置不同的 mainFields：
目录
\ No newline at end of file
+};目录
\ No newline at end of file
diff --git a/modern-js/builder/api/config-tools.html b/modern-js/builder/api/config-tools.html
index 0b8c0a1b35..8c24531319 100644
--- a/modern-js/builder/api/config-tools.html
+++ b/modern-js/builder/api/config-tools.html
@@ -1,4 +1,4 @@
-Tools Config - Modern.js Builder
+Tools Config - Modern.js Builder
-Modern.js Builder Tools Config
+Modern.js Builder Tools Config
本章节描述了 Builder 中与底层工具有关的配置。
tools.autoprefixer
-
+;
// browserslist 取决于项目中的 browserslist 配置
// 以及 `output.overrideBrowserslist`(优先级更高) 配置
overrideBrowserslist: browserslist,
-}
-通过 tools.autoprefixer 可以修改 autoprefixer 的配置。
+}通过 tools.autoprefixer 可以修改 autoprefixer 的配置。
Object 类型
当 tools.autoprefixer 的值为 Object 类型时，会与默认配置通过 Object.assign 合并。比如：
+};
Function 类型
当 tools.autoprefixer 为 Function 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果。比如：
+};
tools.babel
-
+;
-通过 tools.babel 可以修改 babel-loader 的配置项。
+通过 tools.babel 可以修改 babel-loader 的配置项。
使用场景
请留意 tools.babel 在以下使用场景中的局限性：
-Function 类型
+Function 类型
当 tools.babel 为 Function 类型时，默认 Babel 配置会作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终的 babel-loader 配置。
+};tools.babel 函数的第二个参数提供了一些方便的工具函数，请继续阅读下方文档。
TIP以上示例仅作为参考，通常来说，你不需要手动配置 babel-plugin-import，因为 Builder 已经提供了更通用的 source.transformImport 配置。
-Object 类型
+Object 类型
当 tools.babel 的值为 Object 类型时，会与默认配置通过 Object.assign 浅合并。
CAUTIONObject.assign 是浅拷贝，会完全覆盖内置的 presets 或 plugins 数组，导致内置的 presets 或 plugins 失效，请在明确影响面的情况下再使用这种方式。
@@ -94,7 +94,7 @@ Object
],
},
},
-};
+};
工具函数
tools.babel 为 Function 类型时，第二个参数可用的工具函数如下:
addPlugins
@@ -117,7 +117,7 @@ addPlugins ]);
},
},
-};
+};
addPresets
addPresets addPresets(['@babel/preset-env']);
},
},
-};
+};
removePlugins
removePlugin
removePlugins('babel-plugin-import');
},
},
-};
+};
removePresets
removePreset
removePresets('@babel/preset-env');
},
},
-};
+};
modifyPresetEnvOptions
-
修改 @babel/preset-env 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+修改 @babel/preset-env 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+};
modifyPresetReactOptions
-修改 @babel/preset-react 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+修改 @babel/preset-react 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+};
addIncludes
-已废弃，请使用 source.include 代替，两者功能完全一致。
+已废弃，请使用 source.include 代替，两者功能完全一致。
addExcludes
-已废弃，请使用 source.exclude 代替，两者功能完全一致。
+已废弃，请使用 source.exclude 代替，两者功能完全一致。
调试 Babel 配置
-当你通过 tools.babel 修改 babel-loader 配置后，可以在 Builder 调试模式 下查看最终生成的配置。
+当你通过 tools.babel 修改 babel-loader 配置后，可以在 Builder 调试模式 下查看最终生成的配置。
首先通过 DEBUG=builder 参数开启调试模式：
+DEBUG=builder pnpm build
然后打开生成的 (webpack|rspack).config.web.js，搜索 babel-loader 关键词，即可看到完整的 babel-loader 配置内容。
tools.bundlerChain
-
+;
什么是 BundlerChain
Bundler chain 是 webpack chain 的子集，其中包含一部分 webpack chain API，你可以用它来同时修改 webpack 和 Rspack 的配置。
-通过 bundler chain 修改的配置，在 webpack 和 Rspack 构建时均可生效。需要注意的是，bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如，修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同)，或添加一个Rspack 兼容的 webpack 插件。
+通过 bundler chain 修改的配置，在 webpack 和 Rspack 构建时均可生效。需要注意的是，bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如，修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同)，或添加一个Rspack 兼容的 webpack 插件。
tools.bundlerChain 的执行时机早于 tools.webpackChain / tools.webpack / tools.rspack，因此会被其他几个配置中的修改所覆盖。
-工具集合
-env
-
-
-
通过 env 参数可以判断当前环境为 development、production 还是 test。比如：
-
-isProd
-
-
-通过 isProd 参数可以判断当前环境是否为 production。比如：
-
-target
-
-
-通过 target 参数可以判断当前构建的目标运行时环境。比如：
-
-isServer
-
-
-判断当前构建的目标运行时环境是否为 node，等价于 target === 'node'。
-
-isWebWorker
-
-
-判断当前构建的目标运行时环境是否为 web-worker，等价于 target === 'web-worker'。
-
-HtmlPlugin
-
-
-通过这个参数你可以拿到 webpack 或 Rspack 中的 HtmlPlugin 实例。
-
-CHAIN_ID
-Builder 中预先定义了一些常用的 Chain ID，你可以通过这些 ID 来定位到内置的 Rule 或 Plugin。
-TIP请留意，下列的一部分 Rule 或 Plugin 并不是默认存在的，当你开启特定配置项、或是注册某些插件后，它们才会被包含在 Rspack 或 webpack 配置中。
-比如，RULE.STYLUS 仅在注册了 Stylus 插件后才会存在。
-
-CHAIN_ID.RULE
-
-
-
-ID
-描述
-
-
-
-
-RULE.MJS处理 mjs 的规则
-
-
-RULE.CSS处理 css 的规则
-
-
-RULE.LESS处理 less 的规则
-
-
-RULE.SASS处理 sass 的规则
-
-
-RULE.STYLUS处理 stylus 的规则
-
-
-RULE.TOML处理 toml 的规则
-
-
-RULE.YAML处理 yaml 的规则
-
-
-RULE.WASM处理 wasm 的规则
-
-
-RULE.NODE处理 node 的规则
-
-
-
-CHAIN_ID.ONE_OF
-通过 ONE_OF.XXX 可以匹配到规则数组中的某一类规则。
-
-
-
-ID
-描述
-
-
-
-
-ONE_OF.SVG处理 SVG 的规则，在 data URI 和单独文件之间自动选择
-
-
-ONE_OF.SVG_URL处理 SVG 的规则，输出为单独文件
-
-
-ONE_OF.SVG_INLINE处理 SVG 的规则，作为 data URI 内联到 bundle 中
-
-
-ONE_OF.SVG_ASSETS处理 SVG 的规则，在 data URI 和单独文件之间自动选择
-
-
-
-CHAIN_ID.USE
-通过 USE.XXX 可以匹配到对应的 loader。
-
-
-
-ID
-描述
-
-
-
-
-USE.LESS对应 less-loader
-
-
-USE.SASS对应 sass-loader
-
-
-USE.STYLUS对应 stylus-loader
-
-
-USE.VUE对应 vue-loader
-
-
-USE.TOML对应 toml-loader
-
-
-USE.YAML对应 yaml-loader
-
-
-USE.NODE对应 node-loader
-
-
-USE.SVGR对应 @svgr/webpack
-
-
-USE.POSTCSS对应 postcss-loader
-
-
-USE.RESOLVE_URL_LOADER_FOR_SASS对应 resolve-url-loader
-
-
-
-CHAIN_ID.PLUGIN
-通过 PLUGIN.XXX 可以匹配到对应的 plugin。
-
-
-
-ID
-描述
-
-
-
-
-PLUGIN.HTML对应 HtmlPlugin，使用时需要拼接 entry 名称：${PLUGIN.HTML}-${entryName}
-
-
-PLUGIN.APP_ICON对应 AppIconPlugin
-
-
-PLUGIN.INLINE_HTML对应 InlineChunkHtmlPlugin
-
-
-PLUGIN.BUNDLE_ANALYZER对应 WebpackBundleAnalyzer
-
-
-PLUGIN.ASSETS_RETRY对应 Builder 中的 webpack 静态资源重试插件 WebpackAssetsRetryPlugin
-
-
-PLUGIN.VUE_LOADER_PLUGIN对应 VueLoaderPlugin
-
-
-PLUGIN.AUTO_SET_ROOT_SIZE对应 Builder 中的自动设置根字体大小插件 AutoSetRootSizePlugin
-
-
-
-CHAIN_ID.MINIMIZER
-通过 MINIMIZER.XXX 可以匹配到对应的压缩工具。
-
-
-
-ID
-描述
-
-
-
-
-MINIMIZER.JS对应 TerserWebpackPlugin 或 SwcJsMinimizerRspackPlugin
-
-
-MINIMIZER.CSS对应 CssMinimizerWebpackPlugin
-
-
-
-使用示例
-使用示例可参考：WebpackChain 使用示例。
+更多信息可参考 Rsbuild#tools.bundlerChain
tools.cssExtract
-
+;
chunkFilename: `${cssPath}/async/${cssFilename}`,
ignoreOrder: true,
},
-};
+};
-
通过 tools.cssExtract 可以更改 mini-css-extract-plugin 的配置。
-Object 类型
+通过 tools.cssExtract 可以更改 mini-css-extract-plugin 的配置。
+Object 类型
当此值为 Object 类型时，与默认配置通过 Object.assign 合并。比如：
-Function 类型
+};
+Function 类型
当此值为 Function 类型时，默认配置作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终配置。比如：
-更多配置细节可参考 mini-css-extract-plugin。
+};
+更多配置细节可参考 mini-css-extract-plugin。
tools.cssLoader
-
+;
-通过 tools.cssLoader 可以修改 css-loader 的配置项。默认配置如下:
+通过 tools.cssLoader 可以修改 css-loader 的配置项。默认配置如下:
-TIP在使用 Rspack 作为打包工具时，仅支持在 disableCssExtract 时使用该配置。
-修改 CSS Modules 相关配置，推荐使用 output.cssModules 配置项。
+}
+TIP在使用 Rspack 作为打包工具时，仅支持在 disableCssExtract 时使用该配置。
+修改 CSS Modules 相关配置，推荐使用 output.cssModules 配置项。
-Object 类型
+Object 类型
当此值为 Object 类型时，会与默认配置进行深层合并 (deep merge)。比如：
-Function 类型
+};
+Function 类型
当此值为 Function 类型时，默认配置作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终配置。比如：
+};
tools.devServer
-
+;
通过 tools.devServer 可以修改开发环境服务器的配置。
-TIPModern.js 中并没有直接使用 webpack-dev-server 或 @rspack/dev-server, 而是基于 webpack-dev-middleware 实现 DevServer。
+
TIPModern.js 中并没有直接使用 webpack-dev-server 或 @rspack/dev-server, 而是基于 webpack-dev-middleware 实现 DevServer。
选项
after
@@ -607,7 +331,7 @@ after ],
},
},
-};
+};
webpack-dev-server 使用 Express 作为服务端框架。Modern.js 中没有使用任何框架，上述中间件中 req 和 res 都是 Node 原生对象，因此 webpack-dev-server 的 Express 中间件不一定能直接在 Modern.js 中使用。
如果要迁移 webpack-dev-server 中使用的 Express 中间件，可以使用以下方式，将 Express app 作为中间件传入：
+};
before
before ],
},
},
-};
+};
client
client port?: string;
/** 指定要使用的 host */
host?: string;
-}
+}
@@ -667,7 +391,7 @@ client host: '',
// By default it is set to "location.protocol === 'https:' ? 'wss' : 'ws'""
protocol: '',
-};
+};
对应 HMR 客户端的配置，通常用于设置 HMR 对应的 WebSocket URL。
compress
@@ -682,21 +406,21 @@ compress compress: false,
},
},
-};
+};
devMiddleware
+}
-devMiddleware 配置项。当前配置是 webpack-dev-middleware 配置项的子集.
+}
+devMiddleware 配置项。当前配置是 webpack-dev-middleware 配置项的子集.
headers
headers },
},
},
-};
+};
historyApiFallback
history
historyApiFallback: true,
},
},
-};
-
更多选项和详细信息可参考 connect-history-api-fallback 文档。
+};
+更多选项和详细信息可参考 connect-history-api-fallback 文档。
hot
-是否开启 Hot Module Replacement 热更新能力。
+是否开启 Hot Module Replacement 热更新能力。
https
https },
},
},
-};
+};
liveReload
setupMidd
) => void;
},
) => void
->;
+>;
@@ -794,7 +518,7 @@ setupMidd
],
},
},
-};
+};
一些特殊场景需求可能需要使用服务器 API：
setupMidd
],
},
},
-};
+};
proxy
proxy },
},
},
-};
-此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
+};
+此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
如果你不想传递 /api，可以通过 pathRewrite 重写请求路径：
-DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
+};
+DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
DevServer Proxy 完整类型定义为：
+ | ProxyDetail;
除了 http-proxy-middleware 的选项外，还支持 bypass 和 context 两个配置项：
当 output.svgDefaultExport 配置为 url 时，SVG 文件的默认导出是文件的 URL。例如：
+console.log(logo); // => 资源 url
当 output.svgDefaultExport 配置为 component 时，SVG 文件的默认导出是文件的 React 组件。例如：
此时，你也可以通过指定 ?url 的 query 来导入 url，比如：
Performance Config
+Performance Config
本章节描述了 Builder 中与性能有关的配置。
performance.buildCache
- +;
*/ cacheDigest?: Array<string | undefined>; } - | boolean;
cacheDirectory: './node_modules/.custom_cache/webpack', }, }, -};
如果不希望缓存，你也可以将 buildCache 置为 false 将其禁用掉：
cacheDigest
cacheDigest 用来添加一些会对构建结果产生影响的环境变量。Builder 将根据 cacheDigest 内容和当前构建模式来设置缓存名称，来确保不同的 cacheDigest 可以命中不同的缓存。
示例
@@ -70,26 +70,26 @@示例 cacheDigest: [process.env.APP_ID],
},
},
-};
+};
performance.bundleAnalyze
-
+;
-用于开启 webpack-bundle-analyzer 插件来分析产物体积。
+用于开启 webpack-bundle-analyzer 插件来分析产物体积。
默认情况下，Builder 不会开启 webpack-bundle-analyzer。当开启该功能后，内部的默认配置如下:
+};
启用 Bundle Analyze
你有两种方式开启 webpack-bundle-analyzer 来分析构建产物的体积:
-
+
@@ -97,9 +97,9 @@
performance: {
bundleAnalyze: {},
},
-};
+};
在启用后，Builder 会生成一个分析构建产物体积的 HTML 文件，并在 Terminal 中打印以下日志：
-
+
手动在浏览器中打开该文件，可以看到打包产物的瓦片图；区块的面积越大，说明该模块的体积越大。
覆盖默认配置
@@ -113,7 +113,7 @@ 覆
}
: {},
},
-};
+};
Size 类型
在 webpack-bundle-analyzer 的面板中，你可以在左上角控制 Size 类型（默认为 Parsed）：
@@ -129,15 +129,21 @@ 生
generateStatsFile: true,
},
},
-};
+};
注意事项
-
performance.chunkSplit
-
+
;
forceSplitting?: ForceSplitting;
}
-export type ChunkSplit = BaseChunkSplit | SplitBySize | SplitCustom;
+export type ChunkSplit = BaseChunkSplit | SplitBySize | SplitCustom;
chunkSplit.strategy
Builder 支持设置以下几种拆包策略：
@@ -206,7 +212,7 @@ chun
minSize: 20000,
},
},
-};
+};
chunkSplit.maxSize
chun
maxSize: 50000,
},
},
-};
+};
chunkSplit.forceSplitting
},
},
},
-};
+};
相比直接配置 webpack 的 splitChunks，这是一个更加简便的方式。
TIP注意，通过 forceSplitting 配置拆分的 chunk 会通过 <script> 标签插入到 HTML 文件中，作为首屏请求的资源。因此，请根据实际场景来进行适当地拆分，避免首屏资源体积过大。
@@ -258,7 +264,7 @@
},
},
},
-};
+};
chunkSplit.override
当 performance.chunkSplit.strategy 为 split-by-experience、split-by-module、split-by-size 或 single-vendor 时，可以通过 performance.chunkSplit.override 配置项来自定义 webpack 拆包配置，此配置会和 webpack 的 splitChunks 配置进行合并（cacheGroups 配置也会合并）。比如:
+};
当 Builder 构建 "node" 类型的产物时，由于 Node Bundles 不需要通过拆包来优化加载性能，因此 chunkSplit 规则不会生效。
performance.dnsPrefetch
-
+;
-为哪些资源配置 dns-prefetch 属性。
+为哪些资源配置 dns-prefetch 属性。
配置该属性可以在请求资源之前解析域名，降低请求延迟，提升加载性能。
-更多信息可参考：Using dns-prefetch
-示例
+更多信息可参考：Using dns-prefetch
+示例
+};
performance.preconnect
-
+;
+}
-为哪些资源配置 preconnect 属性。
+为哪些资源配置 preconnect 属性。
配置该属性会预先建立与服务器的连接，如果站点是 HTTPS 的，则此过程包括 DNS 解析，建立 TCP 连接以及执行 TLS 握手。将 Preconnect 和 DnsPrefetch 结合使用可进一步减少跨域请求的延迟。
-示例
+示例
+};
performance.prefetch
-
+;
@@ -332,17 +338,17 @@ type?: IncludeType;
include?: Filter;
exclude?: Filter;
-}
+}
-
为哪些资源配置 prefetch 属性。
+为哪些资源配置 prefetch 属性。
该属性用于配置在将来某些导航下可能需要的资源，此时，浏览器通常在空闲状态时获取此资源。
Boolean 类型
当设置 performance.prefetch 为 true，将根据如下配置对资源进行预获取:
+}
Object 类型
当 performance.prefetch 的值为 object 类型时，Builder 会根据当前配置对指定资源开启 prefetch 能力。
prefetch.type
@@ -354,7 +360,7 @@ prefetch.type
-示例
+示例
当你希望对当前页面中所有 png 格式的图片资源进行预获取时，可以配置如下：
+};
performance.preload
-
+;
@@ -377,18 +383,18 @@ type?: IncludeType;
include?: Filter;
exclude?: Filter;
-}
+}
-
为哪些资源配置 preload 属性。
+为哪些资源配置 preload 属性。
该属性通常用于配置当前导航下可能需要的资源，此时，浏览器通常以中等优先级（不是布局阻塞）获取此资源。
-Boolean 类型
+Boolean 类型
当设置 performance.preload 为 true，将根据如下配置对资源进行预加载:
-Object 类型
+}
+Object 类型
当 performance.preload 的值为 object 类型时，Builder 会根据当前配置对指定资源开启 preload 能力。
preload.type
type 字段控制了哪些资源会被预加载，同时支持通过 include 和 exclude 对指定资源进行二次过滤。
@@ -399,7 +405,7 @@ preload.typeall-chunks: 预加载所有资源(当前页面)，包含所有异步和非异步资源。
-示例
+示例
当你希望对当前页面中所有 png 格式的图片资源进行预加载时，可以配置如下：
+};
performance.printFileSize
-
+;
dist/static/js/lib-react.09721b5c.js 152.6 kB 49.0 kB
dist/html/main/index.html 5.8 kB 2.5 kB
dist/static/js/main.3568a38e.js 3.5 kB 1.4 kB
- dist/static/css/main.03221f72.css 1.4 kB 741 B
-示例
+ dist/static/css/main.03221f72.css 1.4 kB 741 B
+示例
禁用相关日志：
+};
performance.profile
-
+;
-是否捕获每个模块的耗时信息，对应 webpack / Rspack 的 profile 配置。
-示例
+是否捕获每个模块的耗时信息，对应 webpack / Rspack 的 profile 配置。
+示例
+};
开启后，Webpack / Rspack 生成一些有关模块的统计数据的 JSON 文件会将模块构建的耗时信息也包含进去。
performance.removeConsole
-
+;
移
performance: {
removeConsole: true,
},
-};
+};
移除特定的 console
你也可以指定仅移除特定类型的 console.xx，比如移除 console.log 和 console.warn：
+};
目前支持配置以下类型的 console：
-
+
performance.removeMomentLocale
-
+;
-是否移除 moment.js 的语言包文件。
+是否移除 moment.js 的语言包文件。
moment.js 默认包含了大量的语言包文件，会导致打包后的包体积增大。
当项目中使用了 moment.js 时，推荐开启此选项，自动排除所有的语言包文件：
+};
开启后，可以通过以下方式来加载语言包文件：
+moment.locale('zh-cn');
performance.transformLodash
-
+;
-是否模块化 lodash 的导入，删除未使用的 lodash 模块，从而减少 lodash 代码体积。
-这项优化基于 babel-plugin-lodash 和 swc-plugin-lodash 实现。
-示例
+是否模块化 lodash 的导入，删除未使用的 lodash 模块，从而减少 lodash 代码体积。
+这项优化基于 babel-plugin-lodash 和 swc-plugin-lodash 实现。
+示例
该选项默认开启，Builder 会自动将 lodash 的代码引用指向子路径。
比如：
input.js
+_.map([1, 2, 3], addOne);
转换后的代码为：
output.js
+_map([1, 2, 3], addOne);
关闭转换
在个别情况下，lodash 的 import 转换可能会生成不符合预期的代码，此时你可以手动关闭这项优化：
目录
\ No newline at end of file
+};目录
\ No newline at end of file
diff --git a/modern-js/builder/api/config-security.html b/modern-js/builder/api/config-security.html
index 70f786e165..3272842037 100644
--- a/modern-js/builder/api/config-security.html
+++ b/modern-js/builder/api/config-security.html
@@ -1,4 +1,4 @@
-Security Config - Modern.js Builder
+Security Config - Modern.js Builder
-Modern.js Builder Security Config
+Modern.js Builder Security Config
本章节描述了 Builder 中与安全有关的配置。
security.sri
-
+;
@@ -21,24 +21,24 @@ secu
enabled?: 'auto' | boolean;
hashLoading?: 'eager' | 'lazy';
}
- | boolean;
+ | boolean;
为 HTML 所引入的子资源添加完整性属性 —— integrity，使浏览器能够验证引入资源的完整性，以此防止下载的资源被篡改。
-启动该选项后会将 webpack 的 output.crossOriginLoading 配置项设置为 anonymous。
+启动该选项后会将 webpack 的 output.crossOriginLoading 配置项设置为 anonymous。
SRI 介绍
子资源完整性 Subresource Integrity（SRI）是专门用来校验资源的一种方案，它读取资源标签中的 integrity 属性，将其中的信息摘要值，和资源实际的信息摘要值进行对比，如果发现无法匹配，那么浏览器就会拒绝执行资源。
对于 script 标签来说，结果为拒绝执行其中的代码；对于 CSS link 来说，结果为不加载其中的样式。
-关于 SRI 的更多内容，可以查看 Subresource Integrity - MDN。
+关于 SRI 的更多内容，可以查看 Subresource Integrity - MDN。
示例
默认情况下，不会开启 SRI，当开启之后它的默认配置如下：
+}
你可以按照你自己的需求自定义配置项:
+};
security.checkSyntax
-
+;
@@ -60,7 +60,7 @@ targets?: string[];
exclude?: RegExp | RegExp[];
ecmaVersion?: EcmaVersion;
- };
@@ -71,7 +71,7 @@ 启用检
security: {
checkSyntax: true,
},
-};
+};
当你开启 checkSyntax 后，Builder 会在生产环境构建时进行检测，当在构建产物中检测到不兼容的高级语法后，会将错误日志打印在终端，并退出当前构建流程。
错误日志
错误日志的格式如下所示，包含代码来源文件、产物位置、错误原因、源代码等信息：
@@ -88,7 +88,7 @@ 错误日
> 12 | console.log(() => {
13 | return a + b;
14 | });
- 15 |
+ 15 |
TIP目前语法检测是基于 AST parser 来实现的，每次检测时，只能找出文件中的第一个不兼容语法。如果一个文件中存在多个不兼容语法，你需要修复已发现的语法，并重新执行检测。output.disableMinimize 设置为 true 后再重新构建。
如果日志中没有显示对应的源码位置，可以尝试将
解决方法
@@ -104,7 +104,7 @@ checkSy
-targets 表示项目的目标浏览器范围，它的值为标准的 browserslist 数组，如果你不了解 browserslist 的用法，请参考 「设置浏览器范围」。
+targets 表示项目的目标浏览器范围，它的值为标准的 browserslist 数组，如果你不了解 browserslist 的用法，请参考 「设置浏览器范围」。
Builder 会读取 targets 的值，并自动推导出构建产物中可以使用的最低 ECMAScript 语法版本，比如 ES5 或 ES6。
checkSy
targets: ['chrome >= 53'],
},
},
-};
+};
Builder 会推导出 chrome >= 53 可以使用的 ECMAScript 语法版本为 ES6，当构建产物中包含 es2016 或更高的语法时，就会触发语法错误提示。
TIP请留意，Builder 不支持基于 targets 来自动分析 ES6 以上的语法版本，如果你的构建产物兼容的语法版本超过 ES6，请通过 checkSyntax.ecmaVersion 进行设置。
@@ -136,7 +136,7 @@ che
ecmaVersion: 2020,
},
},
-};
+};
此时，构建产物中可以包含 ES2020 支持的所有语法，比如 optional chaining。
checkSyntax.exclude
@@ -154,4 +154,4 @@ checkSy
exclude: /node_modules\/foo/,
},
},
-};目录
\ No newline at end of file
+};目录
\ No newline at end of file
diff --git a/modern-js/builder/api/config-source.html b/modern-js/builder/api/config-source.html
index 8507013ef3..b8ae4a97bf 100644
--- a/modern-js/builder/api/config-source.html
+++ b/modern-js/builder/api/config-source.html
@@ -1,4 +1,4 @@
-Source Config - Modern.js Builder
+Source Config - Modern.js Builder
-Modern.js Builder Source Config
+Modern.js Builder Source Config
本章节描述了 Builder 中与源代码解析、编译方式相关的配置。
source.alias
-
+;
-设置文件引用的别名，对应 webpack 和 Rspack 的 resolve.alias 配置。
-TIP对于 TypeScript 项目，你只需要在 tsconfig.json 中配置 compilerOptions.paths 即可，Builder 会自动识别它，不需要额外配置 source.alias 字段，详见 「路径别名」。
+
设置文件引用的别名，对应 webpack 和 Rspack 的 resolve.alias 配置。
+TIP对于 TypeScript 项目，你只需要在 tsconfig.json 中配置 compilerOptions.paths 即可，Builder 会自动识别它，不需要额外配置 source.alias 字段，详见 「路径别名」。
Object 类型
alias 的值可以定义为 Object 类型，其中的相对路径会自动被 Builder 转换为绝对路径。
@@ -27,7 +27,7 @@ Object
'@common': './src/common',
},
},
-};
+};
以上配置完成后，如果你在代码中引用 @common/Foo.tsx, 则会映射到 <project>/src/common/Foo.tsx 路径上。
Function 类型
alias 的值定义为函数时，可以接受预设的 alias 对象，并对其进行修改。
@@ -37,7 +37,7 @@ Functi
alias['@common'] = './src/common';
},
},
-};
也可以在函数中返回一个新对象作为最终结果，新对象会覆盖预设的 alias 对象。
+};精确匹配
默认情况，source.alias 会自动匹配子路径，比如以下配置：
+};
它的匹配结果如下：
+import b from '@common/util'; // 解析为 `./src/common/util`
你可以添加 $ 符号来开启精确匹配，开启后将不会自动匹配子路径。
+};
它的匹配结果如下：
+import b from '@common/util'; // 保持 `@common/util` 不变
处理 npm 包
你可以使用 alias 将某个 npm 包指向统一的目录。
比如项目中安装了多份 react，你可以将 react 统一指向根目录的 node_modules 中安装的版本，避免出现打包多份 React 代码的问题。
@@ -86,11 +86,11 @@ 处理
react: path.resolve(__dirname, './node_modules/react'),
},
},
-};
+};
当你在使用 alias 处理 npm 包时，请留意项目中是否使用了这个包不同的 major 版本。
比如你的项目中某个模块或 npm 依赖使用了 React 18 的 API，如果你将 React alias 到 17 版本，就会导致该模块无法引用到 React 18 的 API，导致代码异常。
source.aliasStrategy
-
+;
prefer
"@common/*": ["./src/common-1/*"]
}
}
-}
+}
@@ -119,7 +119,7 @@ prefer
'@utils': './src/utils',
},
},
-};
+};
由于 tsconfig paths 的优先级更高，所以：
prefer-al
source: {
aliasStrategy: 'prefer-alias',
},
-};
+};
比如同时配置以下内容：
prefer-al
"@utils/*": ["./src/utils/*"]
}
}
-}
+}
@@ -153,7 +153,7 @@ prefer-al
'@common': './src/common-2',
},
},
-};
+};
由于 tsconfig paths 只用于提供类型，所以最终只有 @common 别名生效，并指向 ./src/common-2 目录。
大部分情况下你不需要使用 prefer-alias，但当你需要动态生成一些别名配置时，可以考虑使用它。比如，基于环境变量来生成 alias 选项：
+};
source.include
-
+;
-
+];
source.include 用于指定额外需要编译的 JavaScript 文件。
为了避免二次编译，默认情况下，Rsbuild 只会编译当前目录下的 JavaScript 文件，以及所有目录下的 TypeScript 和 JSX 文件，不会编译 node_modules 下的 JavaScript 文件。
-通过 source.include 配置项，可以指定需要 Rsbuild 额外进行编译的目录或模块。source.include 的用法与 Rspack 中的 Rule.include 一致，支持传入字符串、正则表达式来匹配模块的路径。
+通过 source.include 配置项，可以指定需要 Rsbuild 额外进行编译的目录或模块。source.include 的用法与 Rspack 中的 Rule.include 一致，支持传入字符串、正则表达式来匹配模块的路径。
比如:
+};
编译 npm 包
比较典型的使用场景是编译 node_modules 下的 npm 包，因为某些第三方依赖存在 ES6+ 的语法，这可能导致在低版本浏览器上无法运行，你可以通过该选项指定需要编译的依赖，从而解决此类问题。
以 query-string 为例，你可以做如下的配置：
@@ -207,7 +207,7 @@ 编译
/\/node_modules\/query-string\//,
],
},
-};
+};
上述两种方法分别通过 "路径前缀" 和 "正则表达式" 来匹配文件的绝对路径，值得留意的是，项目中所有被引用的模块都会经过匹配，因此你不能使用过于松散的值进行匹配，避免造成编译性能问题或编译异常。
编译 npm 包的子依赖
当你通过 source.include 编译一个 npm 包时，Builder 默认只会编译匹配到的模块，不会编译对应模块的子依赖。
@@ -219,7 +219,7 @@ /\/node_modules\/decode-uri-component\//,
],
},
-};
+};
编译 Monorepo 中的其他库
在 Monorepo 中进行开发时，如果需要引用 Monorepo 中其他库的源代码，也可以直接在 source.include 进行配置:
+};
编译 CommonJS 模块
Babel 默认无法编译 CommonJS 模块，如果你编译了一个 CommonJS 模块，可能会出现 exports is not defined 的运行时报错信息。
当你需要使用 source.include 来编译 CommonJS 模块时，可以将 Babel 的 sourceType 配置设置为 unambiguous：
@@ -247,27 +247,27 @@ config.sourceType = 'unambiguous';
},
},
-};
-
将 sourceType 设置为 unambiguous 可能会产生一些其他影响，请参考 Babel 官方文档。
+};
+将 sourceType 设置为 unambiguous 可能会产生一些其他影响，请参考 Babel 官方文档。
匹配 Symlink
如果你匹配的模块是通过 symlink 链接到当前项目中的，那么需要匹配这个模块的真实路径，而不是 symlink 后的路径。
比如，你将 Monorepo 中的 packages/foo 路径 symlink 到当前项目的 node_modules/foo 路径下，则需要去匹配 packages/foo 路径，而不是 node_modules/foo 路径。
-该行为可以通过 webpack 的 resolve.symlinks 配置项来进行控制。
+该行为可以通过 webpack 的 resolve.symlinks 配置项来进行控制。
注意事项
注意，source.include 不应该被用于编译整个 node_modules 目录，比如下面的写法是错误的：
+};
如果你对整个 node_modules 进行编译，不仅会使编译时间大幅度增加，并且可能会产生不可预期的错误。因为 node_modules 中的大部分 npm 包发布的已经是编译后的产物，通常没必要经过二次编译。此外，core-js 等 npm 包被编译后可能会出现异常。
source.exclude
-
+;
-指定不需要编译的 JavaScript/TypeScript 文件。用法与 webpack 中的 Rule.exclude 一致，支持传入字符串或正则表达式来匹配模块的路径。
+指定不需要编译的 JavaScript/TypeScript 文件。用法与 webpack 中的 Rule.exclude 一致，支持传入字符串或正则表达式来匹配模块的路径。
比如:
+};
source.define
-
+;
sou
-更多细节参考 webpack - DefinePlugin。
-TIP在使用 Rspack 作为打包工具时，支持的类型可参考 Rspack.builtins.define
+
更多细节参考 webpack - DefinePlugin。
+TIP在使用 Rspack 作为打包工具时，支持的类型可参考 Rspack.builtins.define
示例
+};
表达式会被替换为对应的代码段：
+const foo = 1 + 1;
source.globalVars
-
+;
+};
用于在构建时将类似 process.env.FOO 的全局变量表达式替换为指定的值，比如：
-示例
+console.log('development');
+示例
在下方示例中，会在代码中注入 ENABLE_VCONSOLE 和 APP_CONTEXT 两个环境变量：
+};
你可以在代码中直接使用它们：
+console.log(APP_CONTEXT);
函数用法
函数用
+) => Record<string, JSONValue> | void;
你可以将 source.globalVars 设置为一个函数，从而动态设置一些环境变量的值。
比如，根据当前的构建产物类型进行动态设置：
+};
与 define 的区别
source.globalVars 是 source.define 的一个语法糖，它们之间唯一的区别是，source.globalVars 会自动将传入的值进行 JSON 序列化处理，这使得设置全局变量的值更加方便。注意 globalVars 的每个值都需要是可以被 JSON 序列化的值。
-注意事项
+};
+注意事项
source.globalVars 是通过字符串替换的形式来注入环境变量的，因此它无法对「解构赋值」等动态写法生效。
在使用解构赋值时，Builder 将无法判断变量 NODE_ENV 是否与要替换的表达式 process.env.NODE_ENV 存在关联，因此以下使用方式是无效的：
+// ❌ Won't get a string.
source.moduleScopes
-
+;
限制源代码的引用路径。配置该选项后，所有源文件只能从约定的目录下引用代码，从其他目录引用代码会产生对应的报错提示。
-示例
+示例
首先我们配置 moduleScopes 仅包含 src 目录：
+};
然后在 src/App.tsx 中导入 src 目录外部的 utils/a 模块:
-
+
在编译时，会提示引用路径错误:
通过该选项配置 utils 目录，再进行编译，则不会出现错误提示。
@@ -408,15 +408,15 @@ 示例 source: {
moduleScopes: ['./src', './utils'],
},
-};
+};
Array 类型
当 moduleScopes 的值为 Array 类型时，可以直接设置若干个代码路径，比如添加以下配置：
-Function 类型
+};
+Function 类型
moduleScopes 也支持通过函数的形式来进行修改，避免覆盖默认值：
+};
source.transformImport
-
-用于按需引入组件库的代码和样式，能力等价于 babel-plugin-import。
-它与 babel-plugin-import 的区别在于，source.transformImport 不与 Babel 耦合。Builder 会自动识别当前使用的编译工具是 Babel、SWC 还是 Rspack，并添加相应的按需引入配置。
+;
+用于按需引入组件库的代码和样式，能力等价于 babel-plugin-import。
+它与 babel-plugin-import 的区别在于，source.transformImport 不与 Babel 耦合。Builder 会自动识别当前使用的编译工具是 Babel、SWC 还是 Rspack，并添加相应的按需引入配置。
@@ -443,17 +443,17 @@ transformToDefaultImport?: boolean;
customName?: ((member: string) => string | undefined) | string;
customStyleName?: ((member: string) => string | undefined) | string;
- }>;
+ }>;
-
当项目中安装了 Ant Design 组件库 <= 4.x 版本时，Builder 会自动添加以下默认配置：
+当项目中安装了 Ant Design 组件库 <= 4.x 版本时，Builder 会自动添加以下默认配置：
-当项目中安装了 Arco Design 组件库 时，Builder 会自动添加以下默认配置：
+};
+当项目中安装了 Arco Design 组件库 时，Builder 会自动添加以下默认配置：
+];
TIP当你添加了 antd 或 @arco-design/web-react 相关的配置时，优先级会高于上述默认配置。
-示例
+示例
当使用上述 antd 默认配置：
+};
源代码如下：
-
+
会被转换成：
+import 'antd/es/button/style';
禁用默认配置
你可以手动设置 transformImport: false 来关掉 transformImport 的默认行为。
+};
比如，当你使用了 externals 来避免打包 antd 时，由于 transformImport 默认会转换 antd 的引用路径，导致匹配的路径发生了变化，因此 externals 无法正确生效，此时你可以设置关闭 transformImport 来避免该问题。
配置
libraryName
@@ -508,9 +508,9 @@ libraryDi
用于拼接转换后的路径，拼接规则为 ${libraryName}/${libraryDirectory}/${member}，其中 member 为引入成员。
示例：
-
+
转换结果:
-
+
style
style确定是否需要引入相关样式，若为 true，则会引入路径 ${libraryName}/${libraryDirectory}/${member}/style。
若为 false 或 undefined 则不会引入样式。
当配置为 true 时：
-
+
转换结果:
+import 'foo/lib/button/style';
styleLibraryDirectory
styl
该配置用于拼接引入样式时的引入路径，若该配置被指定，则 style 配置项会被忽略。拼接引入路径为 ${libraryName}/${styleLibraryDirectory}/${member}。
当配置为 styles 时：
-
+
转换结果:
+import 'foo/styles/button';
camelToDashComponentName
c
是否需要将 camelCase 的引入转换成 kebab-case。
示例：
-
+
转换结果：
+import ButtonGroup from 'foo/ButtonGroup';
transformToDefaultImport
t
是否将导入语句转换成默认导入。
示例：
-
+
转换结果：
+import { Button } from 'foo/button';
customName
customName
自定义转换后的导入路径，输入是引入的成员，例如配置成 (member) => `my-lib/${member}` ，会将 import { foo } from 'bar' 转换成 import foo from 'my-lib/foo'。
-在使用 Rspack 构建时，不能使用函数配置，但可以使用 handlebars 模版字符串，对于上面的函数配置，在使用模版字符串时可以用以下模版代替 my-lib/{{ member }}，也可以使用一些内置帮助方法，例如 my-lib/{{ kebabCase member }} 来转换成 kebab-case 格式，除了 kebabCase 以外还有 camelCase，snakeCase，upperCase，lowerCase 可以使用。
+在使用 Rspack 构建时，不能使用函数配置，但可以使用 handlebars 模版字符串，对于上面的函数配置，在使用模版字符串时可以用以下模版代替 my-lib/{{ member }}，也可以使用一些内置帮助方法，例如 my-lib/{{ kebabCase member }} 来转换成 kebab-case 格式，除了 kebabCase 以外还有 camelCase，snakeCase，upperCase，lowerCase 可以使用。
customStyleName
customStyl
自定义转换后的样式导入路径，输入是引入的成员，例如配置成 (member) => `my-lib/${member}` ，会将 import { foo } from 'bar' 转换成 import foo from 'my-lib/foo'。
-在使用 Rspack 构建时，不能使用函数配置，但可以使用 handlebars 模版字符串，对于上面的函数配置，在使用模版字符串时可以用以下模版代替 my-lib/{{ member }}，也可以使用一些内置帮助方法，例如 my-lib/{{ kebabCase member }} 来转换成 kebab-case 格式，除了 kebabCase 以外还有 camelCase，snakeCase，upperCase，lowerCase 可以使用。
+在使用 Rspack 构建时，不能使用函数配置，但可以使用 handlebars 模版字符串，对于上面的函数配置，在使用模版字符串时可以用以下模版代替 my-lib/{{ member }}，也可以使用一些内置帮助方法，例如 my-lib/{{ kebabCase member }} 来转换成 kebab-case 格式，除了 kebabCase 以外还有 camelCase，snakeCase，upperCase，lowerCase 可以使用。
source.preEntry
-
+;
s
在每个页面的入口文件前添加一段代码，这段代码会早于页面的代码执行，因此可以用于执行一些全局的代码逻辑，比如注入 polyfill、设置全局样式等。
添加单个脚本
首先创建一个 src/polyfill.ts 文件：
-
+
然后将 src/polyfill.ts 配置到 source.preEntry 上：
+};
重新运行编译并访问任意页面，可以看到 src/polyfill.ts 中的代码已经执行，并在 console 中输出了对应的内容。
添加全局样式
你也可以通过 source.preEntry 来配置全局样式，这段 CSS 代码会早于页面代码加载，比如引入一个 normalize.css 文件：
@@ -609,35 +609,35 @@ 添加
source: {
preEntry: './src/normalize.css',
},
-};
+};
添加多个脚本
你可以将 preEntry 设置为数组来添加多个脚本，它们会按数组顺序执行：
+};
source.resolveExtensionPrefix
-
+;
-用于为 resolve.extensions 添加统一的前缀。
+用于为 resolve.extensions 添加统一的前缀。
如果多个文件拥有相同的名称，但具有不同的文件后缀，Builder 会根据 extensions 数组的顺序进行识别，解析数组中第一个被识别的文件，并跳过其余文件。
-示例
+示例
下面是配置 .web 前缀的例子。
+};
配置完成后，extensions 数组会发生以下变化：
+const extensions = ['.web.js', '.js', '.web.ts' , '.ts', ...];
在代码中 import './foo' 时，会优先识别 foo.web.js 文件，再识别 foo.js 文件。
根据产物类型设置
当你同时构建多种类型的产物时，你可以为不同的产物类型设置不同的 extension 前缀。此时，你需要把 resolveExtensionPrefix 设置为一个对象，对象的 key 为对应的产物类型。
@@ -651,27 +651,27 @@
},
},
},
-};
+};
在代码中 import './foo' 时，对于 node 产物，会优先识别 foo.node.js 文件，而对于 web 产物，则会优先识别 foo.web.js 文件。
source.resolveMainFields
-
+;
+type ResolveMainFields = Fields | Record<BuilderTarget, Fields>;
-该配置项将决定你使用 package.json 哪个字段导入 npm 模块。对应 webpack 的 resolve.mainFields 配置。
-示例
+该配置项将决定你使用 package.json 哪个字段导入 npm 模块。对应 webpack 的 resolve.mainFields 配置。
+示例
-根据产物类型设置
+};
+根据产物类型设置
当你同时构建多种类型的产物时，你可以为不同的产物类型设置不同的 mainFields。此时，你需要把 resolveMainFields 设置为一个对象，对象的 key 为对应的产物类型。
比如为 web 和 node 设置不同的 mainFields：
目录
\ No newline at end of file
+};目录
\ No newline at end of file
diff --git a/modern-js/builder/api/config-tools.html b/modern-js/builder/api/config-tools.html
index 0b8c0a1b35..8c24531319 100644
--- a/modern-js/builder/api/config-tools.html
+++ b/modern-js/builder/api/config-tools.html
@@ -1,4 +1,4 @@
-Tools Config - Modern.js Builder
+Tools Config - Modern.js Builder
-Modern.js Builder Tools Config
+Modern.js Builder Tools Config
本章节描述了 Builder 中与底层工具有关的配置。
tools.autoprefixer
-
+;
// browserslist 取决于项目中的 browserslist 配置
// 以及 `output.overrideBrowserslist`(优先级更高) 配置
overrideBrowserslist: browserslist,
-}
-通过 tools.autoprefixer 可以修改 autoprefixer 的配置。
+}通过 tools.autoprefixer 可以修改 autoprefixer 的配置。
Object 类型
当 tools.autoprefixer 的值为 Object 类型时，会与默认配置通过 Object.assign 合并。比如：
+};
Function 类型
当 tools.autoprefixer 为 Function 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果。比如：
+};
tools.babel
-
+;
-通过 tools.babel 可以修改 babel-loader 的配置项。
+通过 tools.babel 可以修改 babel-loader 的配置项。
使用场景
请留意 tools.babel 在以下使用场景中的局限性：
-Function 类型
+Function 类型
当 tools.babel 为 Function 类型时，默认 Babel 配置会作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终的 babel-loader 配置。
+};tools.babel 函数的第二个参数提供了一些方便的工具函数，请继续阅读下方文档。
TIP以上示例仅作为参考，通常来说，你不需要手动配置 babel-plugin-import，因为 Builder 已经提供了更通用的 source.transformImport 配置。
-Object 类型
+Object 类型
当 tools.babel 的值为 Object 类型时，会与默认配置通过 Object.assign 浅合并。
CAUTIONObject.assign 是浅拷贝，会完全覆盖内置的 presets 或 plugins 数组，导致内置的 presets 或 plugins 失效，请在明确影响面的情况下再使用这种方式。
@@ -94,7 +94,7 @@ Object
],
},
},
-};
+};
工具函数
tools.babel 为 Function 类型时，第二个参数可用的工具函数如下:
addPlugins
@@ -117,7 +117,7 @@ addPlugins ]);
},
},
-};
+};
addPresets
addPresets addPresets(['@babel/preset-env']);
},
},
-};
+};
removePlugins
removePlugin
removePlugins('babel-plugin-import');
},
},
-};
+};
removePresets
removePreset
removePresets('@babel/preset-env');
},
},
-};
+};
modifyPresetEnvOptions
-
修改 @babel/preset-env 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+修改 @babel/preset-env 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+};
modifyPresetReactOptions
-修改 @babel/preset-react 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+修改 @babel/preset-react 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+};
addIncludes
-已废弃，请使用 source.include 代替，两者功能完全一致。
+已废弃，请使用 source.include 代替，两者功能完全一致。
addExcludes
-已废弃，请使用 source.exclude 代替，两者功能完全一致。
+已废弃，请使用 source.exclude 代替，两者功能完全一致。
调试 Babel 配置
-当你通过 tools.babel 修改 babel-loader 配置后，可以在 Builder 调试模式 下查看最终生成的配置。
+当你通过 tools.babel 修改 babel-loader 配置后，可以在 Builder 调试模式 下查看最终生成的配置。
首先通过 DEBUG=builder 参数开启调试模式：
+DEBUG=builder pnpm build
然后打开生成的 (webpack|rspack).config.web.js，搜索 babel-loader 关键词，即可看到完整的 babel-loader 配置内容。
tools.bundlerChain
-
+;
什么是 BundlerChain
Bundler chain 是 webpack chain 的子集，其中包含一部分 webpack chain API，你可以用它来同时修改 webpack 和 Rspack 的配置。
-通过 bundler chain 修改的配置，在 webpack 和 Rspack 构建时均可生效。需要注意的是，bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如，修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同)，或添加一个Rspack 兼容的 webpack 插件。
+通过 bundler chain 修改的配置，在 webpack 和 Rspack 构建时均可生效。需要注意的是，bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如，修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同)，或添加一个Rspack 兼容的 webpack 插件。
tools.bundlerChain 的执行时机早于 tools.webpackChain / tools.webpack / tools.rspack，因此会被其他几个配置中的修改所覆盖。
-工具集合
-env
-
-
-
通过 env 参数可以判断当前环境为 development、production 还是 test。比如：
-
-isProd
-
-
-通过 isProd 参数可以判断当前环境是否为 production。比如：
-
-target
-
-
-通过 target 参数可以判断当前构建的目标运行时环境。比如：
-
-isServer
-
-
-判断当前构建的目标运行时环境是否为 node，等价于 target === 'node'。
-
-isWebWorker
-
-
-判断当前构建的目标运行时环境是否为 web-worker，等价于 target === 'web-worker'。
-
-HtmlPlugin
-
-
-通过这个参数你可以拿到 webpack 或 Rspack 中的 HtmlPlugin 实例。
-
-CHAIN_ID
-Builder 中预先定义了一些常用的 Chain ID，你可以通过这些 ID 来定位到内置的 Rule 或 Plugin。
-TIP请留意，下列的一部分 Rule 或 Plugin 并不是默认存在的，当你开启特定配置项、或是注册某些插件后，它们才会被包含在 Rspack 或 webpack 配置中。
-比如，RULE.STYLUS 仅在注册了 Stylus 插件后才会存在。
-
-CHAIN_ID.RULE
-
-
-
-ID
-描述
-
-
-
-
-RULE.MJS处理 mjs 的规则
-
-
-RULE.CSS处理 css 的规则
-
-
-RULE.LESS处理 less 的规则
-
-
-RULE.SASS处理 sass 的规则
-
-
-RULE.STYLUS处理 stylus 的规则
-
-
-RULE.TOML处理 toml 的规则
-
-
-RULE.YAML处理 yaml 的规则
-
-
-RULE.WASM处理 wasm 的规则
-
-
-RULE.NODE处理 node 的规则
-
-
-
-CHAIN_ID.ONE_OF
-通过 ONE_OF.XXX 可以匹配到规则数组中的某一类规则。
-
-
-
-ID
-描述
-
-
-
-
-ONE_OF.SVG处理 SVG 的规则，在 data URI 和单独文件之间自动选择
-
-
-ONE_OF.SVG_URL处理 SVG 的规则，输出为单独文件
-
-
-ONE_OF.SVG_INLINE处理 SVG 的规则，作为 data URI 内联到 bundle 中
-
-
-ONE_OF.SVG_ASSETS处理 SVG 的规则，在 data URI 和单独文件之间自动选择
-
-
-
-CHAIN_ID.USE
-通过 USE.XXX 可以匹配到对应的 loader。
-
-
-
-ID
-描述
-
-
-
-
-USE.LESS对应 less-loader
-
-
-USE.SASS对应 sass-loader
-
-
-USE.STYLUS对应 stylus-loader
-
-
-USE.VUE对应 vue-loader
-
-
-USE.TOML对应 toml-loader
-
-
-USE.YAML对应 yaml-loader
-
-
-USE.NODE对应 node-loader
-
-
-USE.SVGR对应 @svgr/webpack
-
-
-USE.POSTCSS对应 postcss-loader
-
-
-USE.RESOLVE_URL_LOADER_FOR_SASS对应 resolve-url-loader
-
-
-
-CHAIN_ID.PLUGIN
-通过 PLUGIN.XXX 可以匹配到对应的 plugin。
-
-
-
-ID
-描述
-
-
-
-
-PLUGIN.HTML对应 HtmlPlugin，使用时需要拼接 entry 名称：${PLUGIN.HTML}-${entryName}
-
-
-PLUGIN.APP_ICON对应 AppIconPlugin
-
-
-PLUGIN.INLINE_HTML对应 InlineChunkHtmlPlugin
-
-
-PLUGIN.BUNDLE_ANALYZER对应 WebpackBundleAnalyzer
-
-
-PLUGIN.ASSETS_RETRY对应 Builder 中的 webpack 静态资源重试插件 WebpackAssetsRetryPlugin
-
-
-PLUGIN.VUE_LOADER_PLUGIN对应 VueLoaderPlugin
-
-
-PLUGIN.AUTO_SET_ROOT_SIZE对应 Builder 中的自动设置根字体大小插件 AutoSetRootSizePlugin
-
-
-
-CHAIN_ID.MINIMIZER
-通过 MINIMIZER.XXX 可以匹配到对应的压缩工具。
-
-
-
-ID
-描述
-
-
-
-
-MINIMIZER.JS对应 TerserWebpackPlugin 或 SwcJsMinimizerRspackPlugin
-
-
-MINIMIZER.CSS对应 CssMinimizerWebpackPlugin
-
-
-
-使用示例
-使用示例可参考：WebpackChain 使用示例。
+更多信息可参考 Rsbuild#tools.bundlerChain
tools.cssExtract
-
+;
chunkFilename: `${cssPath}/async/${cssFilename}`,
ignoreOrder: true,
},
-};
+};
-
通过 tools.cssExtract 可以更改 mini-css-extract-plugin 的配置。
-Object 类型
+通过 tools.cssExtract 可以更改 mini-css-extract-plugin 的配置。
+Object 类型
当此值为 Object 类型时，与默认配置通过 Object.assign 合并。比如：
-Function 类型
+};
+Function 类型
当此值为 Function 类型时，默认配置作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终配置。比如：
-更多配置细节可参考 mini-css-extract-plugin。
+};
+更多配置细节可参考 mini-css-extract-plugin。
tools.cssLoader
-
+;
-通过 tools.cssLoader 可以修改 css-loader 的配置项。默认配置如下:
+通过 tools.cssLoader 可以修改 css-loader 的配置项。默认配置如下:
-TIP在使用 Rspack 作为打包工具时，仅支持在 disableCssExtract 时使用该配置。
-修改 CSS Modules 相关配置，推荐使用 output.cssModules 配置项。
+}
+TIP在使用 Rspack 作为打包工具时，仅支持在 disableCssExtract 时使用该配置。
+修改 CSS Modules 相关配置，推荐使用 output.cssModules 配置项。
-Object 类型
+Object 类型
当此值为 Object 类型时，会与默认配置进行深层合并 (deep merge)。比如：
-Function 类型
+};
+Function 类型
当此值为 Function 类型时，默认配置作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终配置。比如：
+};
tools.devServer
-
+;
通过 tools.devServer 可以修改开发环境服务器的配置。
-TIPModern.js 中并没有直接使用 webpack-dev-server 或 @rspack/dev-server, 而是基于 webpack-dev-middleware 实现 DevServer。
+
TIPModern.js 中并没有直接使用 webpack-dev-server 或 @rspack/dev-server, 而是基于 webpack-dev-middleware 实现 DevServer。
选项
after
@@ -607,7 +331,7 @@ after ],
},
},
-};
+};
webpack-dev-server 使用 Express 作为服务端框架。Modern.js 中没有使用任何框架，上述中间件中 req 和 res 都是 Node 原生对象，因此 webpack-dev-server 的 Express 中间件不一定能直接在 Modern.js 中使用。
如果要迁移 webpack-dev-server 中使用的 Express 中间件，可以使用以下方式，将 Express app 作为中间件传入：
+};
before
before ],
},
},
-};
+};
client
client port?: string;
/** 指定要使用的 host */
host?: string;
-}
+}
@@ -667,7 +391,7 @@ client host: '',
// By default it is set to "location.protocol === 'https:' ? 'wss' : 'ws'""
protocol: '',
-};
+};
对应 HMR 客户端的配置，通常用于设置 HMR 对应的 WebSocket URL。
compress
@@ -682,21 +406,21 @@ compress compress: false,
},
},
-};
+};
devMiddleware
+}
-devMiddleware 配置项。当前配置是 webpack-dev-middleware 配置项的子集.
+}
+devMiddleware 配置项。当前配置是 webpack-dev-middleware 配置项的子集.
headers
headers },
},
},
-};
+};
historyApiFallback
history
historyApiFallback: true,
},
},
-};
-
更多选项和详细信息可参考 connect-history-api-fallback 文档。
+};
+更多选项和详细信息可参考 connect-history-api-fallback 文档。
hot
-是否开启 Hot Module Replacement 热更新能力。
+是否开启 Hot Module Replacement 热更新能力。
https
https },
},
},
-};
+};
liveReload
setupMidd
) => void;
},
) => void
->;
+>;
@@ -794,7 +518,7 @@ setupMidd
],
},
},
-};
+};
一些特殊场景需求可能需要使用服务器 API：
setupMidd
],
},
},
-};
+};
proxy
proxy },
},
},
-};
-此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
+};
+此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
如果你不想传递 /api，可以通过 pathRewrite 重写请求路径：
-DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
+};
+DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
DevServer Proxy 完整类型定义为：
+ | ProxyDetail;
除了 http-proxy-middleware 的选项外，还支持 bypass 和 context 两个配置项：
webpack-bundle-analyzer。当开启该功能后，内部的默认配置如下:webpack-bundle-analyzer 来分析构建产物的体积:Size 类型
webpack-bundle-analyzer 的面板中，你可以在左上角控制 Size 类型（默认为 Parsed）：生
generateStatsFile: true,
},
},
-};
+};
注意事项
-
performance.chunkSplit
-
+
;
forceSplitting?: ForceSplitting;
}
-export type ChunkSplit = BaseChunkSplit | SplitBySize | SplitCustom;
+export type ChunkSplit = BaseChunkSplit | SplitBySize | SplitCustom;
chunkSplit.strategy
Builder 支持设置以下几种拆包策略：
-
@@ -206,7 +212,7 @@
chun
minSize: 20000,
},
},
-};
+};
chunkSplit.maxSize
chun
maxSize: 50000,
},
},
-};
+};
chunkSplit.forceSplitting
},
},
},
-};
+};
相比直接配置 webpack 的 splitChunks，这是一个更加简便的方式。
TIP注意，通过 forceSplitting 配置拆分的 chunk 会通过 <script> 标签插入到 HTML 文件中，作为首屏请求的资源。因此，请根据实际场景来进行适当地拆分，避免首屏资源体积过大。
@@ -258,7 +264,7 @@
},
},
},
-};
+};
chunkSplit.override
当 performance.chunkSplit.strategy 为 split-by-experience、split-by-module、split-by-size 或 single-vendor 时，可以通过 performance.chunkSplit.override 配置项来自定义 webpack 拆包配置，此配置会和 webpack 的 splitChunks 配置进行合并（cacheGroups 配置也会合并）。比如:
+};
当 Builder 构建 "node" 类型的产物时，由于 Node Bundles 不需要通过拆包来优化加载性能，因此 chunkSplit 规则不会生效。
performance.dnsPrefetch
-
+;
-为哪些资源配置 dns-prefetch 属性。
+为哪些资源配置 dns-prefetch 属性。
配置该属性可以在请求资源之前解析域名，降低请求延迟，提升加载性能。
-更多信息可参考：Using dns-prefetch
-示例
+更多信息可参考：Using dns-prefetch
+示例
+};
performance.preconnect
-
+;
+}
-为哪些资源配置 preconnect 属性。
+为哪些资源配置 preconnect 属性。
配置该属性会预先建立与服务器的连接，如果站点是 HTTPS 的，则此过程包括 DNS 解析，建立 TCP 连接以及执行 TLS 握手。将 Preconnect 和 DnsPrefetch 结合使用可进一步减少跨域请求的延迟。
-示例
+示例
+};
performance.prefetch
-
+;
@@ -332,17 +338,17 @@ type?: IncludeType;
include?: Filter;
exclude?: Filter;
-}
+}
-
为哪些资源配置 prefetch 属性。
+为哪些资源配置 prefetch 属性。
该属性用于配置在将来某些导航下可能需要的资源，此时，浏览器通常在空闲状态时获取此资源。
Boolean 类型
当设置 performance.prefetch 为 true，将根据如下配置对资源进行预获取:
+}
Object 类型
当 performance.prefetch 的值为 object 类型时，Builder 会根据当前配置对指定资源开启 prefetch 能力。
prefetch.type
@@ -354,7 +360,7 @@ prefetch.type
-示例
+示例
当你希望对当前页面中所有 png 格式的图片资源进行预获取时，可以配置如下：
+};
performance.preload
-
+;
@@ -377,18 +383,18 @@ type?: IncludeType;
include?: Filter;
exclude?: Filter;
-}
+}
-
为哪些资源配置 preload 属性。
+为哪些资源配置 preload 属性。
该属性通常用于配置当前导航下可能需要的资源，此时，浏览器通常以中等优先级（不是布局阻塞）获取此资源。
-Boolean 类型
+Boolean 类型
当设置 performance.preload 为 true，将根据如下配置对资源进行预加载:
-Object 类型
+}
+Object 类型
当 performance.preload 的值为 object 类型时，Builder 会根据当前配置对指定资源开启 preload 能力。
preload.type
type 字段控制了哪些资源会被预加载，同时支持通过 include 和 exclude 对指定资源进行二次过滤。
@@ -399,7 +405,7 @@ preload.typeall-chunks: 预加载所有资源(当前页面)，包含所有异步和非异步资源。
-示例
+示例
chun
maxSize: 50000,
},
},
-};
+};
chunkSplit.forceSplitting
},
},
},
-};
+};
相比直接配置 webpack 的 splitChunks，这是一个更加简便的方式。
TIP注意，通过 forceSplitting 配置拆分的 chunk 会通过 <script> 标签插入到 HTML 文件中，作为首屏请求的资源。因此，请根据实际场景来进行适当地拆分，避免首屏资源体积过大。
@@ -258,7 +264,7 @@
},
},
},
-};
+};
chunkSplit.override
当 performance.chunkSplit.strategy 为 split-by-experience、split-by-module、split-by-size 或 single-vendor 时，可以通过 performance.chunkSplit.override 配置项来自定义 webpack 拆包配置，此配置会和 webpack 的 splitChunks 配置进行合并（cacheGroups 配置也会合并）。比如:
+};
当 Builder 构建 "node" 类型的产物时，由于 Node Bundles 不需要通过拆包来优化加载性能，因此 chunkSplit 规则不会生效。
performance.dnsPrefetch
-
+;
-为哪些资源配置 dns-prefetch 属性。
+为哪些资源配置 dns-prefetch 属性。
配置该属性可以在请求资源之前解析域名，降低请求延迟，提升加载性能。
-更多信息可参考：Using dns-prefetch
-示例
+更多信息可参考：Using dns-prefetch
+示例
+};
performance.preconnect
-
+;
+}
-为哪些资源配置 preconnect 属性。
+为哪些资源配置 preconnect 属性。
配置该属性会预先建立与服务器的连接，如果站点是 HTTPS 的，则此过程包括 DNS 解析，建立 TCP 连接以及执行 TLS 握手。将 Preconnect 和 DnsPrefetch 结合使用可进一步减少跨域请求的延迟。
-示例
+示例
+};
performance.prefetch
-
+;
@@ -332,17 +338,17 @@ type?: IncludeType;
include?: Filter;
exclude?: Filter;
-}
+}
-
为哪些资源配置 prefetch 属性。
+为哪些资源配置 prefetch 属性。
该属性用于配置在将来某些导航下可能需要的资源，此时，浏览器通常在空闲状态时获取此资源。
Boolean 类型
当设置 performance.prefetch 为 true，将根据如下配置对资源进行预获取:
+}
Object 类型
当 performance.prefetch 的值为 object 类型时，Builder 会根据当前配置对指定资源开启 prefetch 能力。
prefetch.type
@@ -354,7 +360,7 @@ prefetch.type
-示例
+示例
}, }, }, -}; +};
相比直接配置 webpack 的 splitChunks，这是一个更加简便的方式。
注意，通过 forceSplitting 配置拆分的 chunk 会通过 <script> 标签插入到 HTML 文件中，作为首屏请求的资源。因此，请根据实际场景来进行适当地拆分，避免首屏资源体积过大。
},
},
},
-};
+};
chunkSplit.override
当 performance.chunkSplit.strategy 为 split-by-experience、split-by-module、split-by-size 或 single-vendor 时，可以通过 performance.chunkSplit.override 配置项来自定义 webpack 拆包配置，此配置会和 webpack 的 splitChunks 配置进行合并（cacheGroups 配置也会合并）。比如:
当 Builder 构建 "node" 类型的产物时，由于 Node Bundles 不需要通过拆包来优化加载性能，因此 chunkSplit 规则不会生效。
performance.dnsPrefetch
- +;
为哪些资源配置 dns-prefetch 属性。
+为哪些资源配置 dns-prefetch 属性。
配置该属性可以在请求资源之前解析域名，降低请求延迟，提升加载性能。
-更多信息可参考：Using dns-prefetch
-示例
+更多信息可参考：Using dns-prefetch
+示例
performance.preconnect
- +;
为哪些资源配置 preconnect 属性。
+为哪些资源配置 preconnect 属性。
配置该属性会预先建立与服务器的连接，如果站点是 HTTPS 的，则此过程包括 DNS 解析，建立 TCP 连接以及执行 TLS 握手。将 Preconnect 和 DnsPrefetch 结合使用可进一步减少跨域请求的延迟。
-示例
+示例
performance.prefetch
- +;
type?: IncludeType;
include?: Filter;
exclude?: Filter;
-}
+}
-
为哪些资源配置 prefetch 属性。
+为哪些资源配置 prefetch 属性。
该属性用于配置在将来某些导航下可能需要的资源，此时，浏览器通常在空闲状态时获取此资源。
Boolean 类型
当设置 performance.prefetch 为 true，将根据如下配置对资源进行预获取:
Object 类型
当 performance.prefetch 的值为 object 类型时，Builder 会根据当前配置对指定资源开启 prefetch 能力。
prefetch.type
@@ -354,7 +360,7 @@prefetch.type
当你希望对当前页面中所有 png 格式的图片资源进行预获取时，可以配置如下：
performance.preload
- +;
type?: IncludeType;
include?: Filter;
exclude?: Filter;
-}
+}
-
为哪些资源配置 preload 属性。
+为哪些资源配置 preload 属性。
该属性通常用于配置当前导航下可能需要的资源，此时，浏览器通常以中等优先级（不是布局阻塞）获取此资源。
-Boolean 类型
+Boolean 类型
当设置 performance.preload 为 true，将根据如下配置对资源进行预加载:
Object 类型
+} +Object 类型
当 performance.preload 的值为 object 类型时，Builder 会根据当前配置对指定资源开启 preload 能力。
preload.type
type 字段控制了哪些资源会被预加载，同时支持通过 include 和 exclude 对指定资源进行二次过滤。
preload.typeall-chunks: 预加载所有资源(当前页面)，包含所有异步和非异步资源。
当你希望对当前页面中所有 png 格式的图片资源进行预加载时，可以配置如下：
performance.printFileSize
- +;
dist/static/js/lib-react.09721b5c.js 152.6 kB 49.0 kB
dist/html/main/index.html 5.8 kB 2.5 kB
dist/static/js/main.3568a38e.js 3.5 kB 1.4 kB
- dist/static/css/main.03221f72.css 1.4 kB 741 B
-示例
+ dist/static/css/main.03221f72.css 1.4 kB 741 B
+示例
禁用相关日志：
performance.profile
- +;
是否捕获每个模块的耗时信息，对应 webpack / Rspack 的 profile 配置。
-示例
+是否捕获每个模块的耗时信息，对应 webpack / Rspack 的 profile 配置。
+示例
开启后，Webpack / Rspack 生成一些有关模块的统计数据的 JSON 文件会将模块构建的耗时信息也包含进去。
performance.removeConsole
- +;
移
performance: {
removeConsole: true,
},
-};
+};
移除特定的 console
你也可以指定仅移除特定类型的 console.xx，比如移除 console.log 和 console.warn：
目前支持配置以下类型的 console：
-performance.removeMomentLocale
- +;
是否移除 moment.js 的语言包文件。
+是否移除 moment.js 的语言包文件。
moment.js 默认包含了大量的语言包文件，会导致打包后的包体积增大。
当项目中使用了 moment.js 时，推荐开启此选项，自动排除所有的语言包文件：
开启后，可以通过以下方式来加载语言包文件：
performance.transformLodash
- +;
是否模块化 lodash 的导入，删除未使用的 lodash 模块，从而减少 lodash 代码体积。
-这项优化基于 babel-plugin-lodash 和 swc-plugin-lodash 实现。
-示例
+是否模块化 lodash 的导入，删除未使用的 lodash 模块，从而减少 lodash 代码体积。
+这项优化基于 babel-plugin-lodash 和 swc-plugin-lodash 实现。
+示例
该选项默认开启，Builder 会自动将 lodash 的代码引用指向子路径。
比如：
转换后的代码为：
关闭转换
在个别情况下，lodash 的 import 转换可能会生成不符合预期的代码，此时你可以手动关闭这项优化：
Security Config
+Security Config
本章节描述了 Builder 中与安全有关的配置。
security.sri
- +;
secu enabled?: 'auto' | boolean; hashLoading?: 'eager' | 'lazy'; } - | boolean;
为 HTML 所引入的子资源添加完整性属性 —— integrity，使浏览器能够验证引入资源的完整性，以此防止下载的资源被篡改。
启动该选项后会将 webpack 的 output.crossOriginLoading 配置项设置为 anonymous。
启动该选项后会将 webpack 的 output.crossOriginLoading 配置项设置为 anonymous。
SRI 介绍
子资源完整性 Subresource Integrity（SRI）是专门用来校验资源的一种方案，它读取资源标签中的 integrity 属性，将其中的信息摘要值，和资源实际的信息摘要值进行对比，如果发现无法匹配，那么浏览器就会拒绝执行资源。
对于 script 标签来说，结果为拒绝执行其中的代码；对于 CSS link 来说，结果为不加载其中的样式。
-关于 SRI 的更多内容，可以查看 Subresource Integrity - MDN。
+关于 SRI 的更多内容，可以查看 Subresource Integrity - MDN。
示例
默认情况下，不会开启 SRI，当开启之后它的默认配置如下：
你可以按照你自己的需求自定义配置项:
security.checkSyntax
- +;
targets?: string[]; exclude?: RegExp | RegExp[]; ecmaVersion?: EcmaVersion; - };
启用检 security: { checkSyntax: true, }, -}; +};
当你开启 checkSyntax 后，Builder 会在生产环境构建时进行检测，当在构建产物中检测到不兼容的高级语法后，会将错误日志打印在终端，并退出当前构建流程。
错误日志
错误日志的格式如下所示，包含代码来源文件、产物位置、错误原因、源代码等信息：
@@ -88,7 +88,7 @@错误日
> 12 | console.log(() => {
13 | return a + b;
14 | });
- 15 |
+ 15 |
TIP目前语法检测是基于 AST parser 来实现的，每次检测时，只能找出文件中的第一个不兼容语法。如果一个文件中存在多个不兼容语法，你需要修复已发现的语法，并重新执行检测。output.disableMinimize 设置为 true 后再重新构建。
如果日志中没有显示对应的源码位置，可以尝试将
解决方法
@@ -104,7 +104,7 @@ checkSy
目前语法检测是基于 AST parser 来实现的，每次检测时，只能找出文件中的第一个不兼容语法。如果一个文件中存在多个不兼容语法，你需要修复已发现的语法，并重新执行检测。output.disableMinimize 设置为 true 后再重新构建。
如果日志中没有显示对应的源码位置，可以尝试将
targets 表示项目的目标浏览器范围，它的值为标准的 browserslist 数组，如果你不了解 browserslist 的用法，请参考 「设置浏览器范围」。
targets 表示项目的目标浏览器范围，它的值为标准的 browserslist 数组，如果你不了解 browserslist 的用法，请参考 「设置浏览器范围」。
Builder 会读取 targets 的值，并自动推导出构建产物中可以使用的最低 ECMAScript 语法版本，比如 ES5 或 ES6。
checkSy targets: ['chrome >= 53'], }, }, -}; +};
Builder 会推导出 chrome >= 53 可以使用的 ECMAScript 语法版本为 ES6，当构建产物中包含 es2016 或更高的语法时，就会触发语法错误提示。
请留意，Builder 不支持基于 targets 来自动分析 ES6 以上的语法版本，如果你的构建产物兼容的语法版本超过 ES6，请通过 checkSyntax.ecmaVersion 进行设置。
che ecmaVersion: 2020, }, }, -}; +};
此时，构建产物中可以包含 ES2020 支持的所有语法，比如 optional chaining。
checkSyntax.exclude
-
@@ -154,4 +154,4 @@
checkSy
exclude: /node_modules\/foo/,
},
},
-};目录
\ No newline at end of file
+};目录
\ No newline at end of file
diff --git a/modern-js/builder/api/config-source.html b/modern-js/builder/api/config-source.html
index 8507013ef3..b8ae4a97bf 100644
--- a/modern-js/builder/api/config-source.html
+++ b/modern-js/builder/api/config-source.html
@@ -1,4 +1,4 @@
-Source Config - Modern.js Builder
+Source Config - Modern.js Builder
-Modern.js Builder Source Config
+Modern.js Builder Source Config
本章节描述了 Builder 中与源代码解析、编译方式相关的配置。
source.alias
-
+;
-设置文件引用的别名，对应 webpack 和 Rspack 的 resolve.alias 配置。
-TIP对于 TypeScript 项目，你只需要在 tsconfig.json 中配置 compilerOptions.paths 即可，Builder 会自动识别它，不需要额外配置 source.alias 字段，详见 「路径别名」。
+
设置文件引用的别名，对应 webpack 和 Rspack 的 resolve.alias 配置。
+TIP对于 TypeScript 项目，你只需要在 tsconfig.json 中配置 compilerOptions.paths 即可，Builder 会自动识别它，不需要额外配置 source.alias 字段，详见 「路径别名」。
Object 类型
alias 的值可以定义为 Object 类型，其中的相对路径会自动被 Builder 转换为绝对路径。
@@ -27,7 +27,7 @@ Object
'@common': './src/common',
},
},
-};
+};
以上配置完成后，如果你在代码中引用 @common/Foo.tsx, 则会映射到 <project>/src/common/Foo.tsx 路径上。
Function 类型
alias 的值定义为函数时，可以接受预设的 alias 对象，并对其进行修改。
@@ -37,7 +37,7 @@ Functi
alias['@common'] = './src/common';
},
},
-};
也可以在函数中返回一个新对象作为最终结果，新对象会覆盖预设的 alias 对象。
+};精确匹配
默认情况，source.alias 会自动匹配子路径，比如以下配置：
+};
Source Config
+Source Config
本章节描述了 Builder 中与源代码解析、编译方式相关的配置。
source.alias
- +;
设置文件引用的别名，对应 webpack 和 Rspack 的 resolve.alias 配置。
-对于 TypeScript 项目，你只需要在 tsconfig.json 中配置 compilerOptions.paths 即可，Builder 会自动识别它，不需要额外配置 source.alias 字段，详见 「路径别名」。
+
设置文件引用的别名，对应 webpack 和 Rspack 的 resolve.alias 配置。
+对于 TypeScript 项目，你只需要在 tsconfig.json 中配置 compilerOptions.paths 即可，Builder 会自动识别它，不需要额外配置 source.alias 字段，详见 「路径别名」。
Object 类型
alias 的值可以定义为 Object 类型，其中的相对路径会自动被 Builder 转换为绝对路径。
Object '@common': './src/common', }, }, -};
以上配置完成后，如果你在代码中引用 @common/Foo.tsx, 则会映射到 <project>/src/common/Foo.tsx 路径上。
Function 类型
alias 的值定义为函数时，可以接受预设的 alias 对象，并对其进行修改。
Functi alias['@common'] = './src/common'; }, }, -};
也可以在函数中返回一个新对象作为最终结果，新对象会覆盖预设的 alias 对象。
精确匹配
默认情况，source.alias 会自动匹配子路径，比如以下配置：
它的匹配结果如下：
你可以添加 $ 符号来开启精确匹配，开启后将不会自动匹配子路径。
它的匹配结果如下：
处理 npm 包
你可以使用 alias 将某个 npm 包指向统一的目录。
比如项目中安装了多份 react，你可以将 react 统一指向根目录的 node_modules 中安装的版本，避免出现打包多份 React 代码的问题。
处理 react: path.resolve(__dirname, './node_modules/react'), }, }, -}; +};
当你在使用 alias 处理 npm 包时，请留意项目中是否使用了这个包不同的 major 版本。
比如你的项目中某个模块或 npm 依赖使用了 React 18 的 API，如果你将 React alias 到 17 版本，就会导致该模块无法引用到 React 18 的 API，导致代码异常。
source.aliasStrategy
- +;
prefer
"@common/*": ["./src/common-1/*"]
}
}
-}
+}
@@ -119,7 +119,7 @@ prefer
'@utils': './src/utils',
},
},
-};
+};
由于 tsconfig paths 的优先级更高，所以：
prefer-al source: { aliasStrategy: 'prefer-alias', }, -}; +};
比如同时配置以下内容：
prefer-al
"@utils/*": ["./src/utils/*"]
}
}
-}
+}
@@ -153,7 +153,7 @@ prefer-al
'@common': './src/common-2',
},
},
-};
+};
由于 tsconfig paths 只用于提供类型，所以最终只有 @common 别名生效，并指向 ./src/common-2 目录。
大部分情况下你不需要使用 prefer-alias，但当你需要动态生成一些别名配置时，可以考虑使用它。比如，基于环境变量来生成 alias 选项：
source.include
- +;
-
-
source.include 用于指定额外需要编译的 JavaScript 文件。
为了避免二次编译，默认情况下，Rsbuild 只会编译当前目录下的 JavaScript 文件，以及所有目录下的 TypeScript 和 JSX 文件，不会编译 node_modules 下的 JavaScript 文件。
-通过 source.include 配置项，可以指定需要 Rsbuild 额外进行编译的目录或模块。source.include 的用法与 Rspack 中的 Rule.include 一致，支持传入字符串、正则表达式来匹配模块的路径。
通过 source.include 配置项，可以指定需要 Rsbuild 额外进行编译的目录或模块。source.include 的用法与 Rspack 中的 Rule.include 一致，支持传入字符串、正则表达式来匹配模块的路径。
比如:
编译 npm 包
比较典型的使用场景是编译 node_modules 下的 npm 包，因为某些第三方依赖存在 ES6+ 的语法，这可能导致在低版本浏览器上无法运行，你可以通过该选项指定需要编译的依赖，从而解决此类问题。
以 query-string 为例，你可以做如下的配置：
编译 /\/node_modules\/query-string\//, ], }, -}; +};
上述两种方法分别通过 "路径前缀" 和 "正则表达式" 来匹配文件的绝对路径，值得留意的是，项目中所有被引用的模块都会经过匹配，因此你不能使用过于松散的值进行匹配，避免造成编译性能问题或编译异常。
编译 npm 包的子依赖
当你通过 source.include 编译一个 npm 包时，Builder 默认只会编译匹配到的模块，不会编译对应模块的子依赖。
/\/node_modules\/decode-uri-component\//,
],
},
-};
+};
编译 Monorepo 中的其他库
在 Monorepo 中进行开发时，如果需要引用 Monorepo 中其他库的源代码，也可以直接在 source.include 进行配置:
编译 CommonJS 模块
Babel 默认无法编译 CommonJS 模块，如果你编译了一个 CommonJS 模块，可能会出现 exports is not defined 的运行时报错信息。
当你需要使用 source.include 来编译 CommonJS 模块时，可以将 Babel 的 sourceType 配置设置为 unambiguous：
config.sourceType = 'unambiguous'; }, }, -}; -
将 sourceType 设置为 unambiguous 可能会产生一些其他影响，请参考 Babel 官方文档。
将 sourceType 设置为 unambiguous 可能会产生一些其他影响，请参考 Babel 官方文档。
匹配 Symlink
如果你匹配的模块是通过 symlink 链接到当前项目中的，那么需要匹配这个模块的真实路径，而不是 symlink 后的路径。
比如，你将 Monorepo 中的 packages/foo 路径 symlink 到当前项目的 node_modules/foo 路径下，则需要去匹配 packages/foo 路径，而不是 node_modules/foo 路径。
该行为可以通过 webpack 的 resolve.symlinks 配置项来进行控制。
+该行为可以通过 webpack 的 resolve.symlinks 配置项来进行控制。
注意事项
注意，source.include 不应该被用于编译整个 node_modules 目录，比如下面的写法是错误的：
如果你对整个 node_modules 进行编译，不仅会使编译时间大幅度增加，并且可能会产生不可预期的错误。因为 node_modules 中的大部分 npm 包发布的已经是编译后的产物，通常没必要经过二次编译。此外，core-js 等 npm 包被编译后可能会出现异常。
source.exclude
- +;
指定不需要编译的 JavaScript/TypeScript 文件。用法与 webpack 中的 Rule.exclude 一致，支持传入字符串或正则表达式来匹配模块的路径。
+指定不需要编译的 JavaScript/TypeScript 文件。用法与 webpack 中的 Rule.exclude 一致，支持传入字符串或正则表达式来匹配模块的路径。
比如:
source.define
- +;
sou
更多细节参考 webpack - DefinePlugin。
-在使用 Rspack 作为打包工具时，支持的类型可参考 Rspack.builtins.define +
更多细节参考 webpack - DefinePlugin。
+在使用 Rspack 作为打包工具时，支持的类型可参考 Rspack.builtins.define
示例
表达式会被替换为对应的代码段：
source.globalVars
- +;
+};
用于在构建时将类似 process.env.FOO 的全局变量表达式替换为指定的值，比如：
示例
+console.log('development'); +示例
在下方示例中，会在代码中注入 ENABLE_VCONSOLE 和 APP_CONTEXT 两个环境变量：
你可以在代码中直接使用它们：
函数用法
函数用
+) => Record<string, JSONValue> | void;
你可以将 source.globalVars 设置为一个函数，从而动态设置一些环境变量的值。
比如，根据当前的构建产物类型进行动态设置：
与 define 的区别
source.globalVars 是 source.define 的一个语法糖，它们之间唯一的区别是，source.globalVars 会自动将传入的值进行 JSON 序列化处理，这使得设置全局变量的值更加方便。注意 globalVars 的每个值都需要是可以被 JSON 序列化的值。
注意事项
+}; +注意事项
source.globalVars 是通过字符串替换的形式来注入环境变量的，因此它无法对「解构赋值」等动态写法生效。
在使用解构赋值时，Builder 将无法判断变量 NODE_ENV 是否与要替换的表达式 process.env.NODE_ENV 存在关联，因此以下使用方式是无效的：
source.moduleScopes
- +;
限制源代码的引用路径。配置该选项后，所有源文件只能从约定的目录下引用代码，从其他目录引用代码会产生对应的报错提示。
-示例
+示例
首先我们配置 moduleScopes 仅包含 src 目录：
然后在 src/App.tsx 中导入 src 目录外部的 utils/a 模块:
在编译时，会提示引用路径错误:
通过该选项配置 utils 目录，再进行编译，则不会出现错误提示。
示例 source: {
moduleScopes: ['./src', './utils'],
},
-};
+};
Array 类型
当 moduleScopes 的值为 Array 类型时，可以直接设置若干个代码路径，比如添加以下配置：
-Function 类型
+};
+Function 类型
moduleScopes 也支持通过函数的形式来进行修改，避免覆盖默认值：
+};
source.transformImport
-
-用于按需引入组件库的代码和样式，能力等价于 babel-plugin-import。
-它与 babel-plugin-import 的区别在于，source.transformImport 不与 Babel 耦合。Builder 会自动识别当前使用的编译工具是 Babel、SWC 还是 Rspack，并添加相应的按需引入配置。
+;
+用于按需引入组件库的代码和样式，能力等价于 babel-plugin-import。
+它与 babel-plugin-import 的区别在于，source.transformImport 不与 Babel 耦合。Builder 会自动识别当前使用的编译工具是 Babel、SWC 还是 Rspack，并添加相应的按需引入配置。
@@ -443,17 +443,17 @@ transformToDefaultImport?: boolean;
customName?: ((member: string) => string | undefined) | string;
customStyleName?: ((member: string) => string | undefined) | string;
- }>;
+ }>;
-
当项目中安装了 Ant Design 组件库 <= 4.x 版本时，Builder 会自动添加以下默认配置：
+当项目中安装了 Ant Design 组件库 <= 4.x 版本时，Builder 会自动添加以下默认配置：
-当项目中安装了 Arco Design 组件库 时，Builder 会自动添加以下默认配置：
+};
+当项目中安装了 Arco Design 组件库 时，Builder 会自动添加以下默认配置：
+];
TIP当你添加了 antd 或 @arco-design/web-react 相关的配置时，优先级会高于上述默认配置。
-示例
+示例
当使用上述 antd 默认配置：
+};
源代码如下：
-
+
会被转换成：
+import 'antd/es/button/style';
禁用默认配置
你可以手动设置 transformImport: false 来关掉 transformImport 的默认行为。
+};
比如，当你使用了 externals 来避免打包 antd 时，由于 transformImport 默认会转换 antd 的引用路径，导致匹配的路径发生了变化，因此 externals 无法正确生效，此时你可以设置关闭 transformImport 来避免该问题。
配置
libraryName
@@ -508,9 +508,9 @@ libraryDi
moduleScopes 的值为 Array 类型时，可以直接设置若干个代码路径，比如添加以下配置：moduleScopes 也支持通过函数的形式来进行修改，避免覆盖默认值：source.transformImport 不与 Babel 耦合。Builder 会自动识别当前使用的编译工具是 Babel、SWC 还是 Rspack，并添加相应的按需引入配置。source.transformImport 不与 Babel 耦合。Builder 会自动识别当前使用的编译工具是 Babel、SWC 还是 Rspack，并添加相应的按需引入配置。当你添加了 antd 或 @arco-design/web-react 相关的配置时，优先级会高于上述默认配置。
transformImport: false 来关掉 transformImport 的默认行为。externals 来避免打包 antd 时，由于 transformImport 默认会转换 antd 的引用路径，导致匹配的路径发生了变化，因此 externals 无法正确生效，此时你可以设置关闭 transformImport 来避免该问题。用于拼接转换后的路径，拼接规则为 ${libraryName}/${libraryDirectory}/${member}，其中 member 为引入成员。
示例：
-转换结果:
-style
style确定是否需要引入相关样式，若为 true，则会引入路径 ${libraryName}/${libraryDirectory}/${member}/style。
若为 false 或 undefined 则不会引入样式。
当配置为 true 时：
-
+
转换结果:
+import 'foo/lib/button/style';
styleLibraryDirectory
styl
该配置用于拼接引入样式时的引入路径，若该配置被指定，则 style 配置项会被忽略。拼接引入路径为 ${libraryName}/${styleLibraryDirectory}/${member}。
当配置为 styles 时：
-
+
转换结果:
+import 'foo/styles/button';
camelToDashComponentName
c
是否需要将 camelCase 的引入转换成 kebab-case。
示例：
-
+
转换结果：
+import ButtonGroup from 'foo/ButtonGroup';
transformToDefaultImport
t
是否将导入语句转换成默认导入。
示例：
-
+
转换结果：
+import { Button } from 'foo/button';
customName
customName
自定义转换后的导入路径，输入是引入的成员，例如配置成 (member) => `my-lib/${member}` ，会将 import { foo } from 'bar' 转换成 import foo from 'my-lib/foo'。
-在使用 Rspack 构建时，不能使用函数配置，但可以使用 handlebars 模版字符串，对于上面的函数配置，在使用模版字符串时可以用以下模版代替 my-lib/{{ member }}，也可以使用一些内置帮助方法，例如 my-lib/{{ kebabCase member }} 来转换成 kebab-case 格式，除了 kebabCase 以外还有 camelCase，snakeCase，upperCase，lowerCase 可以使用。
+在使用 Rspack 构建时，不能使用函数配置，但可以使用 handlebars 模版字符串，对于上面的函数配置，在使用模版字符串时可以用以下模版代替 my-lib/{{ member }}，也可以使用一些内置帮助方法，例如 my-lib/{{ kebabCase member }} 来转换成 kebab-case 格式，除了 kebabCase 以外还有 camelCase，snakeCase，upperCase，lowerCase 可以使用。
customStyleName
customStyl
自定义转换后的样式导入路径，输入是引入的成员，例如配置成 (member) => `my-lib/${member}` ，会将 import { foo } from 'bar' 转换成 import foo from 'my-lib/foo'。
-在使用 Rspack 构建时，不能使用函数配置，但可以使用 handlebars 模版字符串，对于上面的函数配置，在使用模版字符串时可以用以下模版代替 my-lib/{{ member }}，也可以使用一些内置帮助方法，例如 my-lib/{{ kebabCase member }} 来转换成 kebab-case 格式，除了 kebabCase 以外还有 camelCase，snakeCase，upperCase，lowerCase 可以使用。
+在使用 Rspack 构建时，不能使用函数配置，但可以使用 handlebars 模版字符串，对于上面的函数配置，在使用模版字符串时可以用以下模版代替 my-lib/{{ member }}，也可以使用一些内置帮助方法，例如 my-lib/{{ kebabCase member }} 来转换成 kebab-case 格式，除了 kebabCase 以外还有 camelCase，snakeCase，upperCase，lowerCase 可以使用。
source.preEntry
-
+;
s
在每个页面的入口文件前添加一段代码，这段代码会早于页面的代码执行，因此可以用于执行一些全局的代码逻辑，比如注入 polyfill、设置全局样式等。
添加单个脚本
首先创建一个 src/polyfill.ts 文件：
-
+
然后将 src/polyfill.ts 配置到 source.preEntry 上：
+};
重新运行编译并访问任意页面，可以看到 src/polyfill.ts 中的代码已经执行，并在 console 中输出了对应的内容。
添加全局样式
你也可以通过 source.preEntry 来配置全局样式，这段 CSS 代码会早于页面代码加载，比如引入一个 normalize.css 文件：
@@ -609,35 +609,35 @@ 添加
source: {
preEntry: './src/normalize.css',
},
-};
+};
添加多个脚本
你可以将 preEntry 设置为数组来添加多个脚本，它们会按数组顺序执行：
+};
source.resolveExtensionPrefix
-
+;
-用于为 resolve.extensions 添加统一的前缀。
+用于为 resolve.extensions 添加统一的前缀。
如果多个文件拥有相同的名称，但具有不同的文件后缀，Builder 会根据 extensions 数组的顺序进行识别，解析数组中第一个被识别的文件，并跳过其余文件。
-示例
+示例
下面是配置 .web 前缀的例子。
+};
配置完成后，extensions 数组会发生以下变化：
+const extensions = ['.web.js', '.js', '.web.ts' , '.ts', ...];
在代码中 import './foo' 时，会优先识别 foo.web.js 文件，再识别 foo.js 文件。
根据产物类型设置
当你同时构建多种类型的产物时，你可以为不同的产物类型设置不同的 extension 前缀。此时，你需要把 resolveExtensionPrefix 设置为一个对象，对象的 key 为对应的产物类型。
@@ -651,27 +651,27 @@
},
},
},
-};
+};
在代码中 import './foo' 时，对于 node 产物，会优先识别 foo.node.js 文件，而对于 web 产物，则会优先识别 foo.web.js 文件。
source.resolveMainFields
-
+;
+type ResolveMainFields = Fields | Record<BuilderTarget, Fields>;
-该配置项将决定你使用 package.json 哪个字段导入 npm 模块。对应 webpack 的 resolve.mainFields 配置。
-示例
+该配置项将决定你使用 package.json 哪个字段导入 npm 模块。对应 webpack 的 resolve.mainFields 配置。
+示例
-根据产物类型设置
+};
+根据产物类型设置
当你同时构建多种类型的产物时，你可以为不同的产物类型设置不同的 mainFields。此时，你需要把 resolveMainFields 设置为一个对象，对象的 key 为对应的产物类型。
比如为 web 和 node 设置不同的 mainFields：
目录
\ No newline at end of file
+};目录
\ No newline at end of file
diff --git a/modern-js/builder/api/config-tools.html b/modern-js/builder/api/config-tools.html
index 0b8c0a1b35..8c24531319 100644
--- a/modern-js/builder/api/config-tools.html
+++ b/modern-js/builder/api/config-tools.html
@@ -1,4 +1,4 @@
-Tools Config - Modern.js Builder
+Tools Config - Modern.js Builder
-Modern.js Builder Tools Config
+Modern.js Builder Tools Config
本章节描述了 Builder 中与底层工具有关的配置。
tools.autoprefixer
-
+;
// browserslist 取决于项目中的 browserslist 配置
// 以及 `output.overrideBrowserslist`(优先级更高) 配置
overrideBrowserslist: browserslist,
-}
-通过 tools.autoprefixer 可以修改 autoprefixer 的配置。
+}通过 tools.autoprefixer 可以修改 autoprefixer 的配置。
Object 类型
当 tools.autoprefixer 的值为 Object 类型时，会与默认配置通过 Object.assign 合并。比如：
+};
Function 类型
当 tools.autoprefixer 为 Function 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果。比如：
+};
tools.babel
-
+;
-通过 tools.babel 可以修改 babel-loader 的配置项。
+通过 tools.babel 可以修改 babel-loader 的配置项。
使用场景
请留意 tools.babel 在以下使用场景中的局限性：
-Function 类型
+Function 类型
当 tools.babel 为 Function 类型时，默认 Babel 配置会作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终的 babel-loader 配置。
+};tools.babel 函数的第二个参数提供了一些方便的工具函数，请继续阅读下方文档。
TIP以上示例仅作为参考，通常来说，你不需要手动配置 babel-plugin-import，因为 Builder 已经提供了更通用的 source.transformImport 配置。
-Object 类型
+Object 类型
当 tools.babel 的值为 Object 类型时，会与默认配置通过 Object.assign 浅合并。
CAUTIONObject.assign 是浅拷贝，会完全覆盖内置的 presets 或 plugins 数组，导致内置的 presets 或 plugins 失效，请在明确影响面的情况下再使用这种方式。
@@ -94,7 +94,7 @@ Object
],
},
},
-};
+};
工具函数
tools.babel 为 Function 类型时，第二个参数可用的工具函数如下:
addPlugins
@@ -117,7 +117,7 @@ addPlugins ]);
},
},
-};
+};
addPresets
addPresets addPresets(['@babel/preset-env']);
},
},
-};
+};
removePlugins
removePlugin
removePlugins('babel-plugin-import');
},
},
-};
+};
removePresets
removePreset
removePresets('@babel/preset-env');
},
},
-};
+};
modifyPresetEnvOptions
-
修改 @babel/preset-env 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+修改 @babel/preset-env 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+};
modifyPresetReactOptions
-修改 @babel/preset-react 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+修改 @babel/preset-react 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+};
addIncludes
-已废弃，请使用 source.include 代替，两者功能完全一致。
+已废弃，请使用 source.include 代替，两者功能完全一致。
addExcludes
-已废弃，请使用 source.exclude 代替，两者功能完全一致。
+已废弃，请使用 source.exclude 代替，两者功能完全一致。
调试 Babel 配置
-当你通过 tools.babel 修改 babel-loader 配置后，可以在 Builder 调试模式 下查看最终生成的配置。
+当你通过 tools.babel 修改 babel-loader 配置后，可以在 Builder 调试模式 下查看最终生成的配置。
首先通过 DEBUG=builder 参数开启调试模式：
+DEBUG=builder pnpm build
然后打开生成的 (webpack|rspack).config.web.js，搜索 babel-loader 关键词，即可看到完整的 babel-loader 配置内容。
tools.bundlerChain
-
+;
什么是 BundlerChain
Bundler chain 是 webpack chain 的子集，其中包含一部分 webpack chain API，你可以用它来同时修改 webpack 和 Rspack 的配置。
-通过 bundler chain 修改的配置，在 webpack 和 Rspack 构建时均可生效。需要注意的是，bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如，修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同)，或添加一个Rspack 兼容的 webpack 插件。
+通过 bundler chain 修改的配置，在 webpack 和 Rspack 构建时均可生效。需要注意的是，bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如，修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同)，或添加一个Rspack 兼容的 webpack 插件。
tools.bundlerChain 的执行时机早于 tools.webpackChain / tools.webpack / tools.rspack，因此会被其他几个配置中的修改所覆盖。
-工具集合
-env
-
-
-
通过 env 参数可以判断当前环境为 development、production 还是 test。比如：
-
-isProd
-
-
-通过 isProd 参数可以判断当前环境是否为 production。比如：
-
-target
-
-
-通过 target 参数可以判断当前构建的目标运行时环境。比如：
-
-isServer
-
-
-判断当前构建的目标运行时环境是否为 node，等价于 target === 'node'。
-
-isWebWorker
-
-
-判断当前构建的目标运行时环境是否为 web-worker，等价于 target === 'web-worker'。
-
-HtmlPlugin
-
-
-通过这个参数你可以拿到 webpack 或 Rspack 中的 HtmlPlugin 实例。
-
-CHAIN_ID
-Builder 中预先定义了一些常用的 Chain ID，你可以通过这些 ID 来定位到内置的 Rule 或 Plugin。
-TIP请留意，下列的一部分 Rule 或 Plugin 并不是默认存在的，当你开启特定配置项、或是注册某些插件后，它们才会被包含在 Rspack 或 webpack 配置中。
-比如，RULE.STYLUS 仅在注册了 Stylus 插件后才会存在。
-
-CHAIN_ID.RULE
-
-
-
-ID
-描述
-
-
-
-
-RULE.MJS处理 mjs 的规则
-
-
-RULE.CSS处理 css 的规则
-
-
-RULE.LESS处理 less 的规则
-
-
-RULE.SASS处理 sass 的规则
-
-
-RULE.STYLUS处理 stylus 的规则
-
-
-RULE.TOML处理 toml 的规则
-
-
-RULE.YAML处理 yaml 的规则
-
-
-RULE.WASM处理 wasm 的规则
-
-
-RULE.NODE处理 node 的规则
-
-
-
-CHAIN_ID.ONE_OF
-通过 ONE_OF.XXX 可以匹配到规则数组中的某一类规则。
-
-
-
-ID
-描述
-
-
-
-
-ONE_OF.SVG处理 SVG 的规则，在 data URI 和单独文件之间自动选择
-
-
-ONE_OF.SVG_URL处理 SVG 的规则，输出为单独文件
-
-
-ONE_OF.SVG_INLINE处理 SVG 的规则，作为 data URI 内联到 bundle 中
-
-
-ONE_OF.SVG_ASSETS处理 SVG 的规则，在 data URI 和单独文件之间自动选择
-
-
-
-CHAIN_ID.USE
-通过 USE.XXX 可以匹配到对应的 loader。
-
-
-
-ID
-描述
-
-
-
-
-USE.LESS对应 less-loader
-
-
-USE.SASS对应 sass-loader
-
-
-USE.STYLUS对应 stylus-loader
-
-
-USE.VUE对应 vue-loader
-
-
-USE.TOML对应 toml-loader
-
-
-USE.YAML对应 yaml-loader
-
-
-USE.NODE对应 node-loader
-
-
-USE.SVGR对应 @svgr/webpack
-
-
-USE.POSTCSS对应 postcss-loader
-
-
-USE.RESOLVE_URL_LOADER_FOR_SASS对应 resolve-url-loader
-
-
-
-CHAIN_ID.PLUGIN
-通过 PLUGIN.XXX 可以匹配到对应的 plugin。
-
-
-
-ID
-描述
-
-
-
-
-PLUGIN.HTML对应 HtmlPlugin，使用时需要拼接 entry 名称：${PLUGIN.HTML}-${entryName}
-
-
-PLUGIN.APP_ICON对应 AppIconPlugin
-
-
-PLUGIN.INLINE_HTML对应 InlineChunkHtmlPlugin
-
-
-PLUGIN.BUNDLE_ANALYZER对应 WebpackBundleAnalyzer
-
-
-PLUGIN.ASSETS_RETRY对应 Builder 中的 webpack 静态资源重试插件 WebpackAssetsRetryPlugin
-
-
-PLUGIN.VUE_LOADER_PLUGIN对应 VueLoaderPlugin
-
-
-PLUGIN.AUTO_SET_ROOT_SIZE对应 Builder 中的自动设置根字体大小插件 AutoSetRootSizePlugin
-
-
-
-CHAIN_ID.MINIMIZER
-通过 MINIMIZER.XXX 可以匹配到对应的压缩工具。
-
-
-
-ID
-描述
-
-
-
-
-MINIMIZER.JS对应 TerserWebpackPlugin 或 SwcJsMinimizerRspackPlugin
-
-
-MINIMIZER.CSS对应 CssMinimizerWebpackPlugin
-
-
-
-使用示例
-使用示例可参考：WebpackChain 使用示例。
+更多信息可参考 Rsbuild#tools.bundlerChain
tools.cssExtract
-
+;
chunkFilename: `${cssPath}/async/${cssFilename}`,
ignoreOrder: true,
},
-};
+};
-
通过 tools.cssExtract 可以更改 mini-css-extract-plugin 的配置。
-Object 类型
+通过 tools.cssExtract 可以更改 mini-css-extract-plugin 的配置。
+Object 类型
当此值为 Object 类型时，与默认配置通过 Object.assign 合并。比如：
-Function 类型
+};
+Function 类型
当此值为 Function 类型时，默认配置作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终配置。比如：
-更多配置细节可参考 mini-css-extract-plugin。
+};
+更多配置细节可参考 mini-css-extract-plugin。
tools.cssLoader
-
+;
-通过 tools.cssLoader 可以修改 css-loader 的配置项。默认配置如下:
+通过 tools.cssLoader 可以修改 css-loader 的配置项。默认配置如下:
-TIP在使用 Rspack 作为打包工具时，仅支持在 disableCssExtract 时使用该配置。
-修改 CSS Modules 相关配置，推荐使用 output.cssModules 配置项。
+}
+TIP在使用 Rspack 作为打包工具时，仅支持在 disableCssExtract 时使用该配置。
+修改 CSS Modules 相关配置，推荐使用 output.cssModules 配置项。
-Object 类型
+Object 类型
当此值为 Object 类型时，会与默认配置进行深层合并 (deep merge)。比如：
-Function 类型
+};
+Function 类型
当此值为 Function 类型时，默认配置作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终配置。比如：
+};
tools.devServer
-
+;
通过 tools.devServer 可以修改开发环境服务器的配置。
-TIPModern.js 中并没有直接使用 webpack-dev-server 或 @rspack/dev-server, 而是基于 webpack-dev-middleware 实现 DevServer。
+
TIPModern.js 中并没有直接使用 webpack-dev-server 或 @rspack/dev-server, 而是基于 webpack-dev-middleware 实现 DevServer。
选项
after
@@ -607,7 +331,7 @@ after ],
},
},
-};
+};
webpack-dev-server 使用 Express 作为服务端框架。Modern.js 中没有使用任何框架，上述中间件中 req 和 res 都是 Node 原生对象，因此 webpack-dev-server 的 Express 中间件不一定能直接在 Modern.js 中使用。
如果要迁移 webpack-dev-server 中使用的 Express 中间件，可以使用以下方式，将 Express app 作为中间件传入：
+};
before
before ],
},
},
-};
+};
client
client port?: string;
/** 指定要使用的 host */
host?: string;
-}
+}
@@ -667,7 +391,7 @@ client host: '',
// By default it is set to "location.protocol === 'https:' ? 'wss' : 'ws'""
protocol: '',
-};
+};
对应 HMR 客户端的配置，通常用于设置 HMR 对应的 WebSocket URL。
compress
@@ -682,21 +406,21 @@ compress compress: false,
},
},
-};
+};
devMiddleware
+}
-devMiddleware 配置项。当前配置是 webpack-dev-middleware 配置项的子集.
+}
+devMiddleware 配置项。当前配置是 webpack-dev-middleware 配置项的子集.
headers
headers },
},
},
-};
+};
historyApiFallback
history
historyApiFallback: true,
},
},
-};
-
更多选项和详细信息可参考 connect-history-api-fallback 文档。
+};
+更多选项和详细信息可参考 connect-history-api-fallback 文档。
hot
-是否开启 Hot Module Replacement 热更新能力。
+是否开启 Hot Module Replacement 热更新能力。
https
https },
},
},
-};
+};
liveReload
setupMidd
) => void;
},
) => void
->;
+>;
@@ -794,7 +518,7 @@ setupMidd
],
},
},
-};
+};
一些特殊场景需求可能需要使用服务器 API：
setupMidd
],
},
},
-};
+};
proxy
proxy },
},
},
-};
-此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
+};
+此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
如果你不想传递 /api，可以通过 pathRewrite 重写请求路径：
-DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
+};
+DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
DevServer Proxy 完整类型定义为：
+ | ProxyDetail;
除了 http-proxy-middleware 的选项外，还支持 bypass 和 context 两个配置项：
true 时：styl
style 配置项会被忽略。拼接引入路径为 ${libraryName}/${styleLibraryDirectory}/${member}。styles 时：c
t
customName
自定义转换后的导入路径，输入是引入的成员，例如配置成 (member) => `my-lib/${member}` ，会将 import { foo } from 'bar' 转换成 import foo from 'my-lib/foo'。
-在使用 Rspack 构建时，不能使用函数配置，但可以使用 handlebars 模版字符串，对于上面的函数配置，在使用模版字符串时可以用以下模版代替 my-lib/{{ member }}，也可以使用一些内置帮助方法，例如 my-lib/{{ kebabCase member }} 来转换成 kebab-case 格式，除了 kebabCase 以外还有 camelCase，snakeCase，upperCase，lowerCase 可以使用。
+在使用 Rspack 构建时，不能使用函数配置，但可以使用 handlebars 模版字符串，对于上面的函数配置，在使用模版字符串时可以用以下模版代替 my-lib/{{ member }}，也可以使用一些内置帮助方法，例如 my-lib/{{ kebabCase member }} 来转换成 kebab-case 格式，除了 kebabCase 以外还有 camelCase，snakeCase，upperCase，lowerCase 可以使用。
customStyleName
customStyl
自定义转换后的样式导入路径，输入是引入的成员，例如配置成 (member) => `my-lib/${member}` ，会将 import { foo } from 'bar' 转换成 import foo from 'my-lib/foo'。
-在使用 Rspack 构建时，不能使用函数配置，但可以使用 handlebars 模版字符串，对于上面的函数配置，在使用模版字符串时可以用以下模版代替 my-lib/{{ member }}，也可以使用一些内置帮助方法，例如 my-lib/{{ kebabCase member }} 来转换成 kebab-case 格式，除了 kebabCase 以外还有 camelCase，snakeCase，upperCase，lowerCase 可以使用。
+在使用 Rspack 构建时，不能使用函数配置，但可以使用 handlebars 模版字符串，对于上面的函数配置，在使用模版字符串时可以用以下模版代替 my-lib/{{ member }}，也可以使用一些内置帮助方法，例如 my-lib/{{ kebabCase member }} 来转换成 kebab-case 格式，除了 kebabCase 以外还有 camelCase，snakeCase，upperCase，lowerCase 可以使用。
source.preEntry
-
+;
s
在每个页面的入口文件前添加一段代码，这段代码会早于页面的代码执行，因此可以用于执行一些全局的代码逻辑，比如注入 polyfill、设置全局样式等。
添加单个脚本
首先创建一个 src/polyfill.ts 文件：
-
+
然后将 src/polyfill.ts 配置到 source.preEntry 上：
+};
重新运行编译并访问任意页面，可以看到 src/polyfill.ts 中的代码已经执行，并在 console 中输出了对应的内容。
添加全局样式
你也可以通过 source.preEntry 来配置全局样式，这段 CSS 代码会早于页面代码加载，比如引入一个 normalize.css 文件：
@@ -609,35 +609,35 @@ 添加
source: {
preEntry: './src/normalize.css',
},
-};
+};
添加多个脚本
你可以将 preEntry 设置为数组来添加多个脚本，它们会按数组顺序执行：
+};
source.resolveExtensionPrefix
-
+;
-用于为 resolve.extensions 添加统一的前缀。
+用于为 resolve.extensions 添加统一的前缀。
如果多个文件拥有相同的名称，但具有不同的文件后缀，Builder 会根据 extensions 数组的顺序进行识别，解析数组中第一个被识别的文件，并跳过其余文件。
-示例
+示例
下面是配置 .web 前缀的例子。
+};
配置完成后，extensions 数组会发生以下变化：
+const extensions = ['.web.js', '.js', '.web.ts' , '.ts', ...];
在代码中 import './foo' 时，会优先识别 foo.web.js 文件，再识别 foo.js 文件。
根据产物类型设置
当你同时构建多种类型的产物时，你可以为不同的产物类型设置不同的 extension 前缀。此时，你需要把 resolveExtensionPrefix 设置为一个对象，对象的 key 为对应的产物类型。
@@ -651,27 +651,27 @@
},
},
},
-};
+};
在代码中 import './foo' 时，对于 node 产物，会优先识别 foo.node.js 文件，而对于 web 产物，则会优先识别 foo.web.js 文件。
source.resolveMainFields
-
+;
+type ResolveMainFields = Fields | Record<BuilderTarget, Fields>;
-该配置项将决定你使用 package.json 哪个字段导入 npm 模块。对应 webpack 的 resolve.mainFields 配置。
-示例
+该配置项将决定你使用 package.json 哪个字段导入 npm 模块。对应 webpack 的 resolve.mainFields 配置。
+示例
-根据产物类型设置
+};
+根据产物类型设置
当你同时构建多种类型的产物时，你可以为不同的产物类型设置不同的 mainFields。此时，你需要把 resolveMainFields 设置为一个对象，对象的 key 为对应的产物类型。
比如为 web 和 node 设置不同的 mainFields：
目录
\ No newline at end of file
+};目录
\ No newline at end of file
diff --git a/modern-js/builder/api/config-tools.html b/modern-js/builder/api/config-tools.html
index 0b8c0a1b35..8c24531319 100644
--- a/modern-js/builder/api/config-tools.html
+++ b/modern-js/builder/api/config-tools.html
@@ -1,4 +1,4 @@
-Tools Config - Modern.js Builder
+Tools Config - Modern.js Builder
-Modern.js Builder Tools Config
+Modern.js Builder Tools Config
本章节描述了 Builder 中与底层工具有关的配置。
tools.autoprefixer
-
+;
// browserslist 取决于项目中的 browserslist 配置
// 以及 `output.overrideBrowserslist`(优先级更高) 配置
overrideBrowserslist: browserslist,
-}
-通过 tools.autoprefixer 可以修改 autoprefixer 的配置。
+}通过 tools.autoprefixer 可以修改 autoprefixer 的配置。
Object 类型
当 tools.autoprefixer 的值为 Object 类型时，会与默认配置通过 Object.assign 合并。比如：
+};
Function 类型
当 tools.autoprefixer 为 Function 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果。比如：
+};
tools.babel
-
+;
-通过 tools.babel 可以修改 babel-loader 的配置项。
+通过 tools.babel 可以修改 babel-loader 的配置项。
使用场景
请留意 tools.babel 在以下使用场景中的局限性：
-Function 类型
+Function 类型
当 tools.babel 为 Function 类型时，默认 Babel 配置会作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终的 babel-loader 配置。
+};tools.babel 函数的第二个参数提供了一些方便的工具函数，请继续阅读下方文档。
TIP以上示例仅作为参考，通常来说，你不需要手动配置 babel-plugin-import，因为 Builder 已经提供了更通用的 source.transformImport 配置。
-Object 类型
+Object 类型
当 tools.babel 的值为 Object 类型时，会与默认配置通过 Object.assign 浅合并。
CAUTIONObject.assign 是浅拷贝，会完全覆盖内置的 presets 或 plugins 数组，导致内置的 presets 或 plugins 失效，请在明确影响面的情况下再使用这种方式。
@@ -94,7 +94,7 @@ Object
],
},
},
-};
+};
工具函数
tools.babel 为 Function 类型时，第二个参数可用的工具函数如下:
addPlugins
@@ -117,7 +117,7 @@ addPlugins ]);
},
},
-};
+};
addPresets
addPresets addPresets(['@babel/preset-env']);
},
},
-};
+};
removePlugins
removePlugin
removePlugins('babel-plugin-import');
},
},
-};
+};
removePresets
removePreset
removePresets('@babel/preset-env');
},
},
-};
+};
modifyPresetEnvOptions
-
修改 @babel/preset-env 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+修改 @babel/preset-env 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+};
modifyPresetReactOptions
-修改 @babel/preset-react 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+修改 @babel/preset-react 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+};
addIncludes
-已废弃，请使用 source.include 代替，两者功能完全一致。
+已废弃，请使用 source.include 代替，两者功能完全一致。
addExcludes
-已废弃，请使用 source.exclude 代替，两者功能完全一致。
+已废弃，请使用 source.exclude 代替，两者功能完全一致。
调试 Babel 配置
-当你通过 tools.babel 修改 babel-loader 配置后，可以在 Builder 调试模式 下查看最终生成的配置。
+当你通过 tools.babel 修改 babel-loader 配置后，可以在 Builder 调试模式 下查看最终生成的配置。
首先通过 DEBUG=builder 参数开启调试模式：
+DEBUG=builder pnpm build
然后打开生成的 (webpack|rspack).config.web.js，搜索 babel-loader 关键词，即可看到完整的 babel-loader 配置内容。
tools.bundlerChain
-
+;
什么是 BundlerChain
Bundler chain 是 webpack chain 的子集，其中包含一部分 webpack chain API，你可以用它来同时修改 webpack 和 Rspack 的配置。
-通过 bundler chain 修改的配置，在 webpack 和 Rspack 构建时均可生效。需要注意的是，bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如，修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同)，或添加一个Rspack 兼容的 webpack 插件。
+通过 bundler chain 修改的配置，在 webpack 和 Rspack 构建时均可生效。需要注意的是，bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如，修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同)，或添加一个Rspack 兼容的 webpack 插件。
tools.bundlerChain 的执行时机早于 tools.webpackChain / tools.webpack / tools.rspack，因此会被其他几个配置中的修改所覆盖。
-工具集合
-env
-
-
-
通过 env 参数可以判断当前环境为 development、production 还是 test。比如：
-
-isProd
-
-
-通过 isProd 参数可以判断当前环境是否为 production。比如：
-
-target
-
-
-通过 target 参数可以判断当前构建的目标运行时环境。比如：
-
-isServer
-
-
-判断当前构建的目标运行时环境是否为 node，等价于 target === 'node'。
-
-isWebWorker
-
-
-判断当前构建的目标运行时环境是否为 web-worker，等价于 target === 'web-worker'。
-
-HtmlPlugin
-
-
-通过这个参数你可以拿到 webpack 或 Rspack 中的 HtmlPlugin 实例。
-
-CHAIN_ID
-Builder 中预先定义了一些常用的 Chain ID，你可以通过这些 ID 来定位到内置的 Rule 或 Plugin。
-TIP请留意，下列的一部分 Rule 或 Plugin 并不是默认存在的，当你开启特定配置项、或是注册某些插件后，它们才会被包含在 Rspack 或 webpack 配置中。
-比如，RULE.STYLUS 仅在注册了 Stylus 插件后才会存在。
-
-CHAIN_ID.RULE
-
-
-
-ID
-描述
-
-
-
-
-RULE.MJS处理 mjs 的规则
-
-
-RULE.CSS处理 css 的规则
-
-
-RULE.LESS处理 less 的规则
-
-
-RULE.SASS处理 sass 的规则
-
-
-RULE.STYLUS处理 stylus 的规则
-
-
-RULE.TOML处理 toml 的规则
-
-
-RULE.YAML处理 yaml 的规则
-
-
-RULE.WASM处理 wasm 的规则
-
-
-RULE.NODE处理 node 的规则
-
-
-
-CHAIN_ID.ONE_OF
-通过 ONE_OF.XXX 可以匹配到规则数组中的某一类规则。
-
-
-
-ID
-描述
-
-
-
-
-ONE_OF.SVG处理 SVG 的规则，在 data URI 和单独文件之间自动选择
-
-
-ONE_OF.SVG_URL处理 SVG 的规则，输出为单独文件
-
-
-ONE_OF.SVG_INLINE处理 SVG 的规则，作为 data URI 内联到 bundle 中
-
-
-ONE_OF.SVG_ASSETS处理 SVG 的规则，在 data URI 和单独文件之间自动选择
-
-
-
-CHAIN_ID.USE
-通过 USE.XXX 可以匹配到对应的 loader。
-
-
-
-ID
-描述
-
-
-
-
-USE.LESS对应 less-loader
-
-
-USE.SASS对应 sass-loader
-
-
-USE.STYLUS对应 stylus-loader
-
-
-USE.VUE对应 vue-loader
-
-
-USE.TOML对应 toml-loader
-
-
-USE.YAML对应 yaml-loader
-
-
-USE.NODE对应 node-loader
-
-
-USE.SVGR对应 @svgr/webpack
-
-
-USE.POSTCSS对应 postcss-loader
-
-
-USE.RESOLVE_URL_LOADER_FOR_SASS对应 resolve-url-loader
-
-
-
-CHAIN_ID.PLUGIN
-通过 PLUGIN.XXX 可以匹配到对应的 plugin。
-
-
-
-ID
-描述
-
-
-
-
-PLUGIN.HTML对应 HtmlPlugin，使用时需要拼接 entry 名称：${PLUGIN.HTML}-${entryName}
-
-
-PLUGIN.APP_ICON对应 AppIconPlugin
-
-
-PLUGIN.INLINE_HTML对应 InlineChunkHtmlPlugin
-
-
-PLUGIN.BUNDLE_ANALYZER对应 WebpackBundleAnalyzer
-
-
-PLUGIN.ASSETS_RETRY对应 Builder 中的 webpack 静态资源重试插件 WebpackAssetsRetryPlugin
-
-
-PLUGIN.VUE_LOADER_PLUGIN对应 VueLoaderPlugin
-
-
-PLUGIN.AUTO_SET_ROOT_SIZE对应 Builder 中的自动设置根字体大小插件 AutoSetRootSizePlugin
-
-
-
-CHAIN_ID.MINIMIZER
-通过 MINIMIZER.XXX 可以匹配到对应的压缩工具。
-
-
-
-ID
-描述
-
-
-
-
-MINIMIZER.JS对应 TerserWebpackPlugin 或 SwcJsMinimizerRspackPlugin
-
-
-MINIMIZER.CSS对应 CssMinimizerWebpackPlugin
-
-
-
-使用示例
-使用示例可参考：WebpackChain 使用示例。
+更多信息可参考 Rsbuild#tools.bundlerChain
tools.cssExtract
-
+;
chunkFilename: `${cssPath}/async/${cssFilename}`,
ignoreOrder: true,
},
-};
+};
-
通过 tools.cssExtract 可以更改 mini-css-extract-plugin 的配置。
-Object 类型
+通过 tools.cssExtract 可以更改 mini-css-extract-plugin 的配置。
+Object 类型
当此值为 Object 类型时，与默认配置通过 Object.assign 合并。比如：
-Function 类型
+};
+Function 类型
当此值为 Function 类型时，默认配置作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终配置。比如：
-更多配置细节可参考 mini-css-extract-plugin。
+};
+更多配置细节可参考 mini-css-extract-plugin。
tools.cssLoader
-
+;
-通过 tools.cssLoader 可以修改 css-loader 的配置项。默认配置如下:
+通过 tools.cssLoader 可以修改 css-loader 的配置项。默认配置如下:
-TIP在使用 Rspack 作为打包工具时，仅支持在 disableCssExtract 时使用该配置。
-修改 CSS Modules 相关配置，推荐使用 output.cssModules 配置项。
+}
+TIP在使用 Rspack 作为打包工具时，仅支持在 disableCssExtract 时使用该配置。
+修改 CSS Modules 相关配置，推荐使用 output.cssModules 配置项。
-Object 类型
+Object 类型
当此值为 Object 类型时，会与默认配置进行深层合并 (deep merge)。比如：
-Function 类型
+};
+Function 类型
当此值为 Function 类型时，默认配置作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终配置。比如：
+};
tools.devServer
-
+;
通过 tools.devServer 可以修改开发环境服务器的配置。
-TIPModern.js 中并没有直接使用 webpack-dev-server 或 @rspack/dev-server, 而是基于 webpack-dev-middleware 实现 DevServer。
+
TIPModern.js 中并没有直接使用 webpack-dev-server 或 @rspack/dev-server, 而是基于 webpack-dev-middleware 实现 DevServer。
选项
after
@@ -607,7 +331,7 @@ after ],
},
},
-};
+};
webpack-dev-server 使用 Express 作为服务端框架。Modern.js 中没有使用任何框架，上述中间件中 req 和 res 都是 Node 原生对象，因此 webpack-dev-server 的 Express 中间件不一定能直接在 Modern.js 中使用。
如果要迁移 webpack-dev-server 中使用的 Express 中间件，可以使用以下方式，将 Express app 作为中间件传入：
+};
before
before ],
},
},
-};
+};
client
client port?: string;
/** 指定要使用的 host */
host?: string;
-}
+}
@@ -667,7 +391,7 @@ client host: '',
// By default it is set to "location.protocol === 'https:' ? 'wss' : 'ws'""
protocol: '',
-};
+};
对应 HMR 客户端的配置，通常用于设置 HMR 对应的 WebSocket URL。
compress
@@ -682,21 +406,21 @@ compress compress: false,
},
},
-};
+};
devMiddleware
+}
-devMiddleware 配置项。当前配置是 webpack-dev-middleware 配置项的子集.
+}
+devMiddleware 配置项。当前配置是 webpack-dev-middleware 配置项的子集.
headers
headers },
},
},
-};
+};
historyApiFallback
history
historyApiFallback: true,
},
},
-};
-
更多选项和详细信息可参考 connect-history-api-fallback 文档。
+};
+更多选项和详细信息可参考 connect-history-api-fallback 文档。
hot
-是否开启 Hot Module Replacement 热更新能力。
+是否开启 Hot Module Replacement 热更新能力。
https
https },
},
},
-};
+};
liveReload
setupMidd
) => void;
},
) => void
->;
+>;
@@ -794,7 +518,7 @@ setupMidd
],
},
},
-};
+};
一些特殊场景需求可能需要使用服务器 API：
setupMidd
],
},
},
-};
+};
proxy
proxy },
},
},
-};
-此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
+};
+此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
如果你不想传递 /api，可以通过 pathRewrite 重写请求路径：
-DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
+};
+DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
DevServer Proxy 完整类型定义为：
+ | ProxyDetail;
除了 http-proxy-middleware 的选项外，还支持 bypass 和 context 两个配置项：
(member) => `my-lib/${member}` ，会将 import { foo } from 'bar' 转换成 import foo from 'my-lib/foo'。my-lib/{{ member }}，也可以使用一些内置帮助方法，例如 my-lib/{{ kebabCase member }} 来转换成 kebab-case 格式，除了 kebabCase 以外还有 camelCase，snakeCase，upperCase，lowerCase 可以使用。my-lib/{{ member }}，也可以使用一些内置帮助方法，例如 my-lib/{{ kebabCase member }} 来转换成 kebab-case 格式，除了 kebabCase 以外还有 camelCase，snakeCase，upperCase，lowerCase 可以使用。customStyl
(member) => `my-lib/${member}` ，会将 import { foo } from 'bar' 转换成 import foo from 'my-lib/foo'。my-lib/{{ member }}，也可以使用一些内置帮助方法，例如 my-lib/{{ kebabCase member }} 来转换成 kebab-case 格式，除了 kebabCase 以外还有 camelCase，snakeCase，upperCase，lowerCase 可以使用。my-lib/{{ member }}，也可以使用一些内置帮助方法，例如 my-lib/{{ kebabCase member }} 来转换成 kebab-case 格式，除了 kebabCase 以外还有 camelCase，snakeCase，upperCase，lowerCase 可以使用。s
在每个页面的入口文件前添加一段代码，这段代码会早于页面的代码执行，因此可以用于执行一些全局的代码逻辑，比如注入 polyfill、设置全局样式等。
添加单个脚本
首先创建一个 src/polyfill.ts 文件：
然后将 src/polyfill.ts 配置到 source.preEntry 上：
重新运行编译并访问任意页面，可以看到 src/polyfill.ts 中的代码已经执行，并在 console 中输出了对应的内容。
添加全局样式
你也可以通过 source.preEntry 来配置全局样式，这段 CSS 代码会早于页面代码加载，比如引入一个 normalize.css 文件：
添加
source: {
preEntry: './src/normalize.css',
},
-};
+};
添加多个脚本
你可以将 preEntry 设置为数组来添加多个脚本，它们会按数组顺序执行：
source.resolveExtensionPrefix
- +;
用于为 resolve.extensions 添加统一的前缀。
+用于为 resolve.extensions 添加统一的前缀。
如果多个文件拥有相同的名称，但具有不同的文件后缀，Builder 会根据 extensions 数组的顺序进行识别，解析数组中第一个被识别的文件，并跳过其余文件。
-示例
+示例
下面是配置 .web 前缀的例子。
配置完成后，extensions 数组会发生以下变化：
在代码中 import './foo' 时，会优先识别 foo.web.js 文件，再识别 foo.js 文件。
根据产物类型设置
当你同时构建多种类型的产物时，你可以为不同的产物类型设置不同的 extension 前缀。此时，你需要把 resolveExtensionPrefix 设置为一个对象，对象的 key 为对应的产物类型。
}, }, }, -}; +};
在代码中 import './foo' 时，对于 node 产物，会优先识别 foo.node.js 文件，而对于 web 产物，则会优先识别 foo.web.js 文件。
source.resolveMainFields
- +;
该配置项将决定你使用 package.json 哪个字段导入 npm 模块。对应 webpack 的 resolve.mainFields 配置。
示例
+该配置项将决定你使用 package.json 哪个字段导入 npm 模块。对应 webpack 的 resolve.mainFields 配置。
示例
根据产物类型设置
+}; +根据产物类型设置
当你同时构建多种类型的产物时，你可以为不同的产物类型设置不同的 mainFields。此时，你需要把 resolveMainFields 设置为一个对象，对象的 key 为对应的产物类型。
比如为 web 和 node 设置不同的 mainFields：
Tools Config
+Tools Config
本章节描述了 Builder 中与底层工具有关的配置。
tools.autoprefixer
- +;
// browserslist 取决于项目中的 browserslist 配置 // 以及 `output.overrideBrowserslist`(优先级更高) 配置 overrideBrowserslist: browserslist, -}
通过 tools.autoprefixer 可以修改 autoprefixer 的配置。
通过 tools.autoprefixer 可以修改 autoprefixer 的配置。
Object 类型
当 tools.autoprefixer 的值为 Object 类型时，会与默认配置通过 Object.assign 合并。比如：
Function 类型
当 tools.autoprefixer 为 Function 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果。比如：
tools.babel
- +;
通过 tools.babel 可以修改 babel-loader 的配置项。
通过 tools.babel 可以修改 babel-loader 的配置项。
使用场景
请留意 tools.babel 在以下使用场景中的局限性：
Function 类型
+Function 类型
当 tools.babel 为 Function 类型时，默认 Babel 配置会作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终的 babel-loader 配置。
tools.babel 函数的第二个参数提供了一些方便的工具函数，请继续阅读下方文档。
以上示例仅作为参考，通常来说，你不需要手动配置 babel-plugin-import，因为 Builder 已经提供了更通用的 source.transformImport 配置。
Object 类型
+Object 类型
当 tools.babel 的值为 Object 类型时，会与默认配置通过 Object.assign 浅合并。
Object.assign 是浅拷贝，会完全覆盖内置的 presets 或 plugins 数组，导致内置的 presets 或 plugins 失效，请在明确影响面的情况下再使用这种方式。
Object
],
},
},
-};
+};
工具函数
tools.babel 为 Function 类型时，第二个参数可用的工具函数如下:
addPlugins
@@ -117,7 +117,7 @@addPlugins ]);
},
},
-};
+};
addPresets
addPresets addPresets(['@babel/preset-env']);
},
},
-};
+};
removePlugins
removePlugin
removePlugins('babel-plugin-import');
},
},
-};
+};
removePresets
removePreset
removePresets('@babel/preset-env');
},
},
-};
+};
modifyPresetEnvOptions
-
修改 @babel/preset-env 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+修改 @babel/preset-env 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+};
modifyPresetReactOptions
-修改 @babel/preset-react 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+修改 @babel/preset-react 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+};
addIncludes
-已废弃，请使用 source.include 代替，两者功能完全一致。
+已废弃，请使用 source.include 代替，两者功能完全一致。
addExcludes
-已废弃，请使用 source.exclude 代替，两者功能完全一致。
+已废弃，请使用 source.exclude 代替，两者功能完全一致。
调试 Babel 配置
-当你通过 tools.babel 修改 babel-loader 配置后，可以在 Builder 调试模式 下查看最终生成的配置。
+当你通过 tools.babel 修改 babel-loader 配置后，可以在 Builder 调试模式 下查看最终生成的配置。
首先通过 DEBUG=builder 参数开启调试模式：
+DEBUG=builder pnpm build
然后打开生成的 (webpack|rspack).config.web.js，搜索 babel-loader 关键词，即可看到完整的 babel-loader 配置内容。
tools.bundlerChain
-
+;
什么是 BundlerChain
Bundler chain 是 webpack chain 的子集，其中包含一部分 webpack chain API，你可以用它来同时修改 webpack 和 Rspack 的配置。
-通过 bundler chain 修改的配置，在 webpack 和 Rspack 构建时均可生效。需要注意的是，bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如，修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同)，或添加一个Rspack 兼容的 webpack 插件。
+通过 bundler chain 修改的配置，在 webpack 和 Rspack 构建时均可生效。需要注意的是，bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如，修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同)，或添加一个Rspack 兼容的 webpack 插件。
tools.bundlerChain 的执行时机早于 tools.webpackChain / tools.webpack / tools.rspack，因此会被其他几个配置中的修改所覆盖。
-工具集合
-env
-
-
-
通过 env 参数可以判断当前环境为 development、production 还是 test。比如：
-
-isProd
-
-
-通过 isProd 参数可以判断当前环境是否为 production。比如：
-
-target
-
-
-通过 target 参数可以判断当前构建的目标运行时环境。比如：
-
-isServer
-
-
-判断当前构建的目标运行时环境是否为 node，等价于 target === 'node'。
-
-isWebWorker
-
-
-判断当前构建的目标运行时环境是否为 web-worker，等价于 target === 'web-worker'。
-
-HtmlPlugin
-
-
-通过这个参数你可以拿到 webpack 或 Rspack 中的 HtmlPlugin 实例。
-
-CHAIN_ID
-Builder 中预先定义了一些常用的 Chain ID，你可以通过这些 ID 来定位到内置的 Rule 或 Plugin。
-TIP请留意，下列的一部分 Rule 或 Plugin 并不是默认存在的，当你开启特定配置项、或是注册某些插件后，它们才会被包含在 Rspack 或 webpack 配置中。
-比如，RULE.STYLUS 仅在注册了 Stylus 插件后才会存在。
-
-CHAIN_ID.RULE
-
-
-
-ID
-描述
-
-
-
-
-RULE.MJS处理 mjs 的规则
-
-
-RULE.CSS处理 css 的规则
-
-
-RULE.LESS处理 less 的规则
-
-
-RULE.SASS处理 sass 的规则
-
-
-RULE.STYLUS处理 stylus 的规则
-
-
-RULE.TOML处理 toml 的规则
-
-
-RULE.YAML处理 yaml 的规则
-
-
-RULE.WASM处理 wasm 的规则
-
-
-RULE.NODE处理 node 的规则
-
-
-
-CHAIN_ID.ONE_OF
-通过 ONE_OF.XXX 可以匹配到规则数组中的某一类规则。
-
-
-
-ID
-描述
-
-
-
-
-ONE_OF.SVG处理 SVG 的规则，在 data URI 和单独文件之间自动选择
-
-
-ONE_OF.SVG_URL处理 SVG 的规则，输出为单独文件
-
-
-ONE_OF.SVG_INLINE处理 SVG 的规则，作为 data URI 内联到 bundle 中
-
-
-ONE_OF.SVG_ASSETS处理 SVG 的规则，在 data URI 和单独文件之间自动选择
-
-
-
-CHAIN_ID.USE
-通过 USE.XXX 可以匹配到对应的 loader。
-
-
-
-ID
-描述
-
-
-
-
-USE.LESS对应 less-loader
-
-
-USE.SASS对应 sass-loader
-
-
-USE.STYLUS对应 stylus-loader
-
-
-USE.VUE对应 vue-loader
-
-
-USE.TOML对应 toml-loader
-
-
-USE.YAML对应 yaml-loader
-
-
-USE.NODE对应 node-loader
-
-
-USE.SVGR对应 @svgr/webpack
-
-
-USE.POSTCSS对应 postcss-loader
-
-
-USE.RESOLVE_URL_LOADER_FOR_SASS对应 resolve-url-loader
-
-
-
-CHAIN_ID.PLUGIN
-通过 PLUGIN.XXX 可以匹配到对应的 plugin。
-
-
-
-ID
-描述
-
-
-
-
-PLUGIN.HTML对应 HtmlPlugin，使用时需要拼接 entry 名称：${PLUGIN.HTML}-${entryName}
-
-
-PLUGIN.APP_ICON对应 AppIconPlugin
-
-
-PLUGIN.INLINE_HTML对应 InlineChunkHtmlPlugin
-
-
-PLUGIN.BUNDLE_ANALYZER对应 WebpackBundleAnalyzer
-
-
-PLUGIN.ASSETS_RETRY对应 Builder 中的 webpack 静态资源重试插件 WebpackAssetsRetryPlugin
-
-
-PLUGIN.VUE_LOADER_PLUGIN对应 VueLoaderPlugin
-
-
-PLUGIN.AUTO_SET_ROOT_SIZE对应 Builder 中的自动设置根字体大小插件 AutoSetRootSizePlugin
-
-
-
-CHAIN_ID.MINIMIZER
-通过 MINIMIZER.XXX 可以匹配到对应的压缩工具。
-
-
-
-ID
-描述
-
-
-
-
-MINIMIZER.JS对应 TerserWebpackPlugin 或 SwcJsMinimizerRspackPlugin
-
-
-MINIMIZER.CSS对应 CssMinimizerWebpackPlugin
-
-
-
-使用示例
-使用示例可参考：WebpackChain 使用示例。
+更多信息可参考 Rsbuild#tools.bundlerChain
tools.cssExtract
-
+;
chunkFilename: `${cssPath}/async/${cssFilename}`,
ignoreOrder: true,
},
-};
+};
-
通过 tools.cssExtract 可以更改 mini-css-extract-plugin 的配置。
-Object 类型
+通过 tools.cssExtract 可以更改 mini-css-extract-plugin 的配置。
+Object 类型
当此值为 Object 类型时，与默认配置通过 Object.assign 合并。比如：
-Function 类型
+};
+Function 类型
当此值为 Function 类型时，默认配置作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终配置。比如：
-更多配置细节可参考 mini-css-extract-plugin。
+};
+更多配置细节可参考 mini-css-extract-plugin。
tools.cssLoader
-
+;
-通过 tools.cssLoader 可以修改 css-loader 的配置项。默认配置如下:
+通过 tools.cssLoader 可以修改 css-loader 的配置项。默认配置如下:
-TIP在使用 Rspack 作为打包工具时，仅支持在 disableCssExtract 时使用该配置。
-修改 CSS Modules 相关配置，推荐使用 output.cssModules 配置项。
+}
+TIP在使用 Rspack 作为打包工具时，仅支持在 disableCssExtract 时使用该配置。
+修改 CSS Modules 相关配置，推荐使用 output.cssModules 配置项。
-Object 类型
+Object 类型
当此值为 Object 类型时，会与默认配置进行深层合并 (deep merge)。比如：
-Function 类型
+};
+Function 类型
当此值为 Function 类型时，默认配置作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终配置。比如：
+};
tools.devServer
-
+;
通过 tools.devServer 可以修改开发环境服务器的配置。
-TIPModern.js 中并没有直接使用 webpack-dev-server 或 @rspack/dev-server, 而是基于 webpack-dev-middleware 实现 DevServer。
+
TIPModern.js 中并没有直接使用 webpack-dev-server 或 @rspack/dev-server, 而是基于 webpack-dev-middleware 实现 DevServer。
选项
after
@@ -607,7 +331,7 @@ after ],
},
},
-};
+};
webpack-dev-server 使用 Express 作为服务端框架。Modern.js 中没有使用任何框架，上述中间件中 req 和 res 都是 Node 原生对象，因此 webpack-dev-server 的 Express 中间件不一定能直接在 Modern.js 中使用。
如果要迁移 webpack-dev-server 中使用的 Express 中间件，可以使用以下方式，将 Express app 作为中间件传入：
+};
before
before ],
},
},
-};
+};
client
client port?: string;
/** 指定要使用的 host */
host?: string;
-}
+}
@@ -667,7 +391,7 @@ client host: '',
// By default it is set to "location.protocol === 'https:' ? 'wss' : 'ws'""
protocol: '',
-};
+};
对应 HMR 客户端的配置，通常用于设置 HMR 对应的 WebSocket URL。
compress
@@ -682,21 +406,21 @@ compress compress: false,
},
},
-};
+};
devMiddleware
+}
-devMiddleware 配置项。当前配置是 webpack-dev-middleware 配置项的子集.
+}
+devMiddleware 配置项。当前配置是 webpack-dev-middleware 配置项的子集.
headers
headers },
},
},
-};
+};
historyApiFallback
history
historyApiFallback: true,
},
},
-};
-
更多选项和详细信息可参考 connect-history-api-fallback 文档。
+};
+更多选项和详细信息可参考 connect-history-api-fallback 文档。
hot
-是否开启 Hot Module Replacement 热更新能力。
+是否开启 Hot Module Replacement 热更新能力。
https
https },
},
},
-};
+};
liveReload
setupMidd
) => void;
},
) => void
->;
+>;
@@ -794,7 +518,7 @@ setupMidd
],
},
},
-};
+};
一些特殊场景需求可能需要使用服务器 API：
setupMidd
],
},
},
-};
+};
proxy
proxy },
},
},
-};
-此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
+};
+此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
如果你不想传递 /api，可以通过 pathRewrite 重写请求路径：
-DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
+};
+DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
DevServer Proxy 完整类型定义为：
+ | ProxyDetail;
除了 http-proxy-middleware 的选项外，还支持 bypass 和 context 两个配置项：
addPresets addPresets(['@babel/preset-env']);
},
},
-};
+};
removePlugins
removePlugin
removePlugins('babel-plugin-import');
},
},
-};
+};
removePresets
removePreset
removePresets('@babel/preset-env');
},
},
-};
+};
modifyPresetEnvOptions
-
修改 @babel/preset-env 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+修改 @babel/preset-env 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+};
modifyPresetReactOptions
-修改 @babel/preset-react 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+修改 @babel/preset-react 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+};
addIncludes
-已废弃，请使用 source.include 代替，两者功能完全一致。
+已废弃，请使用 source.include 代替，两者功能完全一致。
addExcludes
-已废弃，请使用 source.exclude 代替，两者功能完全一致。
+已废弃，请使用 source.exclude 代替，两者功能完全一致。
调试 Babel 配置
-当你通过 tools.babel 修改 babel-loader 配置后，可以在 Builder 调试模式 下查看最终生成的配置。
+当你通过 tools.babel 修改 babel-loader 配置后，可以在 Builder 调试模式 下查看最终生成的配置。
首先通过 DEBUG=builder 参数开启调试模式：
+DEBUG=builder pnpm build
然后打开生成的 (webpack|rspack).config.web.js，搜索 babel-loader 关键词，即可看到完整的 babel-loader 配置内容。
tools.bundlerChain
-
+;
什么是 BundlerChain
Bundler chain 是 webpack chain 的子集，其中包含一部分 webpack chain API，你可以用它来同时修改 webpack 和 Rspack 的配置。
-通过 bundler chain 修改的配置，在 webpack 和 Rspack 构建时均可生效。需要注意的是，bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如，修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同)，或添加一个Rspack 兼容的 webpack 插件。
+通过 bundler chain 修改的配置，在 webpack 和 Rspack 构建时均可生效。需要注意的是，bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如，修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同)，或添加一个Rspack 兼容的 webpack 插件。
tools.bundlerChain 的执行时机早于 tools.webpackChain / tools.webpack / tools.rspack，因此会被其他几个配置中的修改所覆盖。
-工具集合
-env
-
-
-
通过 env 参数可以判断当前环境为 development、production 还是 test。比如：
-
-isProd
-
-
-通过 isProd 参数可以判断当前环境是否为 production。比如：
-
-target
-
-
-通过 target 参数可以判断当前构建的目标运行时环境。比如：
-
-isServer
-
-
-判断当前构建的目标运行时环境是否为 node，等价于 target === 'node'。
-
-isWebWorker
-
-
-判断当前构建的目标运行时环境是否为 web-worker，等价于 target === 'web-worker'。
-
-HtmlPlugin
-
-
-通过这个参数你可以拿到 webpack 或 Rspack 中的 HtmlPlugin 实例。
-
-CHAIN_ID
-Builder 中预先定义了一些常用的 Chain ID，你可以通过这些 ID 来定位到内置的 Rule 或 Plugin。
-TIP请留意，下列的一部分 Rule 或 Plugin 并不是默认存在的，当你开启特定配置项、或是注册某些插件后，它们才会被包含在 Rspack 或 webpack 配置中。
-比如，RULE.STYLUS 仅在注册了 Stylus 插件后才会存在。
-
-CHAIN_ID.RULE
-
-
-
-ID
-描述
-
-
-
-
-RULE.MJS处理 mjs 的规则
-
-
-RULE.CSS处理 css 的规则
-
-
-RULE.LESS处理 less 的规则
-
-
-RULE.SASS处理 sass 的规则
-
-
-RULE.STYLUS处理 stylus 的规则
-
-
-RULE.TOML处理 toml 的规则
-
-
-RULE.YAML处理 yaml 的规则
-
-
-RULE.WASM处理 wasm 的规则
-
-
-RULE.NODE处理 node 的规则
-
-
-
-CHAIN_ID.ONE_OF
-通过 ONE_OF.XXX 可以匹配到规则数组中的某一类规则。
-
-
-
-ID
-描述
-
-
-
-
-ONE_OF.SVG处理 SVG 的规则，在 data URI 和单独文件之间自动选择
-
-
-ONE_OF.SVG_URL处理 SVG 的规则，输出为单独文件
-
-
-ONE_OF.SVG_INLINE处理 SVG 的规则，作为 data URI 内联到 bundle 中
-
-
-ONE_OF.SVG_ASSETS处理 SVG 的规则，在 data URI 和单独文件之间自动选择
-
-
-
-CHAIN_ID.USE
-通过 USE.XXX 可以匹配到对应的 loader。
-
-
-
-ID
-描述
-
-
-
-
-USE.LESS对应 less-loader
-
-
-USE.SASS对应 sass-loader
-
-
-USE.STYLUS对应 stylus-loader
-
-
-USE.VUE对应 vue-loader
-
-
-USE.TOML对应 toml-loader
-
-
-USE.YAML对应 yaml-loader
-
-
-USE.NODE对应 node-loader
-
-
-USE.SVGR对应 @svgr/webpack
-
-
-USE.POSTCSS对应 postcss-loader
-
-
-USE.RESOLVE_URL_LOADER_FOR_SASS对应 resolve-url-loader
-
-
-
-CHAIN_ID.PLUGIN
-通过 PLUGIN.XXX 可以匹配到对应的 plugin。
-
-
-
-ID
-描述
-
-
-
-
-PLUGIN.HTML对应 HtmlPlugin，使用时需要拼接 entry 名称：${PLUGIN.HTML}-${entryName}
-
-
-PLUGIN.APP_ICON对应 AppIconPlugin
-
-
-PLUGIN.INLINE_HTML对应 InlineChunkHtmlPlugin
-
-
-PLUGIN.BUNDLE_ANALYZER对应 WebpackBundleAnalyzer
-
-
-PLUGIN.ASSETS_RETRY对应 Builder 中的 webpack 静态资源重试插件 WebpackAssetsRetryPlugin
-
-
-PLUGIN.VUE_LOADER_PLUGIN对应 VueLoaderPlugin
-
-
-PLUGIN.AUTO_SET_ROOT_SIZE对应 Builder 中的自动设置根字体大小插件 AutoSetRootSizePlugin
-
-
-
-CHAIN_ID.MINIMIZER
-通过 MINIMIZER.XXX 可以匹配到对应的压缩工具。
-
-
-
-ID
-描述
-
-
-
-
-MINIMIZER.JS对应 TerserWebpackPlugin 或 SwcJsMinimizerRspackPlugin
-
-
-MINIMIZER.CSS对应 CssMinimizerWebpackPlugin
-
-
-
-使用示例
-使用示例可参考：WebpackChain 使用示例。
+更多信息可参考 Rsbuild#tools.bundlerChain
tools.cssExtract
-
+;
chunkFilename: `${cssPath}/async/${cssFilename}`,
ignoreOrder: true,
},
-};
+};
-
通过 tools.cssExtract 可以更改 mini-css-extract-plugin 的配置。
-Object 类型
+通过 tools.cssExtract 可以更改 mini-css-extract-plugin 的配置。
+Object 类型
当此值为 Object 类型时，与默认配置通过 Object.assign 合并。比如：
-Function 类型
+};
+Function 类型
当此值为 Function 类型时，默认配置作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终配置。比如：
-更多配置细节可参考 mini-css-extract-plugin。
+};
+更多配置细节可参考 mini-css-extract-plugin。
tools.cssLoader
-
+;
-通过 tools.cssLoader 可以修改 css-loader 的配置项。默认配置如下:
+通过 tools.cssLoader 可以修改 css-loader 的配置项。默认配置如下:
-TIP在使用 Rspack 作为打包工具时，仅支持在 disableCssExtract 时使用该配置。
-修改 CSS Modules 相关配置，推荐使用 output.cssModules 配置项。
+}
+TIP在使用 Rspack 作为打包工具时，仅支持在 disableCssExtract 时使用该配置。
+修改 CSS Modules 相关配置，推荐使用 output.cssModules 配置项。
-Object 类型
+Object 类型
当此值为 Object 类型时，会与默认配置进行深层合并 (deep merge)。比如：
-Function 类型
+};
+Function 类型
当此值为 Function 类型时，默认配置作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终配置。比如：
+};
tools.devServer
-
+;
通过 tools.devServer 可以修改开发环境服务器的配置。
-TIPModern.js 中并没有直接使用 webpack-dev-server 或 @rspack/dev-server, 而是基于 webpack-dev-middleware 实现 DevServer。
+
TIPModern.js 中并没有直接使用 webpack-dev-server 或 @rspack/dev-server, 而是基于 webpack-dev-middleware 实现 DevServer。
选项
after
@@ -607,7 +331,7 @@ after ],
},
},
-};
+};
webpack-dev-server 使用 Express 作为服务端框架。Modern.js 中没有使用任何框架，上述中间件中 req 和 res 都是 Node 原生对象，因此 webpack-dev-server 的 Express 中间件不一定能直接在 Modern.js 中使用。
如果要迁移 webpack-dev-server 中使用的 Express 中间件，可以使用以下方式，将 Express app 作为中间件传入：
+};
before
before ],
},
},
-};
+};
client
client port?: string;
/** 指定要使用的 host */
host?: string;
-}
+}
@@ -667,7 +391,7 @@ client host: '',
// By default it is set to "location.protocol === 'https:' ? 'wss' : 'ws'""
protocol: '',
-};
+};
对应 HMR 客户端的配置，通常用于设置 HMR 对应的 WebSocket URL。
compress
@@ -682,21 +406,21 @@ compress compress: false,
},
},
-};
+};
devMiddleware
+}
-devMiddleware 配置项。当前配置是 webpack-dev-middleware 配置项的子集.
+}
+devMiddleware 配置项。当前配置是 webpack-dev-middleware 配置项的子集.
headers
headers },
},
},
-};
+};
historyApiFallback
history
historyApiFallback: true,
},
},
-};
-
更多选项和详细信息可参考 connect-history-api-fallback 文档。
+};
+更多选项和详细信息可参考 connect-history-api-fallback 文档。
hot
-是否开启 Hot Module Replacement 热更新能力。
+是否开启 Hot Module Replacement 热更新能力。
https
https },
},
},
-};
+};
liveReload
setupMidd
) => void;
},
) => void
->;
+>;
@@ -794,7 +518,7 @@ setupMidd
],
},
},
-};
+};
一些特殊场景需求可能需要使用服务器 API：
setupMidd
],
},
},
-};
+};
proxy
proxy },
},
},
-};
-此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
+};
+此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
如果你不想传递 /api，可以通过 pathRewrite 重写请求路径：
-DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
+};
+DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
DevServer Proxy 完整类型定义为：
+ | ProxyDetail;
除了 http-proxy-middleware 的选项外，还支持 bypass 和 context 两个配置项：
removePlugin
removePlugins('babel-plugin-import');
},
},
-};
+};
removePresets
removePreset
removePresets('@babel/preset-env');
},
},
-};
+};
modifyPresetEnvOptions
-
修改 @babel/preset-env 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+修改 @babel/preset-env 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+};
modifyPresetReactOptions
-修改 @babel/preset-react 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+修改 @babel/preset-react 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+};
addIncludes
-已废弃，请使用 source.include 代替，两者功能完全一致。
+已废弃，请使用 source.include 代替，两者功能完全一致。
addExcludes
-已废弃，请使用 source.exclude 代替，两者功能完全一致。
+已废弃，请使用 source.exclude 代替，两者功能完全一致。
调试 Babel 配置
-当你通过 tools.babel 修改 babel-loader 配置后，可以在 Builder 调试模式 下查看最终生成的配置。
+当你通过 tools.babel 修改 babel-loader 配置后，可以在 Builder 调试模式 下查看最终生成的配置。
首先通过 DEBUG=builder 参数开启调试模式：
+DEBUG=builder pnpm build
然后打开生成的 (webpack|rspack).config.web.js，搜索 babel-loader 关键词，即可看到完整的 babel-loader 配置内容。
tools.bundlerChain
-
+;
什么是 BundlerChain
Bundler chain 是 webpack chain 的子集，其中包含一部分 webpack chain API，你可以用它来同时修改 webpack 和 Rspack 的配置。
-通过 bundler chain 修改的配置，在 webpack 和 Rspack 构建时均可生效。需要注意的是，bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如，修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同)，或添加一个Rspack 兼容的 webpack 插件。
+通过 bundler chain 修改的配置，在 webpack 和 Rspack 构建时均可生效。需要注意的是，bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如，修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同)，或添加一个Rspack 兼容的 webpack 插件。
tools.bundlerChain 的执行时机早于 tools.webpackChain / tools.webpack / tools.rspack，因此会被其他几个配置中的修改所覆盖。
-工具集合
-env
-
-
-
通过 env 参数可以判断当前环境为 development、production 还是 test。比如：
-
-isProd
-
-
-通过 isProd 参数可以判断当前环境是否为 production。比如：
-
-target
-
-
-通过 target 参数可以判断当前构建的目标运行时环境。比如：
-
-isServer
-
-
-判断当前构建的目标运行时环境是否为 node，等价于 target === 'node'。
-
-isWebWorker
-
-
-判断当前构建的目标运行时环境是否为 web-worker，等价于 target === 'web-worker'。
-
-HtmlPlugin
-
-
-通过这个参数你可以拿到 webpack 或 Rspack 中的 HtmlPlugin 实例。
-
-CHAIN_ID
-Builder 中预先定义了一些常用的 Chain ID，你可以通过这些 ID 来定位到内置的 Rule 或 Plugin。
-TIP请留意，下列的一部分 Rule 或 Plugin 并不是默认存在的，当你开启特定配置项、或是注册某些插件后，它们才会被包含在 Rspack 或 webpack 配置中。
-比如，RULE.STYLUS 仅在注册了 Stylus 插件后才会存在。
-
-CHAIN_ID.RULE
-
-
-
-ID
-描述
-
-
-
-
-RULE.MJS处理 mjs 的规则
-
-
-RULE.CSS处理 css 的规则
-
-
-RULE.LESS处理 less 的规则
-
-
-RULE.SASS处理 sass 的规则
-
-
-RULE.STYLUS处理 stylus 的规则
-
-
-RULE.TOML处理 toml 的规则
-
-
-RULE.YAML处理 yaml 的规则
-
-
-RULE.WASM处理 wasm 的规则
-
-
-RULE.NODE处理 node 的规则
-
-
-
-CHAIN_ID.ONE_OF
-通过 ONE_OF.XXX 可以匹配到规则数组中的某一类规则。
-
-
-
-ID
-描述
-
-
-
-
-ONE_OF.SVG处理 SVG 的规则，在 data URI 和单独文件之间自动选择
-
-
-ONE_OF.SVG_URL处理 SVG 的规则，输出为单独文件
-
-
-ONE_OF.SVG_INLINE处理 SVG 的规则，作为 data URI 内联到 bundle 中
-
-
-ONE_OF.SVG_ASSETS处理 SVG 的规则，在 data URI 和单独文件之间自动选择
-
-
-
-CHAIN_ID.USE
-通过 USE.XXX 可以匹配到对应的 loader。
-
-
-
-ID
-描述
-
-
-
-
-USE.LESS对应 less-loader
-
-
-USE.SASS对应 sass-loader
-
-
-USE.STYLUS对应 stylus-loader
-
-
-USE.VUE对应 vue-loader
-
-
-USE.TOML对应 toml-loader
-
-
-USE.YAML对应 yaml-loader
-
-
-USE.NODE对应 node-loader
-
-
-USE.SVGR对应 @svgr/webpack
-
-
-USE.POSTCSS对应 postcss-loader
-
-
-USE.RESOLVE_URL_LOADER_FOR_SASS对应 resolve-url-loader
-
-
-
-CHAIN_ID.PLUGIN
-通过 PLUGIN.XXX 可以匹配到对应的 plugin。
-
-
-
-ID
-描述
-
-
-
-
-PLUGIN.HTML对应 HtmlPlugin，使用时需要拼接 entry 名称：${PLUGIN.HTML}-${entryName}
-
-
-PLUGIN.APP_ICON对应 AppIconPlugin
-
-
-PLUGIN.INLINE_HTML对应 InlineChunkHtmlPlugin
-
-
-PLUGIN.BUNDLE_ANALYZER对应 WebpackBundleAnalyzer
-
-
-PLUGIN.ASSETS_RETRY对应 Builder 中的 webpack 静态资源重试插件 WebpackAssetsRetryPlugin
-
-
-PLUGIN.VUE_LOADER_PLUGIN对应 VueLoaderPlugin
-
-
-PLUGIN.AUTO_SET_ROOT_SIZE对应 Builder 中的自动设置根字体大小插件 AutoSetRootSizePlugin
-
-
-
-CHAIN_ID.MINIMIZER
-通过 MINIMIZER.XXX 可以匹配到对应的压缩工具。
-
-
-
-ID
-描述
-
-
-
-
-MINIMIZER.JS对应 TerserWebpackPlugin 或 SwcJsMinimizerRspackPlugin
-
-
-MINIMIZER.CSS对应 CssMinimizerWebpackPlugin
-
-
-
-使用示例
-使用示例可参考：WebpackChain 使用示例。
+更多信息可参考 Rsbuild#tools.bundlerChain
tools.cssExtract
-
+;
chunkFilename: `${cssPath}/async/${cssFilename}`,
ignoreOrder: true,
},
-};
+};
-
通过 tools.cssExtract 可以更改 mini-css-extract-plugin 的配置。
-Object 类型
+通过 tools.cssExtract 可以更改 mini-css-extract-plugin 的配置。
+Object 类型
当此值为 Object 类型时，与默认配置通过 Object.assign 合并。比如：
-Function 类型
+};
+Function 类型
当此值为 Function 类型时，默认配置作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终配置。比如：
-更多配置细节可参考 mini-css-extract-plugin。
+};
+更多配置细节可参考 mini-css-extract-plugin。
tools.cssLoader
-
+;
-通过 tools.cssLoader 可以修改 css-loader 的配置项。默认配置如下:
+通过 tools.cssLoader 可以修改 css-loader 的配置项。默认配置如下:
-TIP在使用 Rspack 作为打包工具时，仅支持在 disableCssExtract 时使用该配置。
-修改 CSS Modules 相关配置，推荐使用 output.cssModules 配置项。
+}
+TIP在使用 Rspack 作为打包工具时，仅支持在 disableCssExtract 时使用该配置。
+修改 CSS Modules 相关配置，推荐使用 output.cssModules 配置项。
-Object 类型
+Object 类型
当此值为 Object 类型时，会与默认配置进行深层合并 (deep merge)。比如：
-Function 类型
+};
+Function 类型
当此值为 Function 类型时，默认配置作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终配置。比如：
+};
tools.devServer
-
+;
通过 tools.devServer 可以修改开发环境服务器的配置。
-TIPModern.js 中并没有直接使用 webpack-dev-server 或 @rspack/dev-server, 而是基于 webpack-dev-middleware 实现 DevServer。
+
TIPModern.js 中并没有直接使用 webpack-dev-server 或 @rspack/dev-server, 而是基于 webpack-dev-middleware 实现 DevServer。
选项
after
@@ -607,7 +331,7 @@ after ],
},
},
-};
+};
webpack-dev-server 使用 Express 作为服务端框架。Modern.js 中没有使用任何框架，上述中间件中 req 和 res 都是 Node 原生对象，因此 webpack-dev-server 的 Express 中间件不一定能直接在 Modern.js 中使用。
如果要迁移 webpack-dev-server 中使用的 Express 中间件，可以使用以下方式，将 Express app 作为中间件传入：
+};
before
before ],
},
},
-};
+};
client
client port?: string;
/** 指定要使用的 host */
host?: string;
-}
+}
@@ -667,7 +391,7 @@ client host: '',
// By default it is set to "location.protocol === 'https:' ? 'wss' : 'ws'""
protocol: '',
-};
+};
对应 HMR 客户端的配置，通常用于设置 HMR 对应的 WebSocket URL。
compress
@@ -682,21 +406,21 @@ compress compress: false,
},
},
-};
+};
devMiddleware
+}
-devMiddleware 配置项。当前配置是 webpack-dev-middleware 配置项的子集.
+}
+devMiddleware 配置项。当前配置是 webpack-dev-middleware 配置项的子集.
headers
headers },
},
},
-};
+};
historyApiFallback
history
historyApiFallback: true,
},
},
-};
-
更多选项和详细信息可参考 connect-history-api-fallback 文档。
+};
+更多选项和详细信息可参考 connect-history-api-fallback 文档。
hot
-是否开启 Hot Module Replacement 热更新能力。
+是否开启 Hot Module Replacement 热更新能力。
https
https },
},
},
-};
+};
liveReload
setupMidd
) => void;
},
) => void
->;
+>;
@@ -794,7 +518,7 @@ setupMidd
],
},
},
-};
+};
一些特殊场景需求可能需要使用服务器 API：
setupMidd
],
},
},
-};
+};
proxy
proxy },
},
},
-};
-此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
+};
+此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
如果你不想传递 /api，可以通过 pathRewrite 重写请求路径：
-DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
+};
+DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
DevServer Proxy 完整类型定义为：
+ | ProxyDetail;
除了 http-proxy-middleware 的选项外，还支持 bypass 和 context 两个配置项：
removePreset
removePresets('@babel/preset-env');
},
},
-};
+};
modifyPresetEnvOptions
-
修改 @babel/preset-env 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+修改 @babel/preset-env 的配置项，传入的配置会与默认配置进行浅层合并，比如:
modifyPresetReactOptions
修改 @babel/preset-react 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+修改 @babel/preset-react 的配置项，传入的配置会与默认配置进行浅层合并，比如:
addIncludes
-已废弃，请使用 source.include 代替，两者功能完全一致。
+已废弃，请使用 source.include 代替，两者功能完全一致。
addExcludes
-已废弃，请使用 source.exclude 代替，两者功能完全一致。
+已废弃，请使用 source.exclude 代替，两者功能完全一致。
调试 Babel 配置
-当你通过 tools.babel 修改 babel-loader 配置后，可以在 Builder 调试模式 下查看最终生成的配置。
当你通过 tools.babel 修改 babel-loader 配置后，可以在 Builder 调试模式 下查看最终生成的配置。
首先通过 DEBUG=builder 参数开启调试模式：
然后打开生成的 (webpack|rspack).config.web.js，搜索 babel-loader 关键词，即可看到完整的 babel-loader 配置内容。
tools.bundlerChain
- +;
什么是 BundlerChain
Bundler chain 是 webpack chain 的子集，其中包含一部分 webpack chain API，你可以用它来同时修改 webpack 和 Rspack 的配置。
-通过 bundler chain 修改的配置，在 webpack 和 Rspack 构建时均可生效。需要注意的是，bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如，修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同)，或添加一个Rspack 兼容的 webpack 插件。
+通过 bundler chain 修改的配置，在 webpack 和 Rspack 构建时均可生效。需要注意的是，bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如，修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同)，或添加一个Rspack 兼容的 webpack 插件。
tools.bundlerChain 的执行时机早于 tools.webpackChain / tools.webpack / tools.rspack，因此会被其他几个配置中的修改所覆盖。
-工具集合
-env
-
-
-
Bundler chain 是 webpack chain 的子集，其中包含一部分 webpack chain API，你可以用它来同时修改 webpack 和 Rspack 的配置。
-通过 bundler chain 修改的配置，在 webpack 和 Rspack 构建时均可生效。需要注意的是，bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如，修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同)，或添加一个Rspack 兼容的 webpack 插件。
+通过 bundler chain 修改的配置，在 webpack 和 Rspack 构建时均可生效。需要注意的是，bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如，修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同)，或添加一个Rspack 兼容的 webpack 插件。
tools.bundlerChain 的执行时机早于 tools.webpackChain / tools.webpack / tools.rspack，因此会被其他几个配置中的修改所覆盖。
通过 env 参数可以判断当前环境为 development、production 还是 test。比如：
-isProd
--
-
通过 isProd 参数可以判断当前环境是否为 production。比如：
-target
--
-
通过 target 参数可以判断当前构建的目标运行时环境。比如：
-isServer
--
-
判断当前构建的目标运行时环境是否为 node，等价于 target === 'node'。
isWebWorker
--
-
判断当前构建的目标运行时环境是否为 web-worker，等价于 target === 'web-worker'。
HtmlPlugin
--
-
通过这个参数你可以拿到 webpack 或 Rspack 中的 HtmlPlugin 实例。
-CHAIN_ID
-Builder 中预先定义了一些常用的 Chain ID，你可以通过这些 ID 来定位到内置的 Rule 或 Plugin。
-请留意，下列的一部分 Rule 或 Plugin 并不是默认存在的，当你开启特定配置项、或是注册某些插件后，它们才会被包含在 Rspack 或 webpack 配置中。
-比如，RULE.STYLUS 仅在注册了 Stylus 插件后才会存在。
-
CHAIN_ID.RULE
-| ID | -描述 | -
|---|---|
RULE.MJS |
-处理 mjs 的规则 |
-
RULE.CSS |
-处理 css 的规则 |
-
RULE.LESS |
-处理 less 的规则 |
-
RULE.SASS |
-处理 sass 的规则 |
-
RULE.STYLUS |
-处理 stylus 的规则 |
-
RULE.TOML |
-处理 toml 的规则 |
-
RULE.YAML |
-处理 yaml 的规则 |
-
RULE.WASM |
-处理 wasm 的规则 |
-
RULE.NODE |
-处理 node 的规则 |
-
CHAIN_ID.ONE_OF
-通过 ONE_OF.XXX 可以匹配到规则数组中的某一类规则。
| ID | -描述 | -
|---|---|
ONE_OF.SVG |
-处理 SVG 的规则，在 data URI 和单独文件之间自动选择 | -
ONE_OF.SVG_URL |
-处理 SVG 的规则，输出为单独文件 | -
ONE_OF.SVG_INLINE |
-处理 SVG 的规则，作为 data URI 内联到 bundle 中 | -
ONE_OF.SVG_ASSETS |
-处理 SVG 的规则，在 data URI 和单独文件之间自动选择 | -
CHAIN_ID.USE
-通过 USE.XXX 可以匹配到对应的 loader。
| ID | -描述 | -
|---|---|
USE.LESS |
-对应 less-loader |
-
USE.SASS |
-对应 sass-loader |
-
USE.STYLUS |
-对应 stylus-loader |
-
USE.VUE |
-对应 vue-loader |
-
USE.TOML |
-对应 toml-loader |
-
USE.YAML |
-对应 yaml-loader |
-
USE.NODE |
-对应 node-loader |
-
USE.SVGR |
-对应 @svgr/webpack |
-
USE.POSTCSS |
-对应 postcss-loader |
-
USE.RESOLVE_URL_LOADER_FOR_SASS |
-对应 resolve-url-loader |
-
CHAIN_ID.PLUGIN
-通过 PLUGIN.XXX 可以匹配到对应的 plugin。
| ID | -描述 | -
|---|---|
PLUGIN.HTML |
-对应 HtmlPlugin，使用时需要拼接 entry 名称：${PLUGIN.HTML}-${entryName} |
-
PLUGIN.APP_ICON |
-对应 AppIconPlugin |
-
PLUGIN.INLINE_HTML |
-对应 InlineChunkHtmlPlugin |
-
PLUGIN.BUNDLE_ANALYZER |
-对应 WebpackBundleAnalyzer |
-
PLUGIN.ASSETS_RETRY |
-对应 Builder 中的 webpack 静态资源重试插件 WebpackAssetsRetryPlugin |
-
PLUGIN.VUE_LOADER_PLUGIN |
-对应 VueLoaderPlugin |
-
PLUGIN.AUTO_SET_ROOT_SIZE |
-对应 Builder 中的自动设置根字体大小插件 AutoSetRootSizePlugin |
-
CHAIN_ID.MINIMIZER
-通过 MINIMIZER.XXX 可以匹配到对应的压缩工具。
| ID | -描述 | -
|---|---|
MINIMIZER.JS |
-对应 TerserWebpackPlugin 或 SwcJsMinimizerRspackPlugin |
-
MINIMIZER.CSS |
-对应 CssMinimizerWebpackPlugin |
-
使用示例
-使用示例可参考：WebpackChain 使用示例。
+更多信息可参考 Rsbuild#tools.bundlerChain
tools.cssExtract
- +;
chunkFilename: `${cssPath}/async/${cssFilename}`,
ignoreOrder: true,
},
-};
+};
-
通过 tools.cssExtract 可以更改 mini-css-extract-plugin 的配置。
Object 类型
+通过 tools.cssExtract 可以更改 mini-css-extract-plugin 的配置。
Object 类型
当此值为 Object 类型时，与默认配置通过 Object.assign 合并。比如：
Function 类型
+}; +Function 类型
当此值为 Function 类型时，默认配置作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终配置。比如：
更多配置细节可参考 mini-css-extract-plugin。
+}; +更多配置细节可参考 mini-css-extract-plugin。
tools.cssLoader
- +;
通过 tools.cssLoader 可以修改 css-loader 的配置项。默认配置如下:
通过 tools.cssLoader 可以修改 css-loader 的配置项。默认配置如下:
在使用 Rspack 作为打包工具时，仅支持在 disableCssExtract 时使用该配置。
-修改 CSS Modules 相关配置，推荐使用 output.cssModules 配置项。 +}
在使用 Rspack 作为打包工具时，仅支持在 disableCssExtract 时使用该配置。
+修改 CSS Modules 相关配置，推荐使用 output.cssModules 配置项。
Object 类型
+Object 类型
当此值为 Object 类型时，会与默认配置进行深层合并 (deep merge)。比如：
Function 类型
+}; +Function 类型
当此值为 Function 类型时，默认配置作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终配置。比如：
tools.devServer
- +;
通过 tools.devServer 可以修改开发环境服务器的配置。
Modern.js 中并没有直接使用 webpack-dev-server 或 @rspack/dev-server, 而是基于 webpack-dev-middleware 实现 DevServer。 +
Modern.js 中并没有直接使用 webpack-dev-server 或 @rspack/dev-server, 而是基于 webpack-dev-middleware 实现 DevServer。
选项
after
@@ -607,7 +331,7 @@after ], }, }, -};
webpack-dev-server 使用 Express 作为服务端框架。Modern.js 中没有使用任何框架，上述中间件中 req 和 res 都是 Node 原生对象，因此 webpack-dev-server 的 Express 中间件不一定能直接在 Modern.js 中使用。
如果要迁移 webpack-dev-server 中使用的 Express 中间件，可以使用以下方式，将 Express app 作为中间件传入：
before
before ],
},
},
-};
+};
client
client port?: string;
/** 指定要使用的 host */
host?: string;
-}
+}
@@ -667,7 +391,7 @@ client host: '',
// By default it is set to "location.protocol === 'https:' ? 'wss' : 'ws'""
protocol: '',
-};
+};
对应 HMR 客户端的配置，通常用于设置 HMR 对应的 WebSocket URL。
compress
@@ -682,21 +406,21 @@ compress compress: false,
},
},
-};
+};
devMiddleware
+}
-devMiddleware 配置项。当前配置是 webpack-dev-middleware 配置项的子集.
+}
+devMiddleware 配置项。当前配置是 webpack-dev-middleware 配置项的子集.
headers
headers },
},
},
-};
+};
historyApiFallback
history
historyApiFallback: true,
},
},
-};
-
更多选项和详细信息可参考 connect-history-api-fallback 文档。
+};
+更多选项和详细信息可参考 connect-history-api-fallback 文档。
hot
-是否开启 Hot Module Replacement 热更新能力。
+是否开启 Hot Module Replacement 热更新能力。
https
https },
},
},
-};
+};
liveReload
setupMidd
) => void;
},
) => void
->;
+>;
@@ -794,7 +518,7 @@ setupMidd
],
},
},
-};
+};
一些特殊场景需求可能需要使用服务器 API：
setupMidd
],
},
},
-};
+};
proxy
proxy },
},
},
-};
-此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
+};
+此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
如果你不想传递 /api，可以通过 pathRewrite 重写请求路径：
-DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
+};
+DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
DevServer Proxy 完整类型定义为：
+ | ProxyDetail;
除了 http-proxy-middleware 的选项外，还支持 bypass 和 context 两个配置项：
client port?: string;
/** 指定要使用的 host */
host?: string;
-}
+}
@@ -667,7 +391,7 @@ client host: '',
// By default it is set to "location.protocol === 'https:' ? 'wss' : 'ws'""
protocol: '',
-};
+};
对应 HMR 客户端的配置，通常用于设置 HMR 对应的 WebSocket URL。
compress
@@ -682,21 +406,21 @@ compress compress: false,
},
},
-};
+};
devMiddleware
+}
-devMiddleware 配置项。当前配置是 webpack-dev-middleware 配置项的子集.
+}
+devMiddleware 配置项。当前配置是 webpack-dev-middleware 配置项的子集.
headers
headers },
},
},
-};
+};
historyApiFallback
history
historyApiFallback: true,
},
},
-};
-
更多选项和详细信息可参考 connect-history-api-fallback 文档。
+};
+更多选项和详细信息可参考 connect-history-api-fallback 文档。
hot
-是否开启 Hot Module Replacement 热更新能力。
+是否开启 Hot Module Replacement 热更新能力。
https
https },
},
},
-};
+};
liveReload
setupMidd
) => void;
},
) => void
->;
+>;
@@ -794,7 +518,7 @@ setupMidd
],
},
},
-};
+};
一些特殊场景需求可能需要使用服务器 API：
setupMidd
],
},
},
-};
+};
proxy
proxy },
},
},
-};
-此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
+};
+此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
如果你不想传递 /api，可以通过 pathRewrite 重写请求路径：
-DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
+};
+DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
DevServer Proxy 完整类型定义为：
+ | ProxyDetail;
除了 http-proxy-middleware 的选项外，还支持 bypass 和 context 两个配置项：
对应 HMR 客户端的配置，通常用于设置 HMR 对应的 WebSocket URL。
compress
-
@@ -682,21 +406,21 @@
compress compress: false,
},
},
-};
+};
devMiddleware
+}
-devMiddleware 配置项。当前配置是 webpack-dev-middleware 配置项的子集.
+}
+devMiddleware 配置项。当前配置是 webpack-dev-middleware 配置项的子集.
headers
headers },
},
},
-};
+};
historyApiFallback
history
historyApiFallback: true,
},
},
-};
-
更多选项和详细信息可参考 connect-history-api-fallback 文档。
+};
+更多选项和详细信息可参考 connect-history-api-fallback 文档。
hot
-是否开启 Hot Module Replacement 热更新能力。
+是否开启 Hot Module Replacement 热更新能力。
https
https },
},
},
-};
+};
liveReload
setupMidd
) => void;
},
) => void
->;
+>;
@@ -794,7 +518,7 @@ setupMidd
],
},
},
-};
+};
一些特殊场景需求可能需要使用服务器 API：
setupMidd
],
},
},
-};
+};
proxy
proxy },
},
},
-};
-此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
+};
+此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
如果你不想传递 /api，可以通过 pathRewrite 重写请求路径：
-DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
+};
+DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
DevServer Proxy 完整类型定义为：
+ | ProxyDetail;
除了 http-proxy-middleware 的选项外，还支持 bypass 和 context 两个配置项：
headers },
},
},
-};
+};
historyApiFallback
history
historyApiFallback: true,
},
},
-};
-
更多选项和详细信息可参考 connect-history-api-fallback 文档。
+};
+更多选项和详细信息可参考 connect-history-api-fallback 文档。
hot
-是否开启 Hot Module Replacement 热更新能力。
+是否开启 Hot Module Replacement 热更新能力。
https
https },
},
},
-};
+};
liveReload
setupMidd
) => void;
},
) => void
->;
+>;
@@ -794,7 +518,7 @@ setupMidd
],
},
},
-};
+};
一些特殊场景需求可能需要使用服务器 API：
setupMidd
],
},
},
-};
+};
proxy
proxy },
},
},
-};
-此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
+};
+此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
如果你不想传递 /api，可以通过 pathRewrite 重写请求路径：
-DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
+};
+DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
DevServer Proxy 完整类型定义为：
+ | ProxyDetail;
除了 http-proxy-middleware 的选项外，还支持 bypass 和 context 两个配置项：
history historyApiFallback: true, }, }, -}; -
更多选项和详细信息可参考 connect-history-api-fallback 文档。
+}; +更多选项和详细信息可参考 connect-history-api-fallback 文档。
hot
是否开启 Hot Module Replacement 热更新能力。
+是否开启 Hot Module Replacement 热更新能力。
https
https },
},
},
-};
+};
liveReload
setupMidd
) => void;
},
) => void
->;
+>;
@@ -794,7 +518,7 @@ setupMidd
],
},
},
-};
+};
一些特殊场景需求可能需要使用服务器 API：
setupMidd
],
},
},
-};
+};
proxy
proxy },
},
},
-};
-此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
+};
+此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
如果你不想传递 /api，可以通过 pathRewrite 重写请求路径：
-DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
+};
+DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
DevServer Proxy 完整类型定义为：
+ | ProxyDetail;
除了 http-proxy-middleware 的选项外，还支持 bypass 和 context 两个配置项：
setupMidd
) => void;
},
) => void
->;
+>;
@@ -794,7 +518,7 @@ setupMidd
],
},
},
-};
+};
一些特殊场景需求可能需要使用服务器 API：
setupMidd
],
},
},
-};
+};
proxy
proxy },
},
},
-};
-此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
+};
+此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
如果你不想传递 /api，可以通过 pathRewrite 重写请求路径：
-DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
+};
+DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
DevServer Proxy 完整类型定义为：
+ | ProxyDetail;
除了 http-proxy-middleware 的选项外，还支持 bypass 和 context 两个配置项：
proxy },
},
},
-};
-此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
+};
+此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
如果你不想传递 /api，可以通过 pathRewrite 重写请求路径：
-DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
+};
+DevServer Proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
DevServer Proxy 完整类型定义为：
+ | ProxyDetail;
除了 http-proxy-middleware 的选项外，还支持 bypass 和 context 两个配置项：
pathRewrite 重写请求路径：