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

package/docs/en/configure/app/tools/babel.mdx

@@ -1,225 +0,0 @@
----
-title: babel
----
-
-# tools.babel
-
-- **Type:** `Object | Function`
-- **Default:** `undefined`
-
-With `tools.babel` you can modify the options of [babel-loader](https://github.com/babel/babel-loader).
-
-### Usage Scenarios
-
-Please note the limitations of `tools.babel` in the following usage scenarios:
-
-- Rspack scenario: When using Rspack as the bundler, using the `tools.babel` option 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 SWC plugin for code compilation, the `tools.babel` option will not take effect.
-
-### Function Type
-
-When `tools.babel` is of type `Function`, the default Babel configuration will be passed as the first parameter. You can directly modify the configuration object or return an object as the final `babel-loader` configuration.
-
-```js
-export default {
-  tools: {
-    babel(config) {
-      // Add a Babel plugin
-      // note: the plugin have been added to the default config to support antd load on demand
-      config.plugins.push([
-        'babel-plugin-import',
-        {
-          libraryName: 'xxx-components',
-          libraryDirectory: 'es',
-          style: true,
-        },
-      ]);
-    },
-  },
-};
-```
-
-The second parameter of the `tools.babel` function provides some more convenient utility functions. Please continue reading the documentation below.
-
-:::tip
-The above example is just for reference, usually you don't need to manually configure `babel-plugin-import`, because Modern.js already provides a more general `source.transformImport` configuration.
-:::
-
-### Object Type
-
-When `tools.babel`'s type is `Object`, the config will be shallow merged with default config by `Object.assign`.
-
-:::caution
-Note that `Object.assign` is a shallow copy and will completely overwrite the built-in `presets` or `plugins` array, please use it with caution.
-:::
-
-```js
-export default {
-  tools: {
-    babel: {
-      plugins: [
-        [
-          'babel-plugin-import',
-          {
-            libraryName: 'xxx-components',
-            libraryDirectory: 'es',
-            style: true,
-          },
-        ],
-      ],
-    },
-  },
-};
-```
-
-### Util Functions
-
-When `tools.babel` is a Function, the tool functions available for the second parameter are as follows:
-
-#### addPlugins
-
-- **Type:** `(plugins: BabelPlugin[]) => void`
-
-Add some Babel plugins. For example:
-
-```js
-export default {
-  tools: {
-    babel(config, { addPlugins }) {
-      addPlugins([
-        [
-          'babel-plugin-import',
-          {
-            libraryName: 'xxx-components',
-            libraryDirectory: 'es',
-            style: true,
-          },
-        ],
-      ]);
-    },
-  },
-};
-```
-
-#### addPresets
-
-- **Type:** `(presets: BabelPlugin[]) => void`
-
-Add Babel preset configuration. (No need to add presets in most cases)
-
-```js
-export default {
-  tools: {
-    babel(config, { addPresets }) {
-      addPresets(['@babel/preset-env']);
-    },
-  },
-};
-```
-
-#### removePlugins
-
-- **Type:** `(plugins: string | string[]) => void`
-
-To remove the Babel plugin, just pass in the name of the plugin to be removed, you can pass in a single string or an array of strings.
-
-```js
-export default {
-  tools: {
-    babel(config, { removePlugins }) {
-      removePlugins('babel-plugin-import');
-    },
-  },
-};
-```
-
-#### removePresets
-
-- **Type:** `(presets: string | string[]) => void`
-
-To remove the Babel preset configuration, pass in the name of the preset to be removed, you can pass in a single string or an array of strings.
-
-```js
-export default {
-  tools: {
-    babel(config, { removePresets }) {
-      removePresets('@babel/preset-env');
-    },
-  },
-};
-```
-
-#### modifyPresetEnvOptions
-
-- **Type:** `(options: PresetEnvOptions) => void`
-
-Modify the configuration of [@babel/preset-env](https://babeljs.io/docs/en/babel-preset-env), the configuration you pass in will be shallowly merged with default config. For example:
-
-```js
-export default {
-  tools: {
-    babel(config, { modifyPresetEnvOptions }) {
-      modifyPresetEnvOptions({
-        targets: 'last 2 versions',
-      });
-    },
-  },
-};
-```
-
-```js
-export default {
-  tools: {
-    babel(config, { modifyPresetEnvOptions }) {
-      modifyPresetEnvOptions({
-        targets: {
-          chrome: '58',
-          ie: '11',
-        },
-      });
-    },
-  },
-};
-```
-
-#### modifyPresetReactOptions
-
-- **Type:** `(options: PresetReactOptions) => void`
-
-Modify the configuration of [@babel/preset-react](https://babeljs.io/docs/en/babel-preset-react), the configuration you pass in will be shallowly merged with default config. For example:
-
-```js
-export default {
-  tools: {
-    babel(config, { modifyPresetReactOptions }) {
-      modifyPresetReactOptions({
-        pragma: 'React.createElement',
-      });
-    },
-  },
-};
-```
-
-#### addIncludes
-
-Deprecated, please use [source.include](https://modernjs.dev/en/configure/app/source/include.html) instead, both have the same functionality.
-
-#### addExcludes
-
-Deprecated, please use [source.exclude](https://modernjs.dev/en/configure/app/source/exclude.html) instead, both have the same functionality.
-
-### Debugging Babel Configuration
-
-After modifying the `babel-loader` configuration through `tools.babel`, you can view the final generated configuration in [Rsbuild debug mode](https://rsbuild.rs/guide/debug/debug-mode).
-
-First, enable debug mode by using the `DEBUG=builder` parameter:
-
-```bash
-# Debug development mode
-DEBUG=builder pnpm dev
-
-# Debug production mode
-DEBUG=builder pnpm build
-```
-
-Then open the generated `(webpack|rspack).config.web.js` file and search for the `babel-loader` keyword to see the complete `babel-loader` configuration.

package/docs/en/plugin/cli-plugins/migration.mdx

@@ -1,83 +0,0 @@
-# Plugin Migration
-
-### Migration Background
-
-The Modern.js plugin system is constantly evolving. To provide a clearer API and more powerful features, we've optimized the definition and usage of CLI plugins. While the old plugin syntax is still supported for compatibility, we strongly recommend migrating according to this guide to take full advantage of the new plugin system.
-
-### Migration Steps Overview
-
-1.  **Adjust Hook Invocation:** Migrate from the `return hooks` pattern to direct `api.xxx` calls.
-2.  **Replace Changed APIs:** Refer to the detailed API mapping table and update your code.
-
-### Detailed Migration Steps
-
-#### Adjust Hook Invocation
-
-The new plugin system recommends using the `api` object to directly call Hooks. This approach is more intuitive and easier to maintain.
-
-```typescript
-// Old Syntax (return hooks)
-{
-  setup: () => ({
-    commands({ program }) {
-      /*...*/
-    },
-  });
-}
-
-// New Syntax (api.xxx)
-{
-  setup: api => {
-    api.addCommand(({ program }) => {
-      /*...*/
-    });
-  };
-}
-```
-
-**Explanation:** The `api` object provides all available Hooks and utility methods.
-
-#### Replace Changed APIs
-
-To maintain API consistency and clarity, we've adjusted the names of some APIs. The following table lists all changed APIs and their old and new counterparts:
-
-| Old API                    | New API                       | Description                                                                                                                 |
-| :------------------------- | :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
-| `useAppContext`            | `getAppContext`               | Gets the application context information.                                                                                   |
-| `useConfigContext`         | `getConfig`                   | Gets the configuration defined in the user's configuration file.                                                            |
-| `useResolvedConfigContext` | `getNormalizedConfig`         | Gets the final configuration after processing by plugins.                                                                   |
-| `beforeConfig`             | (Defined directly in `setup`) | The `beforeConfig` Hook is no longer needed. Write related logic directly in the `setup` function.                          |
-| `prepare`                  | `onPrepare`                   | The preparation stage before running the main process.                                                                      |
-| `afterPrepare`             | `onAfterPrepare` (Deprecated) | Executes after `onPrepare`, but may be deprecated in future versions. It's recommended to merge the logic into `onPrepare`. |
-| `beforePrintInstructions`  | `onBeforePrintInstructions`   | Executes before printing log messages.                                                                                      |
-| `commands`                 | `addCommand`                  | Adds a new CLI command.                                                                                                     |
-| `watchFiles`               | `addWatchFiles`               | Adds files to be watched.                                                                                                   |
-| `fileChange`               | `onFileChanged`               | Listens for file change events.                                                                                             |
-| `beforeCreateCompiler`     | `onBeforeCreateCompiler`      | Executes before creating the compiler.                                                                                      |
-| `afterCreateCompiler`      | `onAfterCreateCompiler`       | Executes after creating the compiler.                                                                                       |
-| `beforeBuild`              | `onBeforeBuild`               | Executes before building.                                                                                                   |
-| `afterBuild`               | `onAfterBuild`                | Executes after building.                                                                                                    |
-| `beforeDev`                | `onBeforeDev`                 | Executes before running the `dev` command.                                                                                  |
-| `afterDev`                 | `onDevCompileDone`            | Executes after the `dev` command compilation is complete.                                                                   |
-| `beforeExit`               | `onBeforeExit`                | Executes before the process exits.                                                                                          |
-| `htmlPartials`             | `modifyHtmlPartials`          | Modifies HTML template partials.                                                                                            |
-
-**Explanation:** Please carefully review your code and ensure that all old APIs have been replaced with the new APIs.
-
-### Frequently Asked Questions
-
-**Q: Will my plugin still work after the migration?**
-
-A: As long as you have correctly completed all the steps in this guide, your plugin should work normally. If you encounter any problems, please refer to the official Modern.js documentation or seek community support.
-
-**Q: Do I have to migrate my plugin immediately?**
-
-A: While the old plugin syntax is still supported, we strongly recommend migrating as soon as possible. The new plugin system offers better performance and richer features, and migration is worthwhile in the long run.
-
-**Q: Where can I find more information about the new plugin system?**
-
-A: Please refer to the official Modern.js documentation, especially the section on the plugin system. You can also refer to examples of other migrated plugins to understand best practices.
-
-### Summary
-
-With this detailed migration guide, we hope to help you smoothly migrate your CLI plugins to the new Modern.js plugin system. If you encounter any problems during the migration, please feel free to ask us for help.

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

@@ -1,110 +0,0 @@
-# Plugin Migration
-
-### Migration Background
-
-The Modern.js plugin system is constantly evolving. To provide a clearer API and more powerful features, we've optimized the definition and usage of Runtime plugins. While the old plugin syntax is still partially compatible, we strongly recommend migrating according to this guide to take full advantage of the new plugin system.
-
-### Migration Steps Overview
-
-1.  **Update Plugin Type Definition:** Replace the `Plugin` type with `RuntimePlugin`.
-2.  **Adjust Hook Invocation:** Migrate from the `return hooks` pattern to direct `api.xxx` calls.
-3.  **Replace Changed APIs:** Refer to the detailed API mapping table and update your code.
-
-### Detailed Migration Steps
-
-#### Update Plugin Type Definition
-
-This is the first and most crucial step. It ensures that your plugin interacts correctly with the new plugin system.
-
-```typescript
-// Old Syntax
-import type { Plugin } from '@modern-js/runtime';
-
-const plugin: Plugin = { ... };
-
-// New Syntax
-import type { RuntimePlugin } from '@modern-js/runtime';
-
-const plugin: RuntimePlugin = { ... };
-```
-
-**Explanation:** The `RuntimePlugin` type is the standard definition for new plugins. It provides better type inference and a clearer API structure.
-
-#### Adjust Hook Invocation
-
-The new plugin system recommends using the `api` object to directly call Hooks. This approach is more intuitive and easier to maintain.
-
-```typescript
-// Old Syntax (return hooks)
-{
-  setup: () => ({
-    beforeRender({ req, res }) {
-      /*...*/
-    },
-  });
-}
-
-// New Syntax (api.xxx)
-{
-  setup: api => {
-    api.onBeforeRender(({ req, res }) => {
-      /*...*/
-    });
-  };
-}
-```
-
-**Explanation:** The `api` object provides all available Hooks and utility methods.
-
-#### Replace Changed APIs
-
-To maintain API consistency and clarity, we've adjusted the names of some APIs. Additionally, the `hoc` and `init` Hooks have been removed. Please use the new Hooks as replacements. The table below lists all changed APIs and their old and new counterparts:
-
-| Old API        | New API          | Description                                                                                                                                                                                                                                                                                       |
-| :------------- | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `beforeRender` | `onBeforeRender` | Executed before application rendering.                                                                                                                                                                                                                                                            |
-| `hoc`          | `wrapRoot`       | **Important Change:** Used to wrap the root component, achieving the functionality of a Higher-Order Component (HOC). Make sure to pass props to the original component.                                                                                                                          |
-| `init`         | `onBeforeRender` | **Important Change:** Execute initialization logic before application rendering. This replaces the previous `init` hook. Use `onBeforeRender` to perform any setup or initialization tasks that were previously done in `init`. This provides a single, consistent point for pre-rendering logic. |
-
-**Explanation:**
-
-- `onBeforeRender` replaces both the original `beforeRender` and `init`, used for pre-rendering logic and initialization, respectively.
-- `wrapRoot` replaces `hoc` and is used to implement higher-order component functionality. It's crucial to pass props correctly when using `wrapRoot`.
-
-**`wrapRoot` Usage Example:**
-
-```typescript
-{
-  setup: api => {
-    api.wrapRoot(App => {
-      const AppWrapper = props => {
-        // Ensure props are passed to the original component
-        return (
-          <Provider value={xx}>
-            <App {...props} />
-          </Provider>
-        );
-      };
-      return AppWrapper;
-    });
-  };
-}
-```
-
-### Frequently Asked Questions
-
-**Q: Will my plugin still work correctly after migration?**
-
-A: As long as you've correctly completed all the steps in this guide, your plugin should function properly. If you encounter any issues, please refer to the official Modern.js documentation or seek community support.
-
-**Q: Do I have to migrate my plugin immediately?**
-
-A: While the old plugin syntax remains partially compatible, we strongly recommend migrating as soon as possible. The new plugin system offers improved performance and richer functionality, making migration worthwhile in the long run.
-
-**Q: Where can I find more information about the new plugin system?**
-
-A: Please consult the official Modern.js documentation, especially the section on the plugin system. You can also refer to examples of other migrated plugins to understand best practices.
-
-### Summary
-
-With this detailed migration guide, we hope to help you smoothly transition your Runtime plugins to the new Modern.js plugin system. If you encounter any problems during the migration process, please don't hesitate to ask for assistance.

package/docs/zh/components/default-mwa-generate.mdx

@@ -1,4 +0,0 @@
-```bash
-? 请选择开发语言：TS
-? 请选择包管理工具：pnpm
-```

package/docs/zh/configure/app/performance/bundle-analyze.mdx

@@ -1,24 +0,0 @@
----
-title: bundleAnalyze
----
-
-# performance.bundleAnalyze
-
-- **类型：** `Object | undefined`
-
-用于开启 [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) 插件来分析产物体积。
-
-默认情况下，Modern.js 不会开启 `webpack-bundle-analyzer`。当开启该功能后，内部的默认配置如下:
-
-```js
-const defaultConfig = {
-  analyzerMode: 'static',
-  openAnalyzer: false,
-  // target 为编译目标，如 `web`、`node` 等
-  reportFilename: `report-${target}.html`,
-};
-```
-
-import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
-
-<RsbuildConfig configName="performance.bundleAnalyze" />

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

@@ -1,224 +0,0 @@
----
-title: babel
----
-
-# tools.babel
-
-- **类型：** `Object | Function`
-- **默认值：** `undefined`
-
-通过 `tools.babel` 可以修改 [babel-loader](https://github.com/babel/babel-loader) 的配置项。
-
-### 使用场景
-
-请留意 `tools.babel` 在以下使用场景中的局限性：
-
-- Rspack 场景：在使用 Rspack 作为打包工具时，使用 `tools.babel` 配置项将会明显拖慢 Rspack 构建速度。因为 Rspack 默认使用的是 SWC 编译，配置 Babel 会导致代码需要被编译两次，产生了额外的编译开销。
-- webpack + SWC 场景：在使用 webpack 作为打包工具时，如果你使用了 SWC 插件进行代码编译，那么 `tools.babel` 选项将不会生效。
-
-### Function 类型
-
-当 `tools.babel` 为 Function 类型时，默认 Babel 配置会作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终的 `babel-loader` 配置。
-
-```js
-export default {
-  tools: {
-    babel(config) {
-      // 添加一个插件，比如配置某个组件库的按需引入
-      config.plugins.push([
-        'babel-plugin-import',
-        {
-          libraryName: 'xxx-components',
-          libraryDirectory: 'es',
-          style: true,
-        },
-      ]);
-    },
-  },
-};
-```
-
-`tools.babel` 函数的第二个参数提供了一些方便的工具函数，请继续阅读下方文档。
-
-:::tip
-以上示例仅作为参考，通常来说，你不需要手动配置 `babel-plugin-import`，因为 Modern.js 已经提供了更通用的 `source.transformImport` 配置。
-:::
-
-### Object 类型
-
-当 `tools.babel` 的值为 `Object` 类型时，会与默认配置通过 `Object.assign` 浅合并。
-
-:::caution
-`Object.assign` 是浅拷贝，会完全覆盖内置的 `presets` 或 `plugins` 数组，导致内置的 presets 或 plugins 失效，请在明确影响面的情况下再使用这种方式。
-:::
-
-```js
-export default {
-  tools: {
-    babel: {
-      plugins: [
-        [
-          'babel-plugin-import',
-          {
-            libraryName: 'xxx-components',
-            libraryDirectory: 'es',
-            style: true,
-          },
-        ],
-      ],
-    },
-  },
-};
-```
-
-### 工具函数
-
-`tools.babel` 为 Function 类型时，第二个参数可用的工具函数如下:
-
-#### addPlugins
-
-- **类型：** `(plugins: BabelPlugin[]) => void`
-
-添加若干个 Babel 插件。
-
-```js
-export default {
-  tools: {
-    babel(config, { addPlugins }) {
-      addPlugins([
-        [
-          'babel-plugin-import',
-          {
-            libraryName: 'xxx-components',
-            libraryDirectory: 'es',
-            style: true,
-          },
-        ],
-      ]);
-    },
-  },
-};
-```
-
-#### addPresets
-
-- **类型：** `(presets: BabelPlugin[]) => void`
-
-添加若干个 Babel 预设配置 (大多数情况下不需要增加预设)。
-
-```js
-export default {
-  tools: {
-    babel(config, { addPresets }) {
-      addPresets(['@babel/preset-env']);
-    },
-  },
-};
-```
-
-#### removePlugins
-
-- **类型：** `(plugins: string | string[]) => void`
-
-移除 Babel 插件，传入需要移除的插件名称即可，你可以传入单个字符串，也可以传入一个字符串数组。
-
-```js
-export default {
-  tools: {
-    babel(config, { removePlugins }) {
-      removePlugins('babel-plugin-import');
-    },
-  },
-};
-```
-
-#### removePresets
-
-- **类型：** `(presets: string | string[]) => void`
-
-移除 Babel 预设配置，传入需要移除的预设名称即可，你可以传入单个字符串，也可以传入一个字符串数组。
-
-```js
-export default {
-  tools: {
-    babel(config, { removePresets }) {
-      removePresets('@babel/preset-env');
-    },
-  },
-};
-```
-
-#### modifyPresetEnvOptions
-
-- **类型：** `(options: PresetEnvOptions) => void`
-
-修改 [@babel/preset-env](https://babeljs.io/docs/en/babel-preset-env) 的配置项，传入的配置会与默认配置进行浅层合并，比如:
-
-```js
-export default {
-  tools: {
-    babel(config, { modifyPresetEnvOptions }) {
-      modifyPresetEnvOptions({
-        targets: 'last 2 versions',
-      });
-    },
-  },
-};
-```
-
-```js
-export default {
-  tools: {
-    babel(config, { modifyPresetEnvOptions }) {
-      modifyPresetEnvOptions({
-        targets: {
-          chrome: '58',
-          ie: '11',
-        },
-      });
-    },
-  },
-};
-```
-
-#### modifyPresetReactOptions
-
-- **类型：** `(options: PresetReactOptions) => void`
-
-修改 [@babel/preset-react](https://babeljs.io/docs/en/babel-preset-react) 的配置项，传入的配置会与默认配置进行浅层合并，比如:
-
-```js
-export default {
-  tools: {
-    babel(config, { modifyPresetReactOptions }) {
-      modifyPresetReactOptions({
-        pragma: 'React.createElement',
-      });
-    },
-  },
-};
-```
-
-#### addIncludes
-
-已废弃，请使用 [source.include](https://modernjs.dev/configure/app/source/include.html) 代替，两者功能完全一致。
-
-#### addExcludes
-
-已废弃，请使用 [source.exclude](https://modernjs.dev/configure/app/source/exclude.html) 代替，两者功能完全一致。
-
-### 调试 Babel 配置
-
-当你通过 `tools.babel` 修改 `babel-loader` 配置后，可以在 [调试模式](https://rsbuild.rs/zh/guide/debug/debug-mode) 下查看最终生成的配置。
-
-首先通过 `DEBUG=builder` 参数开启调试模式：
-
-```bash
-# 调试开发环境
-DEBUG=builder pnpm dev
-
-# 调试生产环境
-DEBUG=builder pnpm build
-```
-
-然后打开生成的 `(webpack|rspack).config.web.js`，搜索 `babel-loader` 关键词，即可看到完整的 `babel-loader` 配置内容。