@modern-js/main-doc 2.58.0 → 2.58.2

package/docs/zh/guides/_meta.json

@@ -0,0 +1,38 @@
+[
+  {
+    "type": "dir",
+    "name": "get-started",
+    "label": "gettingStarted"
+  },
+  {
+    "type": "dir",
+    "name": "concept",
+    "label": "concept"
+  },
+  {
+    "type": "dir",
+    "name": "basic-features",
+    "label": "basic"
+  },
+  {
+    "type": "dir",
+    "name": "advanced-features",
+    "label": "advanced"
+  },
+  {
+    "type": "dir",
+    "name": "topic-detail",
+    "label": "topic"
+  },
+  {
+    "type": "dir",
+    "name": "rsbuild-plugins",
+    "label": "构建插件"
+  },
+  {
+    "type": "dir",
+    "name": "troubleshooting",
+    "label": "troubleshooting"
+  },
+  "deprecated"
+]

package/docs/zh/guides/advanced-features/_meta.json

@@ -0,0 +1,26 @@
+[
+  "rspack-start",
+  {
+    "type": "dir",
+    "name": "bff",
+    "label": "use-bff",
+    "collapsed": true
+  },
+  "code-split",
+  {
+    "type": "dir",
+    "name": "ssr",
+    "label": "use-ssr",
+    "collapsed": true
+  },
+  "ssg",
+  "compatibility",
+  "eslint",
+  "low-level",
+  "source-build",
+  "build-performance",
+  "inline-assets",
+  "optimize-bundle",
+  "using-storybook",
+  "web-server"
+]

package/docs/zh/guides/advanced-features/bff/_meta.json

@@ -0,0 +1,6 @@
+[
+  "function",
+  "type",
+  "frameworks",
+  "sdk"
+]

package/docs/zh/guides/advanced-features/rsbuild-plugin.mdx

@@ -28,19 +28,19 @@ Modern.js 从 `MAJOR_VERSION.46.0` 起开始将底层的构建工具升级为 [R
 
 以下是已在 Modern.js 中内置的 Rsbuild 官方插件，无需安装，即可启用：
 
-| 插件                                                                                   | 介绍                                                                                     | Modern.js 链接                                                                                                                        |
-| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| [React 插件](https://rsbuild.dev/zh/plugins/list/plugin-react)                         | 提供对 React 的支持                                                                      | -                                                                                                                                     |
-| [SVGR 插件](https://rsbuild.dev/zh/plugins/list/plugin-svgr)                           | 支持将 SVG 图片转换为一个 React 组件使用                                                 | [output.disableSvgr](/configure/app/output/disable-svgr)<br />[output.svgDefaultExport](/configure/app/output/svg-default-export)     |
-| [Styled Components 插件](https://rsbuild.dev/zh/plugins/list/plugin-styled-components) | 提供对 styled-components 的编译时支持                                                    | [tools.styledComponents](/configure/app/tools/styled-components.html)                                                                 |
-| [Assets Retry 插件](https://rsbuild.dev/zh/plugins/list/plugin-assets-retry)           | 用于在静态资源加载失败时自动发起重试请求                                                 | [output.assetsRetry](/configure/app/output/assets-retry.html)                                                                         |
-| [Type Check 插件](https://rsbuild.dev/zh/plugins/list/plugin-type-check)               | 用于在单独的进程中运行 TypeScript 类型检查                                               | [output.disableTsChecker](/configure/app/output/disable-ts-checker.html)<br />[tools.tsChecker](/configure/app/tools/ts-checker.html) |
+| 插件                                                                                         | 介绍                                                                                     | Modern.js 链接                                                                                                                        |
+| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| [React 插件](https://rsbuild.dev/zh/plugins/list/plugin-react)                               | 提供对 React 的支持                                                                      | -                                                                                                                                     |
+| [SVGR 插件](https://rsbuild.dev/zh/plugins/list/plugin-svgr)                                 | 支持将 SVG 图片转换为一个 React 组件使用                                                 | [output.disableSvgr](/configure/app/output/disable-svgr)<br />[output.svgDefaultExport](/configure/app/output/svg-default-export)     |
+| [Styled Components 插件](https://github.com/rspack-contrib/rsbuild-plugin-styled-components) | 提供对 styled-components 的编译时支持                                                    | [tools.styledComponents](/configure/app/tools/styled-components.html)                                                                 |
+| [Assets Retry 插件](https://rsbuild.dev/zh/plugins/list/plugin-assets-retry)                 | 用于在静态资源加载失败时自动发起重试请求                                                 | [output.assetsRetry](/configure/app/output/assets-retry.html)                                                                         |
+| [Type Check 插件](https://rsbuild.dev/zh/plugins/list/plugin-type-check)                     | 用于在单独的进程中运行 TypeScript 类型检查                                               | [output.disableTsChecker](/configure/app/output/disable-ts-checker.html)<br />[tools.tsChecker](/configure/app/tools/ts-checker.html) |
 | [Node Polyfill 插件](https://github.com/rspack-contrib/rsbuild-plugin-node-polyfill)         | 用于注入 Node 核心模块在浏览器端的 polyfills                                             | [output.disableNodePolyfill](/configure/app/output/disable-node-polyfill.html)                                                        |
-| [Source Build 插件](https://rsbuild.dev/zh/plugins/list/plugin-source-build)           | 用于 monorepo 场景，支持引用其他子目录的源代码，并完成构建和热更新                       | [experiments.sourceBuild](/configure/app/experiments/source-build.html)                                                               |
+| [Source Build 插件](https://github.com/rspack-contrib/rsbuild-plugin-source-build)           | 用于 monorepo 场景，支持引用其他子目录的源代码，并完成构建和热更新                       | [experiments.sourceBuild](/configure/app/experiments/source-build.html)                                                               |
 | [Check Syntax 插件](https://github.com/rspack-contrib/rsbuild-plugin-check-syntax)           | 用于分析产物的语法兼容性，判断是否存在导致兼容性问题的高级语法                           | [security.checkSyntax](/configure/app/security/check-syntax.html)                                                                     |
 | [CSS Minimizer 插件](https://github.com/rspack-contrib/rsbuild-plugin-css-minimizer)         | 用于自定义 CSS 压缩工具，切换到 [cssnano](https://cssnano.co/) 或其他工具进行 CSS 压缩。 | [tools.minifyCss](/configure/app/tools/minify-css.html)                                                                               |
 | [Pug 插件](https://github.com/rspack-contrib/rsbuild-plugin-pug)                             | 提供对 Pug 模板引擎的支持                                                                | [tools.pug](/configure/app/tools/pug.html)                                                                                            |
-| [Rem 插件](https://rsbuild.dev/zh/plugins/list/plugin-rem)                             | 用于实现移动端页面的 rem 自适应布局                                                      | [output.convertToRem](/configure/app/output/convert-to-rem.html)                                                                      |
+| [Rem 插件](https://github.com/rspack-contrib/rsbuild-plugin-rem)                             | 用于实现移动端页面的 rem 自适应布局                                                      | [output.convertToRem](/configure/app/output/convert-to-rem.html)                                                                      |
 | [YAML 插件](https://github.com/rspack-contrib/rsbuild-plugin-yaml)                           | 用于引用 YAML 文件，并将其转换为 JavaScript 对象                                         | [TOML 文件](/guides/basic-features/json-files.html#toml-文件)                                                                         |
 | [TOML 插件](https://github.com/rspack-contrib/rsbuild-plugin-toml)                           | 用于引用 TOML 文件，并将其转换为 JavaScript 对象                                         | [YAML 文件](/guides/basic-features/json-files.html#yaml-文件)                                                                         |
 

package/docs/zh/guides/advanced-features/ssr/_meta.json

@@ -0,0 +1,5 @@
+[
+  "usage",
+  "stream",
+  "cache"
+]

package/docs/zh/guides/basic-features/_meta.json

@@ -0,0 +1,22 @@
+[
+  "css",
+  "routes",
+  {
+    "type": "dir",
+    "name": "data",
+    "label": "data-solution",
+    "collapsed": true
+  },
+  "alias",
+  "mock",
+  "proxy",
+  "env-vars",
+  "html",
+  "output-files",
+  "static-assets",
+  "svg-assets",
+  "json-files",
+  "wasm-assets",
+  "css-modules",
+  "deploy"
+]

package/docs/zh/guides/basic-features/data/_meta.json

@@ -0,0 +1,4 @@
+[
+  "data-fetch",
+  "data-write"
+]

package/docs/zh/guides/basic-features/mock.mdx

@@ -80,7 +80,7 @@ module.exports = {
 
 ## 按需使用 Mock 服务
 
-`config/mock/index.ts` 下还可以到处 `config` 对象，更精细的控制 Mock 服务。
+`config/mock/index.ts` 下还可以导出 `config` 对象，更精细的控制 Mock 服务。
 
 ```ts
 type MockConfig = {

package/docs/zh/guides/concept/_meta.json

@@ -0,0 +1,4 @@
+[
+  "entries",
+  "builder"
+]

package/docs/zh/guides/get-started/_meta.json

@@ -0,0 +1,7 @@
+[
+  "introduction",
+  "quick-start",
+  "upgrade",
+  "glossary",
+  "tech-stack"
+]

package/docs/zh/guides/get-started/quick-start.mdx

@@ -95,7 +95,7 @@ $ pnpm run build
 
 > modern build
 
-  Modern.js Framework v2.55.0
+  Modern.js Framework
 
 info    Starting production build...
 info    Type checker is enabled. It may take some time.
@@ -141,7 +141,7 @@ dist
 ```bash
 $ pnpm run serve
 
-  Modern.js Framework v2.55.0
+  Modern.js Framework
 
 info    Starting production server...
 

package/docs/zh/guides/get-started/upgrade.mdx

@@ -18,7 +18,7 @@ import { PackageManagerTabs } from '@theme';
 > modern upgrade
 
 [INFO] [项目类型]: Web 应用
-[INFO] [Modern.js 最新版本]: 2.0.0
+[INFO] [Modern.js 最新版本]: x.y.z
 [INFO] 已更新 Modern.js 依赖至最新版本!
 ```
 

package/docs/zh/guides/rsbuild-plugins/plugin-esbuild.mdx

@@ -0,0 +1,201 @@
+---
+sidebar_position: 3
+---
+
+# Esbuild 插件
+
+:::warning
+**当前文档中的 esbuild 功能已停止迭代**，我们更推荐使用 Rspack + SWC 的方案，因为 Rspack + SWC 具备更好的构建性能、功能丰富度和产物兼容性。
+
+请参考[「使用 Rspack」](guides/advanced-features/rspack-start)了解更多。
+
+:::
+
+import Esbuild from '@modern-js/builder-doc/docs/zh/shared/esbuild.md';
+
+<Esbuild />
+
+## 快速开始
+
+### 在 Modern.js 框架中使用
+
+Modern.js 框架默认集成了 Builder 的 esbuild 插件，因此，你不需要手动安装和注册插件，只需要使用 [tools.esbuild](/configure/app/tools/esbuild.html) 配置项即可：
+
+```js
+export default defineConfig({
+  tools: {
+    esbuild: {
+      loader: {
+        target: 'chrome61',
+      },
+      minimize: {
+        target: 'chrome61',
+      },
+    },
+  },
+});
+```
+
+## 配置
+
+插件默认会开启代码转译和代码压缩的功能，你也可以通过配置来自定义插件的行为。
+
+### loader
+
+- **类型：**
+
+```ts
+type LoaderOptions = EsbuildLoaderOptions | false | undefined;
+```
+
+- **默认值：**
+
+```ts
+const defaultOptions = {
+  target: 'es2015',
+  charset: builderConfig.output.charset,
+};
+```
+
+这个选项用于启用 JavaScript 和 TypeScript 的转译，启用时将会使用 esbuild-loader 替换 babel-loader 和 ts-loader。
+
+如果你需要修改转译参数，可以查看 [esbuild-loader 文档](https://github.com/privatenumber/esbuild-loader#loader)。
+
+#### 设置 JSX 格式
+
+在使用 esbuild 进行代码转译时，esbuild 默认会读取 `tsconfig.json` 中的 `compilerOptions.jsx` 字段，来决定使用哪种 JSX 语法。
+
+因此，你需要在 `tsconfig.json` 中设置正确的 JSX 语法。
+
+比如 React 项目，需要将 `compilerOptions.jsx` 设置为 `react-jsx`：
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx"
+  }
+}
+```
+
+#### 修改目标环境
+
+通过 `target` 选项来修改代码转译的目标环境。`target` 可以直接设置为 JavaScript 语言版本，比如 `es6`，`es2020`；也可以设置为若干个目标环境，每个目标环境都是一个环境名称后跟一个版本号，比如 `['chrome58', 'edge16' ,'firefox57']`。`target` 字段的详细介绍可以参考 [esbuild - target](https://esbuild.github.io/api/#target)。
+
+target 支持设置为以下环境：
+
+- chrome
+- edge
+- firefox
+- ie
+- ios
+- node
+- opera
+- safari
+
+```ts
+builderPluginEsbuild({
+  loader: {
+    target: 'chrome61',
+  },
+});
+```
+
+#### 关闭代码转译
+
+将 `loader` 设置为 `false` 来关闭 esbuild 代码转译，此时 Builder 会继续使用 Babel 来进行代码转译。
+
+```ts
+builderPluginEsbuild({
+  loader: false,
+});
+```
+
+### minimize
+
+- **类型：**
+
+```ts
+type MinimizeOptions = EsbuildMinifyOptions | false | undefined;
+```
+
+- **默认值：**
+
+```ts
+const defaultOptions = {
+  css: true,
+  target: 'es2015',
+  format: builderTarget === 'web' ? 'iife' : undefined,
+};
+```
+
+这个选项用于启用 JavaScript 和 CSS 的代码压缩。
+
+如果你需要修改压缩参数，可以查看 [esbuild-loader 文档](https://github.com/privatenumber/esbuild-loader#minifyplugin)。
+
+#### 修改目标环境
+
+通过 `target` 选项来修改代码压缩的目标环境。
+
+```ts
+builderPluginEsbuild({
+  minimize: {
+    target: 'chrome61',
+  },
+});
+```
+
+#### 关闭代码压缩
+
+将 `minimize` 设置为 `false` 来关闭 esbuild 代码压缩，此时 Builder 会继续使用 Terser 进行代码压缩。
+
+```ts
+builderPluginEsbuild({
+  minimize: false,
+});
+```
+
+## esbuild 局限性
+
+虽然 esbuild 能给现有的 webpack 项目带来明显的构建性能提升，但这个工具在接入 Builder 时还存在一定的局限性，需要大家在接入的时候格外注意。
+
+### 兼容性
+
+使用 esbuild 进行代码转译时（即 `loader` 能力），esbuild 通常最低支持到 ES2015（即 ES6）语法，并且不具备自动注入 Polyfill 的能力。如果生产环境需要降级到 ES5 及以下的语法，建议使用 SWC 编译。
+
+你可以通过如下的配置指定目标语法版本:
+
+```ts
+builderPluginEsbuild({
+  loader: {
+    target: 'es2015',
+  },
+});
+```
+
+使用 esbuild 进行代码压缩时（即 `minimize` 能力），esbuild 可以在生产环境中进行压缩和混淆，通常最低支持到 ES2015 语法。
+
+如果设置压缩的 `target` 为 `es5`，需要保证所有代码已经被转义为 ES5 代码，否则会导致 esbuild 编译报错：`Transforming 'xxx' to the configured target environment ("es5") is not supported yet`。
+
+因此，对于生产环境需要兼容 ES5 及以下语法的项目，请谨慎开启 minimize 能力，建议使用 SWC 压缩。
+
+你可以通过如下的配置指定目标语法版本:
+
+```ts
+builderPluginEsbuild({
+  minimize: {
+    target: 'es2015',
+  },
+});
+```
+
+### 不支持 Babel 插件
+
+使用 esbuild 进行代码转译时，诸如 `babel-plugin-import` 等原有 Babel 插件的语法编译功能在开启 esbuild 后无法使用。并且由于 Builder 底层使用的是 esbuild 的 `Transform API`，因此不支持使用额外 esbuild 插件来进行自定义编译过程。
+
+如果你有 `babel-plugin-import` 等 Babel 插件相关诉求，可以使用 SWC 插件。
+
+### 产物体积
+
+使用 esbuild 压缩虽然带来了构建效率上的提升，但 esbuild 的压缩比例是低于 terser 的，因此**构建产物的体积会增大**，请根据业务情况酌情使用。通常来说，esbuild 比较适合中后台等对体积不敏感的场景。
+
+对于压缩工具之间的详细对比，可以参考 [minification-benchmarks](https://github.com/privatenumber/minification-benchmarks)。