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

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/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/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/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 />

package/docs/en/configure/app/dev/setup-middlewares.mdx

@@ -1,5 +1,6 @@
 ---
 title: setupMiddlewares
+configName: dev.setupMiddlewares
 ---
 
 # dev.setupMiddlewares
@@ -7,11 +8,31 @@ title: setupMiddlewares
 - **Type:**
 
 ```ts
-type ServerAPIs = {
+type SetupMiddlewaresServer = {
   sockWrite: (
     type: string,
     data?: string | boolean | Record<string, any>,
   ) => void;
+  environments: {
+    [name: string]: {
+      /**
+       * Get stats info about current environment.
+       */
+      getStats: () => Promise<Stats>;
+      /**
+       * Load and execute stats bundle in server.
+       *
+       * @param entryName - relate to Rsbuild's `source.entry`
+       * @returns the return value of entry module.
+       */
+      loadBundle: <T = unknown>(entryName: string) => Promise<T>;
+
+      /**
+       * Get the compiled HTML template.
+       */
+      getTransformedHtml: (entryName: string) => Promise<string>;
+    };
+  };
 };
 
 type SetupMiddlewares = Array<
@@ -20,7 +41,7 @@ type SetupMiddlewares = Array<
       unshift: (...handlers: RequestHandler[]) => void;
       push: (...handlers: RequestHandler[]) => void;
     },
-    server: ServerAPIs,
+    server: SetupMiddlewaresServer,
   ) => void
 >;
 ```
@@ -29,41 +50,6 @@ type SetupMiddlewares = Array<
 
 Provides the ability to execute a custom function and apply custom middlewares.
 
-The order among several different types of middleware is: `unshift` => internal middlewares => `push`.
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
 
-```js
-export default {
-  dev: {
-    setupMiddlewares: [
-      (middlewares, server) => {
-        middlewares.unshift((req, res, next) => {
-          next();
-        });
-
-        middlewares.push((req, res, next) => {
-          next();
-        });
-      },
-    ],
-  },
-};
-```
-
-It is possible to use some server api to meet special scenario requirements:
-
-- sockWrite. Allow send some message to HMR client, and then the HMR client will take different actions depending on the message type. If you send a "content changed" message, the page will reload.
-
-```js
-export default {
-  dev: {
-    setupMiddlewares: [
-      (middlewares, server) => {
-        // add custom watch & trigger page reload when change
-        watcher.on('change', (changed) => {
-          server.sockWrite('content-changed');
-        });
-      },
-    ],
-  },
-};
-```
+<RsbuildConig />

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

@@ -4,6 +4,50 @@ title: startUrl
 
 # dev.startUrl
 
-import Main from '@modern-js/builder-doc/docs/en/config/dev/startUrl.md';
+- **Type:** `boolean | string | string[] | undefined`
+- **Default:** `undefined`
+
+`dev.startUrl` is used to set the URL of the page that automatically opens in the browser when Dev Server starts.
+
+By default, no page will be opened.
+
+You can set it to the following values:
+
+```js
+export default {
+  dev: {
+    // Open the project's default preview page, equivalent to `http://localhost:<port>`
+    startUrl: true,
+    // Open the specified page
+    startUrl: 'http://localhost:8080',
+    // Open multiple pages
+    startUrl: ['http://localhost:8080', 'http://localhost:8080/about'],
+  },
+};
+```
+
+### Port placeholder
+
+Since the port number may change, you can use the `<port>` placeholder to refer to the current port number, and Modern.js will automatically replace the placeholder with the actual listening port number.
+
+```js
+export default {
+  dev: {
+    startUrl: 'http://localhost:<port>/home',
+  },
+};
+```
+
+### Open the specified browser
+
+On MacOS, you can open the specified browser when Dev Server starts, by set environment variable `BROWSER`, support values:
+
+- Google Chrome Canary
+- Google Chrome Dev
+- Google Chrome Beta
+- Google Chrome
+- Microsoft Edge
+- Brave Browser
+- Vivaldi
+- Chromium
 
-<Main />

package/docs/en/configure/app/dev/watch-files.mdx

@@ -1,5 +1,6 @@
 ---
 title: watchFiles
+configName: dev.watchFiles
 ---
 
 # dev.watchFiles
@@ -9,6 +10,7 @@ title: watchFiles
 ```ts
 type WatchFiles = {
   paths: string | string[];
+  type?: 'reload-page' | 'reload-server';
   // watch options for chokidar
   options?: WatchOptions;
 };
@@ -16,44 +18,8 @@ type WatchFiles = {
 
 - **Default:** `undefined`
 
-Watch files and directories for changes. When a file changes, the page will be reloaded.
+Watch specified files and directories for changes. When a file change is detected, it can trigger a page reload or restart the dev server.
 
-If both `dev.hmr` and `dev.liveReload` are set to false, `watchFiles` will be ignored.
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
 
-:::tip
-When files in WatchFiles change, reloading and recompilation of the configuration file will not be triggered.
-:::
-
-### Example
-
-You can configure a list of globs/directories/files to watch for file changes.
-
-```js
-export default {
-  dev: {
-    watchFiles: {
-      // watch a single file
-      paths: 'public/demo.txt',
-      // use a glob pattern
-      paths: 'src/**/*.txt',
-      // watch multiple file paths
-      paths: ['src/**/*.txt', 'public/**/*'],
-    },
-  },
-};
-```
-
-You can also specify [chokidar](https://github.com/paulmillr/chokidar#api) watcher options by passing an object with `paths` and `options` properties.
-
-```js
-export default {
-  dev: {
-    watchFiles: {
-      paths: 'src/**/*.txt',
-      options: {
-        usePolling: false,
-      },
-    },
-  },
-};
-```
+<RsbuildConig />