@modern-js/main-doc 2.58.1 → 2.58.3

package/docs/en/guides/rsbuild-plugins/plugin-swc.mdx

@@ -0,0 +1,356 @@
+---
+sidebar_position: 2
+---
+
+# SWC Plugin
+
+import SWC from '@modern-js/builder-doc/docs/en/shared/swc.md';
+
+<SWC />
+
+## Usage Scenarios
+
+Before using the SWC plugin, please understand the scenarios and limitations of the SWC plugin to determine whether your project is suitable for using it.
+
+### Rspack Scenario
+
+If you are already using Rspack as the bundler in your project, then you do not need to use the SWC plugin, because Rspack uses SWC for transpiler and minifier by default, and the SWC compilation capabilities are available out of the box.
+
+If you have configured the current SWC plugin when using Rspack, it will not have any effect.
+
+### Babel Plugins
+
+If your project requires the registration of some custom Babel plugins, you will not be able to register and use Babel plugins after using SWC, since it replaces Babel as the transpiler.
+
+For most common Babel plugins, you can find corresponding replacements in SWC, such as:
+
+- `@babel/preset-env`: use [presetEnv](#presetenv) instead.
+- `@babel/preset-react`: use [presetReact](#presetreact) instead.
+- `babel-plugin-import`: use [source.transformImport](/configure/app/source/transform-import) instead.
+- `babel-plugin-lodash`: use [extensions.lodash](#extensionslodash) instead.
+- `@emotion/babel-plugin`: use [extensions.emotion](#extensionsemotion) instead.
+- `babel-plugin-styled-components`: use [extensions.styledComponents](#extensionsstyledcomponents) instead.
+- `@babel/plugin-react-transform-remove-prop-types`: use [reactUtils.removePropTypes](#extensionsreactutils) instead.
+
+If you use Babel plugin capabilities that are not yet supported by SWC, you will no longer be able to use them after switching to SWC compilation. You can give feedback via issues under the [swc-plugins](https://github.com/web-infra-dev/swc-plugins) repository and we will evaluate if built-in support is needed.
+
+### Bundle Size
+
+When using SWC for code minification instead of [terser](https://github.com/terser/terser) and [cssnano](https://github.com/cssnano/cssnano), there may be a small change in the bundle size. SWC outperforms terser for JavaScript code compression and slightly underperforms cssnano for CSS code compression.
+
+For a detailed comparison between minifiers, see [minification-benchmarks](https://github.com/privatenumber/minification-benchmarks).
+
+## Quick Start
+
+### Used in Modern.js framework
+
+The Modern.js framework integrates the Builder's SWC plugin, and you can use it in the following ways:
+
+import EnableSWC from '@modern-js/builder-doc/docs/en/shared/enableSwc.md';
+
+<EnableSWC />
+
+That's it! Now you can use SWC transformation and minification in your project.
+
+## Config
+
+- **Type:**
+
+```ts
+type PluginConfig =
+  | ObjPluginConfig
+  | ((
+      config: ObjPluginConfig,
+      utils: { mergeConfig: typeof lodash.merge; setConfig: typeof lodash.set },
+    ) => ObjPluginConfig | void);
+
+// SwcOptions is configurations of swc https://swc.rs/docs/configuration/compilation
+interface ObjPluginConfig extends SwcOptions {
+  presetReact?: ReactConfig;
+  presetEnv?: EnvConfig;
+  jsMinify?: boolean | JsMinifyOptions;
+  cssMinify?: boolean | CssMinifyOptions;
+  extensions?: Extensions;
+  overrides?: Overrides;
+}
+```
+
+The plugin configuration is based on the SWC configuration. In order to simplify some deep-level configurations and improve development experience, certain extensions have been made. When using object-based configuration, for example you can use `presetReact` and `presetEnv` to quickly configure React-related features and syntax downgrading. Other configurations will also be directly passed through to SWC.
+
+When using function-based configuration, the default configuration generated by the plugin will be passed in, allowing you to modify it or return a new configuration.
+
+### presetReact
+
+- **Type:** [presetReact](https://swc.rs/docs/configuration/compilation#jsctransformreact) in SWC.
+
+Ported from `@babel/preset-react`. The value you passed will be merged with default option.
+
+By default, the plugin will set `runtime` field based on your `react` version, if `react` version is newer than 17.0.0, it will be set to `automatic`, otherwish `classic`.
+
+### presetEnv
+
+- **Type:** [presetEnv](https://swc.rs/docs/configuration/supported-browsers#options) in SWC.
+
+Ported from `@babel/preset-env`. The value you passed will be merged with default option.
+
+Default option is:
+
+```ts
+{
+  targets: '', // automatic get browserslist from your project, so you don't have to set this field
+  mode: 'usage',
+}
+```
+
+### jsMinify
+
+- **Type:** `boolean` or [compress configuration](https://terser.org/docs/api-reference.html#compress-options).
+- **Default:** `{ compress: {}, mangle: true }`.
+
+If set it to `false`, then SWC minification will be disabled, if set it to `true` then will it applies default option. If you pass an object, then this object will be merged with default option.
+
+### cssMinify
+
+- **Type:**: `boolean`
+- **Default:**: `true`
+
+Whether enable to compress CSS files by SWC. If enabled, it will improve the performance of CSS compression, but the compression ratio will be slightly reduced.
+
+### overrides
+
+- **Type:**
+
+```ts
+interface Overrides extends SwcOptions {
+  test: RegExp;
+  include: RegExp[];
+  exclude: RegExp[];
+}
+```
+
+- **Default:** `undefined`
+
+Specify special configuration for specific modules. For example if you want to set ie 11 target for `foo.ts`:
+
+```ts
+{
+  test: /foo.ts/,
+  env: { targets: 'ie 11' }
+}
+```
+
+This will merged into the default configuration, and do not affect other modules.
+
+### extensions
+
+- **Type:** `Object`
+
+Some plugins ported from Babel.
+
+#### extensions.reactUtils
+
+- **Type:** `Object`
+
+```ts
+type ReactUtilsOptions = {
+  autoImportReact?: boolean;
+  removeEffect?: boolean;
+  removePropTypes?: {
+    mode?: 'remove' | 'unwrap' | 'unsafe-wrap';
+    removeImport?: boolean;
+    ignoreFilenames?: string[];
+    additionalLibraries?: string[];
+    classNameMatchers?: string[];
+  };
+};
+```
+
+Some little help utils for `React`.
+
+**reactUtils.autoImportReact**
+
+- **Type:** `boolean`
+
+Automatically import `React` as global variable, eg: `import React from 'react'`.
+Mostly used for generated `React.createElement`.
+
+**reactUtils.removeEffect**
+
+- **Type:** `boolean`
+
+Remove `useEffect` call.
+
+**reactUtils.removePropTypes**
+
+- **Type:**
+
+```ts
+type RemovePropTypesOptions = {
+  mode?: 'remove' | 'unwrap' | 'unsafe-wrap';
+  removeImport?: boolean;
+  ignoreFilenames?: string[];
+  additionalLibraries?: string[];
+  classNameMatchers?: string[];
+};
+```
+
+Remove `React` runtime type checking. This is ported from [@babel/plugin-react-transform-remove-prop-types](https://github.com/oliviertassinari/babel-plugin-transform-react-remove-prop-types), All the configurations remain the same.
+
+#### extensions.lodash
+
+- **Type:**
+
+```ts
+type LodashOptions = {
+  cwd?: string;
+  ids?: string[];
+};
+```
+
+- **Default:**
+
+```ts
+const defaultOptions = {
+  cwd: process.cwd(),
+  ids: ['lodash', 'lodash-es'],
+};
+```
+
+Ported from [babel-plugin-lodash](https://github.com/lodash/babel-plugin-lodash), it is used to automatically convert references to Lodash into on-demand imports, thereby reducing the bundle size of Lodash code.
+
+```ts
+// Input
+import { get, throttle } from 'lodash';
+
+// Output
+import get from 'lodash/get';
+import throttle from 'lodash/throttle';
+```
+
+#### extensions.styledComponents
+
+- **Type:**
+
+```ts
+boolean | {
+  // Enabled by default in development, disabled in production to reduce file size,
+  // setting this will override the default for all environments.
+  displayName?: boolean,
+  // Enabled by default.
+  ssr?: boolean,
+  // Enabled by default.
+  fileName?: boolean,
+  // Empty by default.
+  topLevelImportPaths?: string[],
+  // Defaults to ["index"].
+  meaninglessFileNames?: string[],
+  // Enabled by default.
+  cssProp?: boolean,
+  // Empty by default.
+  namespace?: string,
+};
+```
+
+This is ported by Next.js team from [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components).
+
+#### extensions.emotion
+
+- **Type:**
+
+```ts
+boolean | {
+  // default is true. It will be disabled when build type is production.
+  sourceMap?: boolean,
+  // default is 'dev-only'.
+  autoLabel?: 'never' | 'dev-only' | 'always',
+  // default is '[local]'.
+  // Allowed values: `[local]` `[filename]` and `[dirname]`
+  // This option only works when autoLabel is set to 'dev-only' or 'always'.
+  // It allows you to define the format of the resulting label.
+  // The format is defined via string where variable parts are enclosed in square brackets [].
+  // For example labelFormat: "my-classname--[local]", where [local] will be replaced with the name of the variable the result is assigned to.
+  labelFormat?: string,
+  // default is undefined.
+  // This option allows you to tell the compiler what imports it should
+  // look at to determine what it should transform so if you re-export
+  // Emotion's exports, you can still use transforms.
+  importMap?: {
+    [packageName: string]: {
+      [exportName: string]: {
+        canonicalImport?: [string, string],
+        styledBaseImport?: [string, string],
+      }
+    }
+  },
+}
+```
+
+This is ported by Next.js team from [@emotion/babel-plugin](https://www.npmjs.com/package/@emotion/babel-plugin)
+
+#### extensions.pluginImport
+
+:::tip
+Builder provides the [source.transformImport](/configure/app/source/transform-import) config, so you don't need to configure `extensions.pluginImport` manually.
+:::
+
+Ported from [babel-plugin-import](https://github.com/umijs/babel-plugin-import), configurations are the same.
+
+Some configurations can be passed in functions, such as `customName`, `customStyleName`. These JavaScript functions will be called by Rust through Node-API, which will cause some performance overhead.
+
+Some simple function logic can be replaced by template language. Therefore, the configuration of function items such as `customName`, `customStyleName` can also be passed in strings as templates to replace functions and improve performance.
+
+For example:
+
+```ts
+import { MyButton as Btn } from 'foo';
+```
+
+Apply following configurations:
+
+```ts
+PluginSWC({
+  extensions: {
+    pluginImport: [
+      {
+        libraryName: 'foo',
+        customName: 'foo/es/{{ member }}',
+      },
+    ],
+  },
+});
+```
+
+`{{ member }}` will be replaced by the imported specifier:
+
+```ts
+import Btn from 'foo/es/MyButton';
+```
+
+Template `customName: 'foo/es/{{ member }}'` is the same as `` customName: (member) => `foo/es/${member}`  ``, but template value has no performance overhead of Node-API.
+
+The template used here is [handlebars](https://handlebarsjs.com). There are some useful builtin tools, Take the above import statement as an example:
+
+```ts
+PluginSWC({
+  extensions: {
+    pluginImport: [
+      {
+        libraryName: 'foo',
+        customName: 'foo/es/{{ kebabCase member }}',
+      },
+    ],
+  },
+});
+```
+
+Transformed to:
+
+```ts
+import Btn from 'foo/es/my-button';
+```
+
+In addition to `kebabCase`, there are `cameraCase`, `snakeCase`, `upperCase` and `lowerCase` can be used as well.
+
+## Limitation
+
+Do not support `@babel/plugin-transform-runtime` and other custom Babel plugins.

package/docs/en/guides/topic-detail/framework-plugin/_meta.json

@@ -7,4 +7,4 @@
   "extend",
   "plugin-api",
   "hook-list"
-]
+]

package/docs/en/guides/topic-detail/generator/_meta.json

@@ -14,4 +14,4 @@
     "name": "plugin",
     "label": "generator-plugin"
   }
-]
+]

package/docs/en/guides/topic-detail/generator/create/_meta.json

@@ -1,5 +1 @@
-[
-  "use",
-  "option",
-  "config"
-]
+["use", "option", "config"]

package/docs/en/guides/topic-detail/generator/new/_meta.json

@@ -1,5 +1 @@
-[
-  "use",
-  "option",
-  "config"
-]
+["use", "option", "config"]

package/docs/en/guides/topic-detail/generator/plugin/_meta.json

@@ -8,4 +8,4 @@
     "name": "api",
     "label": "API"
   }
-]
+]

package/docs/en/guides/troubleshooting/_meta.json

@@ -1,6 +1 @@
-[
-  "dependencies",
-  "cli",
-  "builder",
-  "hmr"
-]
+["dependencies", "cli", "builder", "hmr"]

package/docs/zh/apis/app/hooks/config/icon.mdx

@@ -42,7 +42,7 @@ sidebar_position: 2
 构建完成后，可以看到 HTML 中自动生成了以下标签：
 
 ```html
-<link rel="apple-touch-icon" sizes="180*180" href="/static/image/icon.png" />
+<link rel="apple-touch-icon" sizes="180x180" href="/static/image/icon.png" />
 ```
 
 ### 查找顺序

package/docs/zh/apis/app/runtime/web-server/unstable_middleware.mdx

@@ -91,7 +91,7 @@ import {
 } from '@modern-js/runtime/server';
 import type { Vars } from '../shared/index';
 
-const setPayload: UnstableMiddleware = async (
+const setPayload: UnstableMiddleware<Vars> = async (
   c: UnstableMiddlewareContext<Vars>,
   next,
 ) => {
@@ -100,7 +100,7 @@ const setPayload: UnstableMiddleware = async (
   await next();
 };
 
-export const unstableMiddleware: UnstableMiddleware[] = [setPayload];
+export const unstableMiddleware: UnstableMiddleware<Vars>[] = [setPayload];
 ```
 
 ```ts title="src/routes/page.data.ts"

package/docs/zh/community/blog/_meta.json

@@ -1,6 +1 @@
-[
-  "overview",
-  "v2-release-note",
-  "2022-0910-updates",
-  "2022-0708-updates"
-]
+["overview", "v2-release-note", "2022-0910-updates", "2022-0708-updates"]

package/docs/zh/components/deploy.mdx

@@ -1 +1 @@
-本地验证完成后，可以将 `dist/` 下的产物整理成服务器需要的结构，进行部署。
+本地验证完成后，可以参考 [部署](/guides/basic-features/deploy.html) 一节，将项目部署到服务器上。

package/docs/zh/configure/_meta.json

@@ -75,4 +75,4 @@
   },
   "app/builder-plugins",
   "app/auto-load-plugin"
-]
+]

package/docs/zh/configure/app/tools/esbuild.mdx

@@ -41,4 +41,4 @@ export default defineConfig({
 });
 ```
 
-完整配置项请参考 [Modern.js Builder - esbuild 插件配置](https://modernjs.dev/builder/plugins/plugin-esbuild.html#%E9%85%8D%E7%BD%AE)。
+完整配置项请参考 [esbuild 插件配置](/guides/rsbuild-plugins/plugin-esbuild.html#配置)。

package/docs/zh/configure/app/tools/swc.mdx

@@ -19,7 +19,7 @@ import SWC from '@modern-js/builder-doc/docs/zh/shared/swc.md';
 
 ## 在 Rspack 模式下使用
 
-通过 `tools.swc` 可以设置 Rspack [builtin:swc-loader](https://www.rspack.dev/guide/builtin-swc-loader) 的选项。
+通过 `tools.swc` 可以设置 Rspack [builtin:swc-loader](https://rspack.dev/zh/guide/features/builtin-swc-loader) 的选项。
 
 ```
 import { defineConfig } from '@modern-js/app-tools';
@@ -77,4 +77,4 @@ export default defineConfig({
 });
 ```
 
-完整配置项请参考 [Modern.js Builder - SWC 插件配置](https://modernjs.dev/builder/plugins/plugin-swc.html#%E9%85%8D%E7%BD%AE)。
+完整配置项请参考 [SWC 插件配置](/guides/rsbuild-plugins/plugin-swc.html#配置)。

package/docs/zh/guides/_meta.json

@@ -24,6 +24,11 @@
     "name": "topic-detail",
     "label": "topic"
   },
+  {
+    "type": "dir",
+    "name": "rsbuild-plugins",
+    "label": "构建插件"
+  },
   {
     "type": "dir",
     "name": "troubleshooting",

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

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

package/docs/zh/guides/advanced-features/rspack-start.mdx

@@ -22,13 +22,6 @@ import InitRspackApp from '@site-docs/components/init-rspack-app';
 
 项目创建完成后，在项目中执行 `pnpm run dev` 即可体验项目，更多信息可参考[快速上手](/guides/get-started/quick-start.html)。
 
-:::tip
-在使用 Rspack 作为打包工具时，由于部分能力尚在开发中，以下 features 暂时无法使用，我们将在未来提供支持：
-
-- 客户端渲染（CSR）使用 [useLoader](/guides/basic-features/data/data-fetch.html)
-
-:::
-
 ## 开启 Rspack 构建
 
 从 Modern.js MAJOR_VERSION.46.0 版本起，在一个已有的 Modern.js 项目中，你仅需在 `modern.config.ts` 中添加以下配置，即可启用 Rspack 构建：
@@ -86,7 +79,7 @@ export default {
 
 ## 修改转译配置
 
-Modern.js 在 Rspack 模式下使用 Rspack [builtin:swc-loader](https://www.rspack.dev/zh/guide/builtin-swc-loader.html) 进行代码转译。
+Modern.js 在 Rspack 模式下使用 Rspack [builtin:swc-loader](https://rspack.dev/zh/guide/features/builtin-swc-loader) 进行代码转译。
 
 Modern.js 已对 `builtin:swc-loader` 的常见配置提供了更方便的配置方式，如：通过 [source.transformImport](/configure/app/source/transform-import) 配置组件库按需引入。如果对 `builtin:swc-loader` 有自定义配置的需求，可通过 [tools.swc](/configure/app/tools/swc) 进行配置：
 

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

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

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

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

package/docs/zh/guides/basic-features/data/data-fetch.mdx

@@ -67,9 +67,9 @@ export const loader = async (): Promise<ProfileData> => {
 
 :::
 
-在 CSR 环境下，`loader` 函数会在客户端执行，`loader` 函数内可以使用浏览器的 API（但通常不需要，也不推荐）。
+在 CSR 项目中，`loader` 函数会在客户端执行，`loader` 函数内可以使用浏览器的 API（但通常不需要，也不推荐）。
 
-在 SSR 环境下，不管是首屏，还是在客户端的导航，`loader` 函数只会在服务端执行，这里可以调用任意的 Node.js API，同时这里使用的任何依赖和代码都不会包含在客户端的 bundle 中。
+在 SSR 项目中，不管是首屏，还是在客户端的导航，`loader` 函数只会在服务端执行，这里可以调用任意的 Node.js API，同时这里使用的任何依赖和代码都不会包含在客户端的 bundle 中。
 
 :::info
 在以后的版本中，Modern.js 可能会支持在 CSR 环境下，`loader` 函数也在服务端运行，以提高性能和安全性，所以这里建议尽可能地保证 `loader` 的纯粹，只做数据获取的场景。
@@ -499,8 +499,7 @@ export const loader = async (): Promise<ProfileData> => {
 **`useLoader`** 是 Modern.js 老版本中的 API。该 API 是一个 React Hook，专门提供给 SSR 应用使用，让开发者能同构的在组件中获取数据。
 
 :::tip
-CSR 的项目没有必要使用 `useLoader` 获取数据。
-
+CSR 的项目没有必要使用 `useLoader` 获取数据，且在使用 Rspack 作为打包工具时，`useLoader` 不支持使用。
 :::
 
 以下是一个最简单的例子：

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

@@ -381,7 +381,7 @@ export default () => {
 
 `routes/` 下每一层目录中，开发者同样可以定义一个 `error.tsx` 文件，默认导出一个 `<ErrorBoundary>` 组件。
 
-当有路由目录下存在该组件时，组件渲染出错会被 `ErrorBoundary` 组件捕获。当目录未定义 `layout.tsx` 文件时，`<ErrorBoundary>` 组件不会生效。
+当有路由目录下存在该组件时，组件渲染出错会被 `ErrorBoundary` 组件捕获。
 
 `<ErrorBoundary>` 可以返回出错时的 UI 视图，当前层级未声明 `<ErrorBoundary>` 组件时，错误会向上冒泡到更上层的组件，直到被捕获或抛出错误。同时，当组件出错时，只会影响捕获到该错误的路由组件及子组件，其他组件的状态和视图不受影响，可以继续交互。
 

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

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