@modern-js/main-doc 2.59.0 → 2.60.1-alpha.0

package/docs/en/_meta.json

@@ -4,21 +4,26 @@
     "link": "/guides/get-started/introduction",
     "activeMatch": "/guides/"
   },
-  {
-    "text": "tutorials",
-    "link": "/tutorials/foundations/introduction",
-    "activeMatch": "/tutorials/"
-  },
   {
     "text": "configure",
     "link": "/configure/app/usage",
     "activeMatch": "/configure/"
   },
+  {
+    "text": "plugin-menu",
+    "link": "/plugin/introduction",
+    "activeMatch": "/plugin/"
+  },
   {
     "text": "apis",
     "link": "/apis/app/commands",
     "activeMatch": "/apis/"
   },
+  {
+    "text": "tutorials",
+    "link": "/tutorials/foundations/introduction",
+    "activeMatch": "/tutorials/"
+  },
   {
     "text": "community",
     "link": "/community/showcase",

package/docs/en/apis/app/hooks/api/lambda.mdx

@@ -4,54 +4,10 @@ sidebar_position: 3
 ---
 # lambda/*.[tj]s
 
-Files that declare API routes under the [BFF Framework Mode](/guides/advanced-features/bff/type.html#framework-mode). Except for [convention files](/apis/app/hooks/api/api#allow-list), files under the `lambda/` directory will be registered as the routes.
-
-:::info
-Using the `api` directory requires enabling the BFF function, and you need to run the new command to enable the "BFF" function under the project.
+After enabling BFF, the files under the `lambda/` directory will be registered as BFF routes according to conventions.
 
+:::note
+The files can be written in `js` or `ts` languages, but they must use `esm` syntax to export functions.
 :::
 
-:::tip
-This file supports using `js` or `ts` language, but must export functions using `esm` syntax.
-
-:::
-
-## Routing File Convention
-
-### Default Routing
-
-The routing system will map files named `index` to the previous directory.
-
-- `api/lambda/index.ts` -> `$BASENAME/`
-- `api/lambda/user/index.ts` -> `$BASENAME/user`
-
-### Nested Routing
-
-The routing system also supports parsing nested files. If you create a nested folder structure, the files will still automatically resolve routes in the same way.
-
-- `api/lambda/hello.ts` -> `$BASENAME/hello`
-- `api/lambda/user/list.ts` -> `$BASENAME/user/list`
-
-### Dynamic Routing
-
-The routing system supports generating dynamic routes through file directories named with `[]`.
-
-- `api/lambda/user/[username]/info.ts` -> `$BASENAME/user/:username/info`
-- `api/lambda/user/[username]/delete.ts` -> `$BASENAME/user/:username/delete`
-- `api/lambda/article/[id]/info.ts` -> `$BASENAME/article/:id/info`
-
-The `$BASENAME` can be configured in `modern.config.js`, and the default value is `/api`.
-
-### Allow List
-
-By default, all files in the `lambda` directory are parsed as BFF function files, but we also set up a whitelist so that these files are not parsed:
-
-- Files named starting with `_`. For example: `_utils.ts`.
-- All files in a folder named starting with `_`. For example: `_utils/index.ts`, `_utils/cp.ts`.
-- Test files. For example: `foo.test.ts`.
-- TypeScript type files. For example: `hello.d.ts`.
-- Files under `node_module`.
-
-## Function Definition
-
-Completely consistent with the [Function Definition](/apis/app/hooks/api/api#function-definition) under the function mode.
+For detailed information, refer to [BFF API Routes](/guides/advanced-features/bff/function.html#api-routes).

package/docs/en/apis/app/hooks/api/middleware.mdx

@@ -0,0 +1,11 @@
+---
+title: _app.[tj]s
+sidebar_position: 2
+---
+# _app.[tj]s
+
+This file can add pre-middleware to BFF functions. For detailed information, refer to [Extend BFF Server](/guides/advanced-features/bff/extend-server).
+
+:::note
+For specific examples, please refer to [hook](/apis/app/runtime/bff/hook).
+:::

package/docs/en/community/blog/v2-release-note.mdx

@@ -132,7 +132,7 @@ Modern.js 可以划分为三个核心部分：**CLI 工具、服务端和运行
 
 在字节跳动内部，我们借助这些插件 API，结合公司内的基建和平台，封装出内部的企业级框架。如果你需要对 Modern.js 框架进行深度定制，也可以借助这些插件 API 来完成。
 
-> 如果你对 Modern.js 的插件系统感兴趣，请阅读 [「Modern.js - 自定义插件」](https://modernjs.dev/guides/topic-detail/framework-plugin/introduction.html)文档。
+> 如果你对 Modern.js 的插件系统感兴趣，请阅读 [「Modern.js - 自定义插件」](https://modernjs.dev/plugin/plugin-system/introduction.html)文档。
 
 ### 嵌套路由
 

package/docs/en/community/contributing-guide.mdx

@@ -186,7 +186,6 @@ You can find all the documentation in the `packages/document` folder:
 root
 └─ packages
    └─ document
-       ├─ builder-doc    # Documentation for Modern.js Builder
        ├─ main-doc       # Documentation for Modern.js Framework
        └─ module-doc     # Documentation for Modern.js Module
 ```

package/docs/en/components/builder.mdx

@@ -0,0 +1,3 @@
+Refers to the build layer of Modern.js. The goal of Builder is to provide Modern.js users with out-of-the-box build capabilities and support seamless switching between webpack and Rspack.
+
+The previous version of Modern.js `MAJOR_VERSION.46.0` used `@modern-js/builder`, which was upgraded to [Rsbuild](https://rsbuild.dev/) starting from `MAJOR_VERSION.46.0`.

package/docs/en/components/bundler.mdx

@@ -0,0 +1,3 @@
+Refers to module bundlers such as [webpack](https://webpack.js.org/), [Rspack](https://www.rspack.dev/).
+
+The main goal of bundlers is to bundle JavaScript, CSS and other files together, and the bundled files can be used in the browser, Node.js or other environments. When bundler processes the Web application, it builds a dependency graph and then combines every module into one or more bundles.

package/docs/en/components/enable-bff.mdx

@@ -1,5 +1,22 @@
-1. Execute `pnpm new` and select "Enable BFF"
-2. Add the following code to `modern.config.[tj]s` according to the chosen runtime framework:
+import { PackageManagerTabs } from '@theme';
+
+1. Execute the `new` command:
+
+<PackageManagerTabs command="run new" />
+
+2. Follow the prompts to **enable BFF functionality**:
+
+```bash
+? Please select the operation you want to perform Enable optional features
+? Please select the feature to enable Enable "BFF"
+? Please select BFF type Framework mode
+```
+
+:::note
+Currently, it is recommended to create BFF in framework mode. We will remove the BFF type concept in the future.
+:::
+
+3. Depending on the chosen runtime framework, add the following code to `modern.config.[tj]s`:
 
 import { Tabs, Tab as TabItem } from "@theme";
 

package/docs/en/components/enableSwc.mdx

@@ -0,0 +1,17 @@
+First, you need to execute `pnpm run new` to enable the SWC compile:
+
+```bash
+? Please select the operation you want: Enable features
+? Please select the feature name: Enable SWC Compile
+```
+
+After the installation, please register the SWC plugin in the `modern.config.ts` file, then the SWC compilation and compression will be enabled.
+
+```ts title="modern.config.ts"
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { swcPlugin } from '@modern-js/plugin-swc';
+
+export default defineConfig({
+  plugins: [appTools(), swcPlugin()],
+});
+```

package/docs/en/components/esbuild.mdx

@@ -0,0 +1,3 @@
+[esbuild](https://esbuild.github.io/) is a front-end build tool based on Golang. It has the functions of bundling, compiling and minimizing JavaScript code. Compared with traditional tools, the performance is significantly improved. When minimizing code, compared to webpack's built-in terser minimizer, esbuild has dozens of times better performance.
+
+Modern.js provides esbuild plugin that allow you to use esbuild instead of babel-loader, ts-loader and terser for transformation and minification process. When you enable esbuild in a large project, **it can greatly reduce the time required for code compilation and compression, while effectively avoiding OOM (heap out of memory) problems**.

package/docs/en/components/extend-bff-function.mdx

@@ -0,0 +1,5 @@
+The standard BFF function writing method may not always meet your needs. We are designing a more powerful BFF function writing method to allow developers to extend BFF functions more conveniently.
+
+:::note
+Coming soon
+:::

package/docs/en/components/micro-frontend.mdx

@@ -0,0 +1,6 @@
+Micro-frontend (MFE) is an architecture style similar to microservices. It is a composition of multiple independently delivered frontend applications, forming a cohesive whole. MFE decomposes frontend applications into smaller, simpler applications that can be developed, tested, and deployed independently while still appearing as a cohesive single product to users.
+
+It primarily addresses two problems:
+
+- Difficulty in maintaining large and complex applications as they evolve over time.
+- Inefficiency caused by cross-team or cross-department collaboration in project development.

package/docs/en/components/module-federation.mdx

@@ -0,0 +1,7 @@
+Module Federation (MF) is a feature of Webpack. It allows a JavaScript application to dynamically load code from another application, and in the process, share dependencies. If an application consuming a federated module does not have a dependency needed by the federated code, Webpack will download the missing dependency from that federated build origin.
+
+This allows for the creation of micro-frontend-style applications, where multiple systems can share code and be dynamically updated without having to rebuild the entire application.
+
+Modern.js provides an example project for Module Federation. Please refer to [module-federation-examples - modernjs](https://github.com/module-federation/module-federation-examples/tree/db5bdbeee56f779999a2c591fc553eb94eb20b36/modernjs).
+
+You can also read the [webpack Module Federation documentation](https://webpack.js.org/concepts/module-federation/) to learn more concepts.

package/docs/en/components/nodeVersion.mdx

@@ -0,0 +1,26 @@
+Before getting started, you will need to install [Node.js](https://nodejs.org/), and ensure that your Node.js version is higher than 16.2.0. **We recommend using the LTS version of Node.js 18.**
+
+You can check the currently used Node.js version with the following command:
+
+```bash
+node -v
+```
+
+If you do not have Node.js installed in your current environment, or the installed version is lower than 16.2.0, you can use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm) to install the required version.
+
+Here is an example of how to install the Node.js 18 LTS version via nvm:
+
+```bash
+# Install the long-term support version of Node.js 18
+nvm install 18 --lts
+
+# Make the newly installed Node.js 18 as the default version
+nvm alias default 18
+
+# Switch to the newly installed Node.js 18
+nvm use 18
+```
+
+:::tip nvm and fnm
+Both nvm and fnm are Node.js version management tools. Relatively speaking, nvm is more mature and stable, while fnm is implemented using Rust, which provides better performance than nvm.
+:::

package/docs/en/components/prerequisites.mdx

@@ -1,6 +1,6 @@
 ### Node.js
 
-import NodeVersion from '@modern-js/builder-doc/docs/en/shared/nodeVersion.md';
+import NodeVersion from '@site-docs-en/components/nodeVersion.mdx';
 
 <NodeVersion />
 

package/docs/en/components/rsbuild-config-tooltip.mdx

@@ -0,0 +1,5 @@
+import RsbuildLInk from '@site/src/components/RsbuildLink';
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to <RsbuildLInk configName={frontmatter.configName}/>.
+:::

package/docs/en/components/rsbuild.mdx

@@ -0,0 +1,3 @@
+[Rsbuild](https://rsbuild.dev/) is an Rspack-based build tool for the web. The main goal of Rsbuild is to provide out-of-the-box build capabilities for Rspack users, allowing developers to start a web project with zero configuration.
+
+Rsbuild integrates high-performance Rust-based tools from the community, including Rspack and SWC, to provide first-class build speed and development experience.

package/docs/en/components/rspack.mdx

@@ -0,0 +1,3 @@
+[Rspack](https://www.rspack.dev/) is a high performance JavaScript bundler written in Rust. It offers strong compatibility with the webpack ecosystem, allowing for seamless replacement of webpack, and provides lightning fast build speeds.
+
+Compared to webpack, Rspack has significantly improved build performance, thanks not only to the language advantages brought by Rust, but also to its parallel architecture and incremental compilation features. Benchmarking has shown that Rspack can provide 5-10 times better compilation performance.

package/docs/en/components/rspackPrecautions.mdx

@@ -0,0 +1,6 @@
+## Precautions
+
+Before using Rspack, you need to be aware of the following:
+
+- Rspack is compatible with most webpack plugins and almost all loaders, but there are still a few webpack plugins that cannot be used for now. For more details, see [Plugin Compatibility](https://rspack.dev/guide/compatibility/plugin).
+- Rspack uses [SWC](https://rspack.dev/guide/features/builtin-swc-loader) by default for code transformation and compression. In rare cases, you may encounter bugs in SWC in edge cases. You can provide feedback via [SWC issues](https://github.com/swc-project/swc/issues).

package/docs/en/components/rspackTip.mdx

@@ -0,0 +1,7 @@
+:::tip Rspack - A High Performance JavaScript Bundler
+
+import Rspack from './rspack.mdx';
+
+<Rspack />
+
+:::

package/docs/en/components/swc.mdx

@@ -0,0 +1,3 @@
+[SWC](https://SWC.rs/) (Speedy Web Compiler) is a transformer and minimizer for JavaScript and TypeScript based on `Rust`. SWC can provide the same abilities with Babel, and it's more than 10x faster than Babel.
+
+Modern.js has a out-of-box plugin for SWC, power your Web application with Polyfill and minification, we also port some common used Babel plugins to SWC.

package/docs/en/configure/app/auto-load-plugin.mdx

@@ -9,6 +9,10 @@ sidebar_position: 22
 
 Used to configure whether Modern.js enables auto-registration of plugins.
 
+:::warning
+This configuration is not recommended. Compared with manually registering plugin, this configuration is relatively black box and cannot add custom configurations to plugin.
+:::
+
 ### Manual Registration Plugin
 
 By default, installing the plugin requires you to register the plugin manually in the `modern.config.ts`.

package/docs/en/configure/app/dev/asset-prefix.mdx

@@ -1,9 +1,19 @@
 ---
 title: assetPrefix
+configName: dev.assetPrefix
 ---
 
 # dev.assetPrefix
 
-import Main from '@modern-js/builder-doc/docs/en/config/dev/assetPrefix.md';
+- **Type:** `boolean | string | 'auto'`
+- **Default:** `'/'`
 
-<Main />
+This configuration item is used to set the URL prefix of static resources in **development mode**.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />
+
+:::warning
+Please note that this configuration item is only applicable in development mode. In production mode, please use the [output.assetPrefix](/configure/app/output/asset-prefix) configuration item for setting.
+:::

package/docs/en/configure/app/dev/before-start-url.mdx

@@ -4,6 +4,18 @@ title: beforeStartUrl
 
 # dev.beforeStartUrl
 
-import Main from '@modern-js/builder-doc/docs/en/config/dev/beforeStartUrl.md';
+- **Type:** `() => Promise<void> | void`
+- **Default:** `undefined`
 
-<Main />
+`dev.beforeStartUrl` is used to execute a callback function before opening the `startUrl`, this config needs to be used together with `dev.startUrl`.
+
+```js
+export default {
+  dev: {
+    startUrl: true,
+    beforeStartUrl: async () => {
+      await doSomeThing();
+    },
+  },
+};
+```

package/docs/en/configure/app/dev/client.mdx

@@ -1,27 +1,25 @@
 ---
 title: client
+configName: dev.client
 ---
 
 # dev.client
 
-Configure the client code injected by Modern.js during the development process. This can be used to set the WebSocket URL for HMR.
-
 - **Type:**
 
 ```ts
 type Client = {
-  /** Specify the protocol name for the WebSocket request */
+  // The protocol name for the WebSocket request
   protocol?: 'ws' | 'wss';
-  /** Specify the path for the WebSocket request */
+  // The path for the WebSocket request
   path?: string;
-  /** Specify the port number for the WebSocket request */
-  port?: string;
-  /** Specify the host for the WebSocket request */
+  // The port number for the WebSocket request
+  port?: string | number;
+  // The host for the WebSocket request
   host?: string;
-  /**
-   * Shows overlay in the browser when there are compiler errors
-   * This feature requires the current browser version to support [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)
-   */
+  // The maximum number of reconnection attempts after a WebSocket request is disconnected.
+  reconnect?: number;
+  // Whether to display an error overlay in the browser when a compilation error occurs
   overlay?: boolean;
 };
 ```
@@ -31,12 +29,18 @@ type Client = {
 ```js
 const defaultConfig = {
   path: '/webpack-hmr',
-  // Defaults to the port number of the dev server
-  port: '',
-  host: location.hostname,
-  protocol: location.protocol === 'https:' ? 'wss' : 'ws',
+  port: '<port>',
+  // By default it is set to "location.hostname"
+  host: '',
+  // By default it is set to "location.protocol === 'https:' ? 'wss' : 'ws'""
+  protocol: undefined,
+  reconnect: 100,
   overlay: false,
 };
 ```
 
-For detailed usage, please refer to [Rsbuild - dev.client](https://rsbuild.dev/config/dev/client).
+Configure the client code injected by Modern.js during the development process. This can be used to set the WebSocket URL for HMR.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/dev/hmr.mdx

@@ -1,9 +1,15 @@
 ---
 title: hmr
+configName: dev.hmr
 ---
 
 # dev.hmr
 
-import Main from '@modern-js/builder-doc/docs/en/config/dev/hmr.md';
+- **Type:** `boolean`
+- **Default:** `true`
 
-<Main />
+Whether to enable Hot Module Replacement.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/dev/host.mdx

@@ -4,6 +4,19 @@ title: host
 
 # dev.host
 
-import Main from '@modern-js/builder-doc/docs/en/config/dev/host.md';
+- **Type:** `string`
+- **Default:** `0.0.0.0`
 
-<Main />
+Specify the host that the dev server listens to.
+
+By default, the dev server will listen to `0.0.0.0`, which means listening to all network interfaces, including `localhost` and public network addresses.
+
+If you want the dev server to listen only on `localhost`, you can set it to:
+
+```ts
+export default {
+  dev: {
+    host: 'localhost',
+  },
+};
+```

package/docs/en/configure/app/dev/https.mdx

@@ -4,6 +4,75 @@ title: https
 
 # dev.https
 
-import Main from '@modern-js/builder-doc/docs/en/config/dev/https.md';
+- **Type:** `boolean | { key: string; cert: string }`
+- **Default:** `false`
+
+After configuring this option, you can enable HTTPS Dev Server, and disabling the HTTP Dev Server.
+
+HTTP:
+
+```bash
+  > Local: http://localhost:8080/
+  > Network: http://192.168.0.1:8080/
+```
+
+HTTPS:
+
+```bash
+  > Local: https://localhost:8080/
+  > Network: https://192.168.0.1:8080/
+```
+
+#### Automatically generate certificates
+
+You can directly set `https` to `true`, Modern.js will automatically generate the HTTPS certificate based on [devcert](https://github.com/davewasmer/devcert).
+
+When using this method, you need to manually install the [devcert](https://github.com/davewasmer/devcert) dependency in your project:
+
+```bash
+# npm
+npm install devcert@1.2.2 -D
+
+# yarn
+yarn add devcert@1.2.2 -D
+
+# pnpm
+pnpm add devcert@1.2.2 -D
+```
+
+Then configure `dev.https` to `true`:
+
+```ts
+export default {
+  dev: {
+    https: true,
+  },
+};
+```
+
+The devcert has some limitations, it does not currently support IP addresses yet.
+
+:::tip
+The 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.https` option. This parameter will be directly passed to the createServer method of the https module in Node.js.
+
+For details, please refer to [https.createServer](https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener).
+
+```ts
+import fs from 'fs';
+
+export default {
+  dev: {
+    https: {
+      key: fs.readFileSync('certificates/private.pem'),
+      cert: fs.readFileSync('certificates/public.pem'),
+    },
+  },
+};
+```
 
-<Main />

package/docs/en/configure/app/dev/live-reload.mdx

@@ -1,5 +1,6 @@
 ---
 title: liveReload
+configName: dev.liveReload
 ---
 
 # dev.liveReload
@@ -9,19 +10,6 @@ title: liveReload
 
 Whether to reload the page when source files are changed.
 
-By default, Modern.js uses HMR as the preferred method to update modules. If HMR is disabled or cannot be used in certain scenarios, it will automatically fallback to liveReload.
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
 
-Please refer to [Hot Module Replacement](https://rsbuild.dev/guide/advanced/hmr) for more information.
-
-## Disabling liveReload
-
-If you need to disable liveReload, you can set both `dev.hmr` and `dev.liveReload` to `false`. Then, no Web Socket requests will be made to the dev server on the page, and the page will not automatically refresh when file change.
-
-```js
-export default {
-  dev: {
-    hmr: false,
-    liveReload: false,
-  },
-};
-```
+<RsbuildConig />

package/docs/en/configure/app/dev/port.mdx

@@ -4,6 +4,22 @@ title: port
 
 # dev.port
 
-import Main from '@modern-js/builder-doc/docs/en/config/dev/port.md';
+- **Type:** `number`
+- **Default:** `8080`
+
+Specify a port number for Dev Server to listen.
+
+By default, Dev Server listens on port `8080` and automatically increments the port number when the port is occupied.
+
+### Example
+
+Set the port to `3000`:
+
+```ts
+export default {
+  dev: {
+    port: 3000,
+  },
+};
+```
 
-<Main />

package/docs/en/configure/app/dev/progress-bar.mdx

@@ -1,9 +1,24 @@
 ---
 title: progressBar
+configName: dev.progressBar
 ---
 
 # dev.progressBar
 
-import Main from '@modern-js/builder-doc/docs/en/config/dev/progressBar.md';
+- **Type:**
 
-<Main />
+```ts
+type ProgressBar =
+  | boolean
+  | {
+      id?: string;
+    };
+```
+
+- **Default:** true
+
+Whether to display progress bar during compilation.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />