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

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

package/docs/en/configure/app/html/mount-id.mdx

@@ -1,9 +1,15 @@
 ---
 title: mountId
+configName: html.mountId
 ---
 
 # html.mountId
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/mountId.md';
+- **Type:** `string`
+- **Default:** `'root'`
 
-<Main />
+By default, the `root` element is included in the HTML template for component mounting, and the element id can be modified through `mountId`.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/html/script-loading.mdx

@@ -1,9 +1,15 @@
 ---
 title: scriptLoading
+configName: html.scriptLoading
 ---
 
 # html.scriptLoading
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/scriptLoading.md';
+- **Type:** `'defer' | 'blocking' | 'module'`
+- **Default:** `'defer'`
 
-<Main />
+Used to set how `<script>` tags are loaded.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

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

@@ -4,6 +4,41 @@ title: tagsByEntries
 
 # html.tagsByEntries
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/tagsByEntries.md';
+- **Type:** `Record<string, ArrayOrNot<HtmlInjectTag | HtmlInjectTagHandler>>`
+- **Default:** `undefined`
+
+Used for multiple entry applications, injecting different tags for each entry.
+
+The usage is the same as `tags`, and you can use the "entry name" as the key to set each page individually.
+
+`tagsByEntries` will override the value set in `tags`.
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use the function usage of `html.tags` instead.
+:::
+
+### Example
+
+```js
+export default {
+  html: {
+    tags: [{ tag: 'script', attrs: { src: 'a.js' } }],
+    tagsByEntries: {
+      foo: [{ tag: 'script', attrs: { src: 'b.js' } }],
+    },
+  },
+};
+```
+
+Compile the application and you can see a tag injected on the `foo` page:
+
+```html
+<script src="b.js"></script>
+```
+
+And for any other pages:
+
+```html
+<script src="a.js"></script>
+```
 
-<Main />

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

@@ -1,9 +1,20 @@
 ---
 title: tags
+configName: html.tags
 ---
 
 # html.tags
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/tags.md';
+- **Type:**
 
-<Main />
+```ts
+type TagsConfig = HtmlTag | HtmlTagHandler | Array<HtmlTag | HtmlTagHandler>;
+```
+
+- **Default:** `undefined`
+
+Modifies the tags that are injected into the HTML page.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

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

@@ -4,6 +4,30 @@ title: templateByEntries
 
 # html.templateByEntries
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/templateByEntries.md';
+- **Type:** `Object`
+- **Default:** `undefined`
+
+Set different template file for different pages.
+
+The usage is same as `template`, and you can use the "entry name" as the key to set each page individually.
+
+`templateByEntries` will overrides the value set in `template`.
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use the function usage of `html.template` instead.
+:::
+
+### Example
+
+```js
+export default {
+  html: {
+    template: './static/index.html',
+    templateByEntries: {
+      foo: './src/pages/foo/index.html',
+      bar: './src/pages/bar/index.html',
+    },
+  },
+};
+```
 
-<Main />

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

@@ -4,6 +4,32 @@ title: templateParametersByEntries
 
 # html.templateParametersByEntries
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/templateParametersByEntries.md';
+- **Type:** `Object`
+- **Default:** `undefined`
 
-<Main />
+Set different template parameters for different pages.
+
+The usage is same as `templateParameters`, and you can use the "entry name" as the key to set each page individually.
+
+`templateParametersByEntries` will overrides the value set in `templateParameters`.
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use the function usage of `html.templateParameters` instead.
+:::
+
+### Example
+
+```js
+export default {
+  html: {
+    templateParametersByEntries: {
+      foo: {
+        type: 'a',
+      },
+      bar: {
+        type: 'b',
+      },
+    },
+  },
+};
+```