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

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

package/docs/en/configure/app/dev/write-to-disk.mdx

@@ -1,5 +1,6 @@
 ---
 title: writeToDisk
+configName: dev.writeToDisk
 ---
 
 # dev.writeToDisk
@@ -7,32 +8,8 @@ title: writeToDisk
 - **Type:** `boolean | ((filename: string) => boolean)`
 - **Default:** `(file) => !file.includes('.hot-update.')`
 
-Used to control whether the build artifacts of the development environment are written to the disk.
+Controls whether the build output from development mode is written to disk.
 
-## Writing to Memory
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
 
-You can choose to save the build artifacts in the memory of the dev server, thereby reducing the overhead caused by file operations.
-
-Simply set the `dev.writeToDisk` option to `false`:
-
-```ts
-export default {
-  dev: {
-    writeToDisk: false,
-  },
-};
-```
-
-## Matching Specific Files
-
-You can also set `dev.writeToDisk` to a function to match only certain files. When the function returns `false`, the file will not be written; when it returns `true`, the file will be written to disk.
-
-For example, Modern.js by default write files to disk while excluding hot-update temporary files:
-
-```ts
-export default {
-  dev: {
-    writeToDisk: (file) => !file.includes('.hot-update.'),
-  },
-};
-```
+<RsbuildConig />

package/docs/en/configure/app/experiments/lazy-compilation.mdx

@@ -4,6 +4,88 @@ title: lazyCompilation
 
 # experiments.lazyCompilation
 
-import Main from '@modern-js/builder-doc/docs/en/config/experiments/lazyCompilation.md';
+- **Type:**
 
-<Main />
+```ts
+type LazyCompilationOptions =
+  | boolean
+  | {
+      // Whether to enable lazy compilation for entries
+      entries?: boolean;
+      // Whether to enable lazy compilation for dynamic imports
+      imports?: boolean;
+      // Specify which imported modules should be lazily compiled.
+      test?: RegExp | ((m: Module) => boolean);
+    };
+```
+
+- **Default:** `false`
+
+Used to enable the lazy compilation (i.e. compile on demand). When this config is enabled, Modern.js will compile entrypoints and dynamic imports only when they are used. It will improve the compilation startup time of the project.
+
+Lazy compilation only takes effect in the development.
+
+### Lazy Compilation for Dynamic Imports
+
+Lazy compile async modules introduced by [dynamic import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import):
+
+```ts
+export default {
+  experiments: {
+    lazyCompilation: {
+      imports: true,
+      entries: false,
+    },
+  },
+};
+```
+
+When `imports` option is enabled, all async modules will only be compiled when requested. If your project is a single-page application, and routing is split through dynamic import, there will be a significant effect of speeding up compilation.
+
+### Lazy Compilation for Entires
+
+In addition to lazy compilation for async modules, you can also choose to lazily compile both entries and async modules at the same time.
+
+```ts
+export default {
+  experiments: {
+    lazyCompilation: {
+      imports: true,
+      entries: true,
+    },
+  },
+};
+```
+
+The above config can also be simplified to:
+
+```ts
+export default {
+  experiments: {
+    lazyCompilation: true,
+  },
+};
+```
+
+When `entries` option is enabled, all pages will not be compiled when the compilation is started, and the page will be compiled only when you visit it.
+
+When using lazy compilation for entries, there are some considerations:
+
+- Only work for multi-page applications, no work for single-page applications.
+- when you visit a page, there will be a white screen for a period of time due to waiting for the page to be compiled.
+
+### Limitations
+
+#### Disable split chunks
+
+When you enable lazy compilation, in order to ensure the compilation results, Modern.js will disable split chunks in the development. This will not affect the build results in the production, but will cause a difference between the build results of the development and production.
+
+#### Use proxy
+
+Lazy Compilation relies on the local development server of webpack. When you proxy a domain name to localhost, Lazy Compilation will not work properly. Therefore, if you need to develop with proxy, please disable Lazy Compilation.
+
+#### Other Potential Issues
+
+Considering that Lazy Compilation is still an experimental feature of webpack, you may encounter some potential issues while using it, such as changes in the behavior of compiled artifacts or compilation errors.
+
+When you encounter these issues, you can refer to [webpack Issues](https://github.com/webpack/webpack/issues) to find solutions or disable the `lazyCompilation` configuration option.

package/docs/en/configure/app/experiments/source-build.mdx

@@ -2,8 +2,33 @@
 title: sourceBuild
 ---
 
-# experiments.sourceBuild
+- **Type:** `boolean | PluginSourceBuildOptions`
+- **Default:** `false`
+- **Version:** `MAJOR_VERSION.46.0`
 
-import Main from '@modern-js/builder-doc/docs/en/config/experiments/sourceBuild.md';
+Used to enable the ability for source code building. When this configuration option is enabled, Modern.js will read the source code files corresponding to the `source` field in the sub-project's package.json and compile them.
 
-<Main />
+```ts
+export default {
+  experiments: {
+    sourceBuild: true,
+  },
+};
+```
+
+More detail can see ["Source Code Build Mode"](https://modernjs.dev/en/guides/advanced-features/source-build.html)。
+
+### Options
+
+`experiments.sourceBuild` is implemented based on [@rsbuild/plugin-source-build](https://github.com/rspack-contrib/rsbuild-plugin-source-build?tab=readme-ov-file#options). You can pass plugin options like this:
+
+```ts
+export default {
+  experiments: {
+    sourceBuild: {
+      sourceField: 'my-source',
+      resolvePriority: 'output',
+    },
+  },
+};
+```

package/docs/en/configure/app/html/app-icon.mdx

@@ -1,9 +1,55 @@
 ---
 title: appIcon
+configName: html.appIcon
 ---
 
 # html.appIcon
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/appIcon.md';
+- **Type:**
 
-<Main />
+```ts
+type AppIconItem = {
+  src: string;
+  size: number;
+  target?: 'apple-touch-icon' | 'web-app-manifest';
+};
+
+type AppIcon = string | {
+  name?: string;
+  icons: AppIconItem[];
+  filename?: string;
+};
+```
+
+- **Default:** `undefined`
+
+Set the web application icons to display when added to the home screen of a mobile device:
+
+- Generate the web app manifest file and its `icons` field.
+- Generate the `apple-touch-icon` and `manifest` tags in the HTML file.
+
+### AppIcon string
+
+The `appIcon` configuration of type `string` is a syntactic sugar for the `object` type.
+
+```js
+export default {
+  html: {
+    appIcon: './src/assets/icon.png',
+  },
+};
+```
+
+The above configuration is equivalent to the following configuration:
+
+```js
+export default {
+  html: {
+    appIcon: { icons: [{ src: './src/assets/icon.png', size: 180 }] }
+  },
+};
+```
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/html/crossorigin.mdx

@@ -1,9 +1,15 @@
 ---
 title: crossorigin
+configName: html.crossorigin
 ---
 
 # html.crossorigin
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/crossorigin.md';
+- **Type:** `boolean | 'anonymous' | 'use-credentials'`
+- **Default:** `false`
 
-<Main />
+Set the [crossorigin](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) attribute of the `<script>` and `<style>` tags.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/html/disable-html-folder.mdx

@@ -4,6 +4,39 @@ title: disableHtmlFolder
 
 # html.disableHtmlFolder
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/disableHtmlFolder.md';
+- **Type:** `boolean`
+- **Default:** `false`
+
+Remove the folder of the HTML files. When this option is enabled, the generated HTML file path will change from `[name]/index.html` to `[name].html`.
+
+### Example
+
+By default, the structure of HTML files in the `dist` directory is:
+
+```bash
+/dist
+└── html
+    └── main
+        └── index.html
+```
+
+Enable the `html.disableHtmlFolder` config:
+
+```js
+export default {
+  html: {
+    disableHtmlFolder: true,
+  },
+};
+```
+
+After recompiling, the directory structure of the HTML files in dist is:
+
+```bash
+/dist
+└── html
+    └── main.html
+```
+
+> If you want to set the path of the HTML files, use the `output.distPath.html` config.
 
-<Main />

package/docs/en/configure/app/html/favicon-by-entries.mdx

@@ -4,6 +4,33 @@ title: faviconByEntries
 
 # html.faviconByEntries
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/faviconByEntries.md';
+- **Type:** `Record<string, string>`
+- **Default:** `undefined`
 
-<Main />
+Set different favicon for different pages.
+
+The usage is same as `favicon`, and you can use the "entry name" as the key to set each page individually.
+
+`faviconByEntries` will overrides the value set in `favicon`.
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use the function usage of `html.favicon` instead.
+:::
+
+### Example
+
+```js
+export default {
+  html: {
+    favicon: './src/assets/default.png',
+    faviconByEntries: {
+      foo: './src/assets/foo.png',
+    },
+  },
+};
+```
+
+After recompiling, you will see:
+
+- The favicon for page `foo` is `./src/assets/foo.png`.
+- The favicon for other pages is `./src/assets/default.png`.

package/docs/en/configure/app/html/favicon.mdx

@@ -1,9 +1,21 @@
 ---
 title: favicon
+configName: html.favicon
 ---
 
 # html.favicon
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/favicon.md';
+- **Type:** `string ｜ Function`
+- **Default:** `undefined`
 
-<Main />
+Set the favicon icon path for all pages, can be set as:
+
+- a URL.
+- an absolute path to the file.
+- a relative path relative to the project root directory.
+
+After config this option, the favicon will be automatically copied to the dist directory during the compilation, and the corresponding `link` tag will be added to the HTML.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/html/inject-by-entries.mdx

@@ -4,6 +4,33 @@ title: injectByEntries
 
 # html.injectByEntries
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/injectByEntries.md';
+- **Type:** `Record<string, boolean | string>`
+- **Default:** `undefined`
 
-<Main />
+Set different script tag inject positions for different pages.
+
+The usage is same as `inject`, and you can use the "entry name" as the key to set each page individually.
+
+`injectByEntries` will overrides the value set in `inject`.
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use the function usage of `html.inject` instead.
+:::
+
+### Example
+
+```js
+export default {
+  html: {
+    inject: 'head',
+    injectByEntries: {
+      foo: 'body',
+    },
+  },
+};
+```
+
+After recompiling, you will see:
+
+- The script tag of the page `foo` will be injected inside the `body` tag.
+- The script tag of other pages will be injected inside the `head` tag.

package/docs/en/configure/app/html/inject.mdx

@@ -1,9 +1,15 @@
 ---
 title: inject
+configName: html.inject
 ---
 
 # html.inject
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/inject.md';
+- **Type:** `'head' | 'body' | boolean | Function`
+- **Default:** `'head'`
 
-<Main />
+Set the inject position of the `<script>` tag.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/html/meta-by-entries.mdx

@@ -4,6 +4,45 @@ title: metaByEntries
 
 # html.metaByEntries
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/metaByEntries.md';
+- **Type:** `Record<string, Meta>`
+- **Default:** `undefined`
+
+Set different meta tags for different pages.
+
+The usage is same as `meta`, and you can use the "entry name" as the key to set each page individually.
+
+`metaByEntries` will overrides the value set in `meta`.
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use the function usage of `html.meta` instead.
+:::
+
+### Example
+
+```js
+export default {
+  html: {
+    meta: {
+      description: 'ByteDance',
+    },
+    metaByEntries: {
+      foo: {
+        description: 'TikTok',
+      },
+    },
+  },
+};
+```
+
+After compiling, you can see that the meta of the page `foo` is:
+
+```html
+<meta name="description" content="TikTok" />
+```
+
+The meta of other pages is:
+
+```html
+<meta name="description" content="ByteDance" />
+```
 
-<Main />

package/docs/en/configure/app/html/meta.mdx

@@ -1,9 +1,29 @@
 ---
 title: meta
+configName: html.meta
 ---
 
 # html.meta
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/meta.md';
+- **Type:** `Object | Function`
+- **Default:**
 
-<Main />
+```js
+const defaultMeta = {
+  charset: { charset: 'utf-8' },
+  viewport:
+    'width=device-width, initial-scale=1.0, shrink-to-fit=no, viewport-fit=cover, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no',
+  'http-equiv': { 'http-equiv': 'x-ua-compatible', content: 'ie=edge' },
+  renderer: 'webkit',
+  layoutmode: 'standard',
+  imagemode: 'force',
+  'wap-font-scale': 'no',
+  'format-detection': 'telephone=no',
+};
+```
+
+Configure the `<meta>` tag of the HTML.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />