@modern-js/main-doc 2.69.7 → 3.0.0-alpha.1

package/docs/zh/plugin/official/cli-plugins/plugin-swc.mdx

@@ -1,351 +0,0 @@
----
-sidebar_position: 2
----
-
-# SWC 插件
-
-:::warning
-**当前文档中的 SWC 功能已停止迭代**，我们更推荐使用 Rspack + SWC 的方案。
-
-请参考[「使用 Rspack」](/guides/advanced-features/rspack-start.html)了解更多。
-
-:::
-
-import SWC from '@site-docs/components/swc.mdx';
-
-<SWC />
-
-## 适用场景
-
-在使用 SWC 插件之前，请先了解一下 SWC 插件的适用场景和局限性，以明确你的项目是否需要使用 SWC 插件。
-
-### Rspack 场景
-
-如果你的项目中已经使用了 Rspack 作为打包工具，那么你不需要接入 SWC 插件，因为 Rspack 默认会使用 SWC 进行转译和压缩，各个 SWC 编译能力可以开箱即用。
-
-如果你使用 Rspack 时配置了当前的 SWC 插件，它将不会产生任何效果。
-
-### Babel 插件
-
-如果你的项目需要注册一些自定义的 Babel 插件，由于 SWC 替代了 Babel 作为转译工具，因此使用 SWC 后，你将无法注册和使用 Babel 插件。
-
-对于大部分常见的 Babel 插件，你可以在 SWC 中找到对应的替代品，比如：
-
-- `@babel/preset-env`: 使用 [presetEnv](#presetenv) 代替。
-- `@babel/preset-react`: 使用 [presetReact](#presetreact) 代替。
-- `babel-plugin-import`：使用 [source.transformImport](/configure/app/source/transform-import) 代替。
-- `babel-plugin-lodash`：使用 [extensions.lodash](#extensionslodash) 代替。
-- `@emotion/babel-plugin`：使用 [extensions.emotion](#extensionsemotion) 代替。
-- `babel-plugin-styled-components`：使用 [extensions.styledComponents](#extensionsstyledcomponents) 代替。
-- `@babel/plugin-react-transform-remove-prop-types`: 使用 [reactUtils.removePropTypes](#extensionsreactutils) 代替。
-
-如果你使用了 SWC 尚未支持的 Babel 插件能力，在切换到 SWC 编译后，将无法再使用它们。你可以到 [swc-plugins](https://github.com/web-infra-dev/swc-plugins) 仓库下通过 issues 进行反馈，我们会评估是否需要内置支持。
-
-### 产物体积
-
-在使用 SWC 来代替 [terser](https://github.com/terser/terser) 和 [cssnano](https://github.com/cssnano/cssnano) 进行代码压缩时，构建产物的体积可能会出现少量变化。在 JavaScript 代码压缩方面，SWC 的压缩率是优于 terser 的；在 CSS 代码压缩方面，SWC 的压缩率稍逊于 cssnano。
-
-对于压缩工具之间的详细对比，可以参考 [minification-benchmarks](https://github.com/privatenumber/minification-benchmarks)。
-
-## 快速开始
-
-### 在 Modern.js 框架中使用
-
-Modern.js 框架对 SWC 插件进行了封装，你可以通过以下方式来使用：
-
-import EnableSWC from '@site-docs/components/enableSwc.mdx';
-
-<EnableSWC />
-
-That's it! 现在你可以在项目中无缝使用 SWC 的转译和压缩能力了。
-
-## 配置
-
-- **类型：**
-
-```ts
-type PluginConfig =
-  | ObjPluginConfig
-  | ((
-      config: ObjPluginConfig,
-      utils: { mergeConfig: typeof lodash.merge; setConfig: typeof lodash.set },
-    ) => ObjPluginConfig | void);
-
-// SwcOptions 为 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;
-}
-```
-
-插件配置在 SWC 配置的基础上，为了简化部分深层配置和为提高开发体验，进行了部分拓展，例如当使用对象形式配置时，可以使用 `presetReact` 以及 `presetEnv` 快速配置 react 以及语法降级相关功能，另外不属于插件特有的配置也会直接透传给 swc。
-
-当使用函数形式配置时，则会传入插件内部产出的默认配置，可以对其进行修改或返回新的配置。
-
-### presetReact
-
-- **类型：** SWC 中的 [react](https://swc.rs/docs/configuration/compilation#jsctransformreact) 配置。
-
-对标 `@babel/preset-react`。传入的值会与默认配置进行合并。
-
-插件默认会自动根据你的 `react` 版本确定 `runtime` 字段，如果 `react` 版本大于 17.0.0，会设置成 `automatic`，否则设置成 `classic`。
-
-### presetEnv
-
-- **类型：** SWC 中的 [presetEnv](https://swc.rs/docs/configuration/supported-browsers#options)。
-
-对标 `@babel/preset-env`。传入的值会与默认配置进行合并。
-默认配置为:
-
-```ts
-{
-  targets: '', // 自动从项目中获取 browserslist
-  mode: 'usage',
-}
-```
-
-### jsMinify
-
-- **类型：** `boolean` 或者 [terser 中的 compress 配置](https://terser.org/docs/api-reference.html#compress-options)。
-- **默认值：** `{ compress: {}, mangle: true }`。
-
-如果配置 `false` 将不会使用 SWC 的压缩能力，配置 `true` 会启用默认压缩配置，如果配置是对象，则会与默认配置进行合并。
-
-### cssMinify
-
-- **类型：** `boolean`
-- **默认值：** `true`
-
-是否启用 SWC 对 CSS 文件进行压缩，若启用会使得 CSS 压缩性能提高，但压缩率会略微降低。
-
-### overrides
-
-- **类型：**
-
-```ts
-interface Overrides extends SwcOptions {
-  test: RegExp;
-  include: RegExp[];
-  exclude: RegExp[];
-}
-```
-
-- **默认值：** `undefined`
-
-对指定文件运用另外的配置。例如需要对 `foo.ts` 的语法降级成 ie 11，则可以如下配置：
-
-```ts
-{
-  test: /foo.ts/,
-  env: { targets: 'ie 11' }
-}
-```
-
-该配置会与默认配置进行合并，并且不会影响到其他文件。
-
-### extensions
-
-- **类型：** `Object`
-
-`extensions` 包含了从 Babel 移植过来的一些插件能力。
-
-#### extensions.reactUtils
-
-- **类型：**
-
-```ts
-type ReactUtilsOptions = {
-  autoImportReact?: boolean;
-  removeEffect?: boolean;
-  removePropTypes?: {
-    mode?: 'remove' | 'unwrap' | 'unsafe-wrap';
-    removeImport?: boolean;
-    ignoreFilenames?: string[];
-    additionalLibraries?: string[];
-    classNameMatchers?: string[];
-  };
-};
-```
-
-一些用于 `React` 的工具，包括以下配置项:
-
-**reactUtils.autoImportReact**
-
-- **类型：** `boolean`
-
-自动引入 `React`, `import React from 'react'`，用于 `jsx` 转换使用 `React.createElement`。
-
-**reactUtils.removeEffect**
-
-- **类型：** `boolean`
-
-移除 `useEffect` 调用。
-
-**reactUtils.removePropTypes**
-
-- **类型：**
-
-```ts
-type RemovePropTypesOptions = {
-  mode?: 'remove' | 'unwrap' | 'unsafe-wrap';
-  removeImport?: boolean;
-  ignoreFilenames?: string[];
-  additionalLibraries?: string[];
-  classNameMatchers?: string[];
-};
-```
-
-移除 `React` 组件在运行时的类型判断。移植自 [@babel/plugin-react-transform-remove-prop-types](https://github.com/oliviertassinari/babel-plugin-transform-react-remove-prop-types)。
-
-相应配置和 `@babel/plugin-react-transform-remove-prop-types` 插件保持一致。
-
-#### extensions.lodash
-
-- **类型：**
-
-```ts
-type LodashOptions = {
-  cwd?: string;
-  ids?: string[];
-};
-```
-
-- **默认值：**
-
-```ts
-const defaultOptions = {
-  cwd: process.cwd(),
-  ids: ['lodash', 'lodash-es'],
-};
-```
-
-移植自 [babel-plugin-lodash](https://github.com/lodash/babel-plugin-lodash)，用于自动将 Lodash 的引用转换为按需引入，从而减少打包后的 Lodash 代码大小。
-
-```ts
-// Input
-import { get, throttle } from 'lodash';
-
-// Output
-import get from 'lodash/get';
-import throttle from 'lodash/throttle';
-```
-
-#### extensions.styledComponents
-
-- **类型：**
-
-```ts
-boolean | {
-  displayName?: boolean; // 默认开发模式开启, 生产模式关闭,
-  ssr?: boolean; // 默认开启
-  fileName?: boolean; // 默认开启
-  topLevelImportPaths?: string[]; // 默认空
-  meaninglessFileNames?: string[]; // 默认为 ["index"].
-  cssProp?: boolean; // 默认开启
-  namespace?: string; // 默认空
-};
-```
-
-由 Next.js 团队移植自 [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components)。
-
-#### extensions.emotion
-
-- **类型：**
-
-```ts
-boolean | {
-  sourceMap?: boolean, // 默认开启
-  autoLabel?: 'never' | 'dev-only' | 'always', // 默认 'dev-only'
-  // 默认 '[local]'.
-  // 允许的值为: `[local]` `[filename]` 以及 `[dirname]`
-  // 只有当 autoLabel 设置成 'dev-only' 或者 'always' 才会生效.
-  // 该配置允许你定义结果标签的格式，该格式的组成是字符串以及可以由方括号包裹字符串作为变量
-  // 例如对于 "my-classname--[local]"，其中的 [local] 会被替换成相应的变量
-  labelFormat?: string,
-  // 默认值 undefined.
-  // 该配置允许让编译器知道哪一个引入需要进行转换，所以如果你重导出了 emotion
-  // 的导出，你仍然可以使用该插件进行转换
-  importMap?: {
-    [packageName: string]: {
-      [exportName: string]: {
-        canonicalImport?: [string, string],
-        styledBaseImport?: [string, string],
-      }
-    }
-  },
-},
-```
-
-由 Next.js 团队移植自 [@emotion/babel-plugin](https://www.npmjs.com/package/@emotion/babel-plugin)。
-
-#### extensions.pluginImport
-
-:::tip
-Modern.js 提供了 [source.transformImport](/configure/app/source/transform-import) 配置项，因此你不需要手动配置 `extensions.pluginImport`。
-:::
-
-移植自 [babel-plugin-import](https://github.com/umijs/babel-plugin-import)，配置选项保持一致。
-
-一些配置可以传入函数，例如 `customName`，`customStyleName` 等，这些 JavaScript 函数会由 Rust 通过 Node-API 调用，这种调用会造成一些性能劣化。
-
-简单的函数逻辑其实可以通过模版语言来代替，因此`customName`，`customStyleName` 等这些配置除了可以传入函数，也可以传入字符串作为模版来代替函数，提高性能。
-
-我们以下面代码为例说明:
-
-```ts
-import { MyButton as Btn } from 'foo';
-```
-
-添加以下配置：
-
-```ts
-PluginSWC({
-  extensions: {
-    pluginImport: [
-      {
-        libraryName: 'foo',
-        customName: 'foo/es/{{ member }}',
-      },
-    ],
-  },
-});
-```
-
-其中的 `{{ member }}` 会被替换为相应的引入成员，转换后:
-
-```ts
-import Btn from 'foo/es/MyButton';
-```
-
-可以看出配置 `customName: "foo/es/{{ member }}"` 的效果等同于配置 `` customName: (member) => `foo/es/${member}`  ``，但是不会有 Node-API 的调用开销。
-
-这里使用到的模版是 [handlebars](https://handlebarsjs.com)，模版配置中还内置了一些有用的辅助工具，还是以上面的导入语句为例，配置成：
-
-```ts
-PluginSWC({
-  extensions: {
-    pluginImport: [
-      {
-        libraryName: 'foo',
-        customName: 'foo/es/{{ kebabCase member }}',
-      },
-    ],
-  },
-});
-```
-
-会转换成下面的结果:
-
-```ts
-import Btn from 'foo/es/my-button';
-```
-
-除了 `kebabCase` 以外还有 `camelCase`，`snakeCase`，`upperCase`，`lowerCase` 可以使用。
-
-## 限制
-
-不支持 `@babel/plugin-transform-runtime` 以及其他自定义的 Babel 插件。

package/docs/zh/plugin/official/cli-plugins/plugin-tailwind.mdx

@@ -1,5 +0,0 @@
-# Tailwind CSS 插件
-
-Tailwind CSS 是一个以 Utility Class 为基础的 CSS 框架和设计系统，可以快速地为组件添加常用样式，同时支持主题样式的灵活扩展。
-
-详细内容可以参考 [使用 Tailwind CSS](/guides/basic-features/css/tailwindcss)。

package/docs/zh/plugin/official/rsbuild-plugins/_meta.json

@@ -1 +0,0 @@
-["plugin-esbuild"]

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

@@ -1,201 +0,0 @@
----
-sidebar_position: 3
----
-
-# Esbuild 插件
-
-:::warning
-**当前文档中的 esbuild 功能已停止迭代**，我们更推荐使用 Rspack + SWC 的方案，因为 Rspack + SWC 具备更好的构建性能、功能丰富度和产物兼容性。
-
-请参考[「使用 Rspack」](guides/advanced-features/rspack-start)了解更多。
-
-:::
-
-import Esbuild from '@site-docs/components/esbuild.mdx';
-
-<Esbuild />
-
-## 快速开始
-
-### 在 Modern.js 框架中使用
-
-Modern.js 框架默认集成了 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 代码转译，此时 Modern.js 会继续使用 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 代码压缩，此时 Modern.js 会继续使用 Terser 进行代码压缩。
-
-```ts
-builderPluginEsbuild({
-  minimize: false,
-});
-```
-
-## esbuild 局限性
-
-虽然 esbuild 能给现有的 webpack 项目带来明显的构建性能提升，但这个工具在接入 Modern.js 时还存在一定的局限性，需要大家在接入的时候格外注意。
-
-### 兼容性
-
-使用 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 后无法使用。并且由于 Modern.js 底层使用的是 esbuild 的 `Transform API`，因此不支持使用额外 esbuild 插件来进行自定义编译过程。
-
-如果你有 `babel-plugin-import` 等 Babel 插件相关诉求，可以使用 SWC 插件。
-
-### 产物体积
-
-使用 esbuild 压缩虽然带来了构建效率上的提升，但 esbuild 的压缩比例是低于 terser 的，因此**构建产物的体积会增大**，请根据业务情况酌情使用。通常来说，esbuild 比较适合中后台等对体积不敏感的场景。
-
-对于压缩工具之间的详细对比，可以参考 [minification-benchmarks](https://github.com/privatenumber/minification-benchmarks)。

package/docs/zh/plugin/official/rsbuild-plugins.mdx

@@ -1,3 +0,0 @@
-# 概览
-
-- [@modern-js/plugin-esbuild](/plugin/official/rsbuild-plugins/plugin-esbuild)：提供 esbuild 编译支持。

package/docs/zh/plugin/runtime-plugins/migration.mdx

@@ -1,101 +0,0 @@
-# 插件迁移
-
-### 迁移背景
-
-Modern.js 插件系统持续演进，为了提供更清晰的 API 和更强大的功能，我们对 Runtime 插件的定义和使用方式进行了优化。虽然旧版插件写法部分仍被兼容，但我们强烈建议您按照本指南进行迁移，以充分利用新版插件系统的优势。
-
-### 迁移步骤总览
-
-1.  **更新插件类型定义**：将 `Plugin` 类型替换为 `RuntimePluginFuture`。
-2.  **调整 Hooks 调用方式**：从 `return hooks` 模式迁移到 `api.xxx` 直接调用。
-3.  **替换已变更的 API**：参照详细的 API 映射表，更新您的代码。
-
-### 详细迁移步骤
-
-#### 更新插件类型定义
-
-这是迁移的第一步，也是最关键的一步。它确保您的插件能够与新版插件系统正确交互。
-
-```typescript
-// 旧版写法
-import type { Plugin } from '@modern-js/runtime';
-
-const plugin: Plugin = { ... };
-
-// 新版写法
-import type { RuntimePluginFuture } from '@modern-js/runtime';
-
-const plugin: RuntimePluginFuture = { ... };
-```
-
-**说明：** `RuntimePluginFuture` 类型是新版插件的标准定义，它带来了更好的类型推断和更清晰的 API 结构。
-
-#### 调整 Hooks 调用方式
-
-新版插件系统推荐使用 `api` 对象直接调用 Hooks，这种方式更直观、更易于维护。
-
-```typescript
-// 旧版写法 (return hooks)
-{
-  setup: () => ({
-    beforeRender({ req, res }) { /*...*/ }
-  })
-}
-
-// 新版写法 (api.xxx)
-{
-  setup: api => {
-    api.onBeforeRender(({ req, res }) => { /*...*/ })
-  }
-}
-```
-
-**说明：** `api` 对象提供了所有可用的 Hooks 和工具方法。
-
-#### 替换已变更的 API
-
-为了保持 API 的一致性和清晰性，我们对部分 API 的名称进行了调整。同时，`hoc` 和 `init` 这两个 Hook 已被移除，请使用新的 Hook 进行替代。下表列出了所有变更的 API 及其新旧对应关系：
-
-| 旧版 API      | 新版 API          | 说明                                                                                                                     |
-| :------------ | :---------------- | :----------------------------------------------------------------------------------------------------------------------- |
-| `beforeRender` | `onBeforeRender`  | 在应用渲染前执行。                                                                                                       |
-| `hoc`         | `wrapRoot`        | **重要变更：** 用于包裹根组件，实现高阶组件 (HOC) 的功能。请确保将 props 传递给原始组件。                               |
-| `init`        | `onBeforeRender`  | **重要变更：** 在应用渲染前执行初始化逻辑。                                                                                 |
-
-**说明：**
-- `onBeforeRender` 替代了原来的 `beforeRender` 和 `init`，分别用于渲染前逻辑和初始化。
-- `wrapRoot` 替代了 `hoc`，用于实现高阶组件功能，使用时务必注意 props 的传递。
-
-**`wrapRoot` 使用示例：**
-
-```typescript
-{
-  setup: api => {
-    api.wrapRoot((App) => {
-      const AppWrapper = (props) => {
-        // 确保将 props 传递给原始组件
-        return <Provider value={xx}><App {...props}/></Provider>;
-      };
-      return AppWrapper;
-    });
-  }
-}
-```
-
-### 常见问题解答
-
-**Q: 迁移后，我的插件还能正常工作吗？**
-
-A: 只要您按照本指南正确完成了所有步骤，您的插件应该能够正常工作。如果您遇到任何问题，请查阅 Modern.js 的官方文档或寻求社区支持。
-
-**Q: 我必须立即迁移我的插件吗？**
-
-A: 虽然旧版插件写法仍然兼容，但我们强烈建议您尽快迁移。新版插件系统提供了更好的性能和更丰富的功能，长期来看，迁移是值得的。
-
-**Q: 我可以在哪里找到更多关于新版插件系统的信息？**
-
-A: 请查阅 Modern.js 的官方文档，特别是关于插件系统的部分。您也可以参考其他已迁移的插件示例，了解最佳实践。
-
-### 总结
-
-通过这份详细的迁移指南，我们希望能够帮助您顺利地将您的 Runtime 插件迁移到 Modern.js 的新版插件系统。如果您在迁移过程中遇到任何问题，请随时向我们寻求帮助。