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

package/docs/en/configure/app/plugins.mdx

@@ -9,13 +9,13 @@ sidebar_position: 9
 
 Used to configure custom Modern.js framework plugins.
 
-Refer to [How to Develop Plugins](/guides/topic-detail/framework-plugin/implement) for how to write custom plugins.
+Refer to [How to Develop Plugins](/plugin/plugin-system/implement) for how to write custom plugins.
 
 ## Note
 
 This option is used to configure framework plugins. If you need to configure other types of plugins, please choose the corresponding configuration method:
 
-- Use [builderPlugins](/configure/app/builder-plugins) to configure Modern.js Builder plugins.
+- Use [builderPlugins](/configure/app/builder-plugins) to configure Rsbuild plugins.
 - Use [tools.bundlerChain](/configure/app/tools/bundler-chain) to configure Rspack or webpack plugins.
 - Use [tools.babel](/configure/app/tools/babel) to configure Babel plugins.
 
@@ -33,7 +33,7 @@ Currently, Modern.js has opened up the ability to customize CLI plugins, and Ser
 
 By default, custom plugins are executed in the order of the `plugins` array, and the execution time of built-in Modern.js plugins is earlier than that of custom plugins.
 
-When the plugin sets options that control the order, such as `pre` and `post`, the execution order will be adjusted based on the declared fields. Refer to [Relationship between plugins](/guides/topic-detail/framework-plugin/relationship) for more information.
+When the plugin sets options that control the order, such as `pre` and `post`, the execution order will be adjusted based on the declared fields. Refer to [Relationship between plugins](/plugin/plugin-system/relationship) for more information.
 
 ## Example
 

package/docs/en/configure/app/security/check-syntax.mdx

@@ -4,6 +4,70 @@ title: checkSyntax
 
 # security.checkSyntax
 
-import Main from '@modern-js/builder-doc/docs/en/config/security/checkSyntax.md';
+- **Type:**
 
-<Main />
+```ts
+type CheckSyntax =
+  | boolean
+  | {
+      targets?: string[];
+      exclude?: RegExp | RegExp[];
+      ecmaVersion?: EcmaVersion;
+    };
+```
+
+- **Default:** `false`
+
+Used to analyze whether there is incompatible advanced syntax in the build artifacts under the current browser scope. If any incompatible syntax is found, detailed information will be printed to the terminal.
+
+### Enable Detection
+
+You can set `checkSyntax` to `true` to enable syntax checking.
+
+```ts
+export default {
+  security: {
+    checkSyntax: true,
+  },
+};
+```
+
+When you enable `checkSyntax`, Modern.js will perform the detection during production builds. If any incompatible advanced syntax is detected in the build artifacts, error logs will be printed to the terminal, and the current build process will be terminated.
+
+### Error Logs
+
+The format of the error logs is as follows, including the source file, artifact location, error reason, and source code:
+
+```bash
+error   [Syntax Checker] Find some syntax errors after production build:
+
+  Error 1
+  source:  /node_modules/foo/index.js:1:0
+  output:  /dist/static/js/main.3f7a4d7e.js:2:39400
+  reason:  Unexpected token (1:178)
+  code:
+     9 |
+    10 | var b = 2;
+    11 |
+  > 12 | console.log(() => {
+    13 |   return a + b;
+    14 | });
+    15 |
+```
+
+:::tip
+Currently, syntax checking is implemented based on AST parser. Each time it performs a check, it can only identify the first incompatible syntax found in the file. If there are multiple incompatible syntaxes in the file, you need to fix the detected syntax and re-run the check.
+If the corresponding source location is not shown in the log, try setting **output.disableMinimize** to true and rebuild again.
+:::
+
+### Solutions
+
+If a syntax error is detected, you can handle it in the following ways:
+
+- If you want to downgrade this syntax to ensure good code compatibility, you can compile the corresponding module through the `source.include` config.
+- If you don't want to downgrade the syntax, you can adjust the project's browserslist to match the syntax.
+- If you do not want to check the syntax of certain products, you can use the `checkSyntax.exclude` configuration to exclude the files to be checked.
+
+### Options
+
+`security.checkSyntax` is implemented based on `@rsbuild/plugin-check-syntax`. For specific options, please refer to [@rsbuild/plugin-check-syntax](https://github.com/rspack-contrib/rsbuild-plugin-check-syntax).

package/docs/en/configure/app/security/nonce.mdx

@@ -1,9 +1,20 @@
 ---
 title: nonce
+configName: security.nonce
 ---
 
 # security.nonce
 
-import Main from '@modern-js/builder-doc/docs/en/config/security/nonce.md';
+- **Type:**
 
-<Main />
+```ts
+type Nonce = string;
+```
+
+- **Default:** `undefined`
+
+Adding a `nonce` attribute to the scripts resources introduced for HTML. This allows the browser to determine whether the script can be executed when it parses inline scripts with matching nonce values.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/security/sri.mdx

@@ -1,9 +1,26 @@
 ---
 title: sri
+configName: security.sri
 ---
 
 # security.sri
 
-import Main from '@modern-js/builder-doc/docs/en/config/security/sri.md';
+- **Type**
 
-<Main />
+```ts
+type SriOptions = {
+  hashFuncNames?: [string, ...string[]];
+  enabled?: 'auto' | true | false;
+  hashLoading?: 'eager' | 'lazy'; // only support webpack
+};
+```
+
+- **Default:** `undefined`
+
+Adding an `integrity` attribute to `<script>` and `<link rel="stylesheet">` tags introduced by HTML allows the browser to verify the integrity of the introduced resource, thus preventing tampering with the downloaded resource.
+
+:::info
+For a specific introduction to SRI, you can refer to [Rsbuild security.sri](https://rsbuild.dev/zh/config/security/sri).
+
+This configuration type is not completely consistent with Rsbuild and will be automatically converted during the build process.
+:::

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

@@ -1,5 +1,6 @@
 ---
 title: port
+configName: server.port
 ---
 
 # server.port
@@ -36,3 +37,7 @@ export default defineConfig({
   },
 });
 ```
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/server/ssr.mdx

@@ -25,15 +25,16 @@ export default defineConfig({
 
 When the value type is `Object`, the following properties can be configured:
 
-- `mode`: `string = 'string'`, which defaults to using `renderToString` for rendering. Configure `stream` to enable streaming rendering.
-- `forceCSR`: `boolean = false`, which is off by default for forcing CSR rendering. Configure `true` to force CSR by adding `?csr=true` or adding `x-modern-ssr-fallback` header when accessing the page.
-- `inlineScript`: `boolean = true`, by default, SSR data is injected into HTML as inline scripts and assigned directly to global variables. Configure `false` to distribute JSON instead of assigning to global variables, this configuration doesn't work in Streaming SSR.
-- `disablePrerender`: `boolean = fasle`, To ensure compatibility with the old data request method (`useLoader`), by default, Modern.js performs pre-rendering of components.
-  However, if developers want to reduce one rendering when there is no use of the useLoader API in your project, you can set the configuration `disablePrerender=true`.
-- `unsafeHeaders`: `string[] = []`, For safety reasons, Modern.js does not add excessive content to SSR_DATA. Developers can use this configuration to specify the headers that need to be injected.
-- `scriptLoading`: `'defer' | 'blocking' | 'module' | 'async'`, The configuration is the same as [html.scriptLoading](/configure/app/html/script-loading), supporting SSR injected script set to `async` loading. The priority is `ssr.scriptLoading` > `html.scriptLoading`.
-- `loaderFailureMode`: `'clientRender' | 'errorBoundary'`, The default configuration is `'errorBoundary'`, when an error occurs in [data loader](/en/guides/basic-features/data/data-fetch.html#data-loader-recommended),
-it will default to rendering the [`Error`](/en/guides/basic-features/routes.html#errorboundary) component of the route. When configured as `'clientRender'`, if a loader throws an error, it switch to client-side rendering，you can use it with [Client Loader](/en/guides/basic-features/data/data-fetch.html#client-loader).
+| Name              | Type                                                         | Default                                   | Description                                                                     |
+| ---------------- | ------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------- |
+| mode             | `string`                                  | `string`          | which defaults to using `renderToString` for rendering. Configure `stream` to enable streaming rendering       |
+| forceCSR         | `boolean`                                 | `false`           | which is off by default for forcing CSR rendering. Configure `true` to force CSR by adding `?csr=true` or adding `x-modern-ssr-fallback` header when accessing the page |
+| inlineScript     | `boolean`                                 | `true`            | By default, SSR data is injected into HTML as inline scripts and assigned directly to global variables. Configure `false` to distribute JSON instead of assigning to global variables, this configuration doesn't work in Streaming SSR |
+| disablePrerender | `boolean`                                 | `fasle`           | To ensure compatibility with the old data request method (`useLoader`), by default, Modern.js performs pre-rendering of components.However, if developers want to reduce one rendering when there is no use of the useLoader API in your project, you can set the configuration `disablePrerender=true` |
+| unsafeHeaders    | `string[]`                                | `[]`              | For safety reasons, Modern.js does not add excessive content to SSR_DATA. Developers can use this configuration to specify the headers that need to be injected      |
+| scriptLoading    | `defer \| blocking \| module \| async`    | `defer`           | The configuration is the same as [html.scriptLoading](/configure/app/html/script-loading), supporting SSR injected script set to `async` loading. The priority is `ssr.scriptLoading` > `html.scriptLoading`  |
+| loaderFailureMode| `clientRender \| errorBoundary`           | `errorBoundary`   | The default configuration is `'errorBoundary'`, when an error occurs in [data loader](/en/guides/basic-features/data/data-fetch.html#data-loader-recommended), it will default to rendering the [`Error`](/en/guides/basic-features/routes.html#errorboundary) component of the route. When configured as `'clientRender'`, if a loader throws an error, it switch to client-side rendering，you can use it with [Client Loader](/en/guides/basic-features/data/data-fetch.html#client-loader) |
+
 
 ```ts title="modern.config.ts"
 export default defineConfig({

package/docs/en/configure/app/source/alias-strategy.mdx

@@ -1,9 +1,15 @@
 ---
 title: aliasStrategy
+configName: source.aliasStrategy
 ---
 
 # source.aliasStrategy
 
-import Main from '@modern-js/builder-doc/docs/en/config/source/aliasStrategy.md';
+- **Type:** `'prefer-tsconfig' | 'prefer-alias'`
+- **Default:** `'prefer-tsconfig'`
 
-<Main />
+`source.aliasStrategy` is used to control the priority between the `paths` option in `tsconfig.json` and the `alias` option in the bundler.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/source/alias.mdx

@@ -1,9 +1,24 @@
 ---
 title: alias
+configName: source.alias
 ---
 
 # source.alias
 
-import Main from '@modern-js/builder-doc/docs/en/config/source/alias.md';
+- **Type:**
 
-<Main />
+```ts
+type Alias = Record<string, string | false | (string | false)[]> | Function;
+```
+
+- **Default:** `undefined`
+
+Create aliases to import or require certain modules, same as the [resolve.alias](https://webpack.js.org/configuration/resolve/#resolvealias) config of Rspack.
+
+:::tip
+For TypeScript projects, you only need to configure [compilerOptions.paths](https://www.typescriptlang.org/tsconfig#paths) in the `tsconfig.json` file. The Rsbuild will automatically recognize it, so there is no need to configure the `source.alias` option separately. For more details, please refer to [Path Aliases](https://modernjs.dev/en/guides/basic-features/alias.html).
+:::
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/source/config-dir.mdx

@@ -5,7 +5,7 @@ title: configDir
 # source.configDir
 
 - **Type:** `string`
-- **Default:** `./config`
+- **Default:** `'./config'`
 
 Modern.js supports placing some files in the `./config` folder to customize HTML templates, icons, static assets, etc. For details, please refer to [File Convention](/apis/app/hooks/config/html).
 

package/docs/en/configure/app/source/decorators.mdx

@@ -1,11 +1,13 @@
 ---
 title: decorators
+configName: source.decorators
 ---
 
 # source.decorators
 
 - **Type:**
-```
+
+```ts
 type Decorators = {
   version?: 'legacy' | '2022-03';
 };
@@ -13,29 +15,14 @@ type Decorators = {
 
 - **Default:**
 
-```
-type Decorators = {
-  version: 'legacy',
+```ts
+const defaultDecorators = {
+  version: 'legacy';
 };
 ```
 
 Used to configure the decorators syntax.
 
-### Example
-
-Modern.js uses `legacy` syntax by default (Stage 1 proposal), equivalent to TypeScript's `experimentalDecorators: true`.
-
-You can adjust the decorator syntax to the Stage 3 decorator proposal by setting `decorators.version` to `2022-03`.
-
-```js
-export default {
-  source: {
-    decorators: {
-      version: '2022-03',
-    },
-  },
-};
-```
-
-For detailed usage, please refer to [Rsbuild - source.decorators](https://rsbuild.dev/config/source/decorators).
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
 
+<RsbuildConig />

package/docs/en/configure/app/source/define.mdx

@@ -1,9 +1,21 @@
 ---
 title: define
+configName: source.define
 ---
 
 # source.define
 
-import Main from '@modern-js/builder-doc/docs/en/config/source/define.md';
+- **Type:** `Record<string, unknown>`
+- **Default:**
 
-<Main />
+```ts
+const defaultDefine = {
+  'process.env.MODERN_TARGET': '"browser"',
+};
+```
+
+Replaces variables in your code with other values or expressions at compile time. This can be useful for allowing different behavior between development builds and production builds.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/source/enable-async-entry.mdx

@@ -13,7 +13,7 @@ When this option is enabled, Modern.js will wrap the automatically generated ent
 
 ## Background
 
-import ModuleFederation from '@modern-js/builder-doc/docs/en/shared/module-federation.md';
+import ModuleFederation from '@site-docs-en/components/module-federation.mdx';
 
 <ModuleFederation />
 

package/docs/en/configure/app/source/entries-dir.mdx

@@ -5,7 +5,7 @@ title: entriesDir
 # source.entriesDir
 
 - **Type:** `string`
-- **Default:** `./src`
+- **Default:** `'./src'`
 
 By default, Modern.js scans the `src` directory to identify page entries. You can customize the directory used for identifying page entries with this option.
 

package/docs/en/configure/app/source/exclude.mdx

@@ -1,9 +1,15 @@
 ---
 title: exclude
+configName: source.exclude
 ---
 
 # source.exclude
 
-import Main from '@modern-js/builder-doc/docs/en/config/source/exclude.md';
+- **Type:** [RuleSetCondition[]](https://rspack.dev/config/module#condition)
+- **Default:** `[]`
 
-<Main />
+Specifies JavaScript/TypeScript files that do not need to be compiled. The usage is consistent with [Rule.exclude](https://rspack.dev/config/module#ruleexclude) in Rspack, which supports passing in strings or regular expressions to match the module path.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/source/global-vars.mdx

@@ -4,6 +4,107 @@ title: globalVars
 
 # source.globalVars
 
-import Main from '@modern-js/builder-doc/docs/en/config/source/globalVars.md';
+- **Type:** `Record<string, JSONValue> | Function`
+- **Default:**
 
-<Main />
+```ts
+const defaultGlobalVars = {
+  // The environment variable `process.env.NODE_ENV` will be added by default,
+  // so you don't need to set it in manually.
+  'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
+};
+```
+
+Used to define global variables. It can replace expressions like `process.env.FOO` in your code after compile. Such as:
+
+```js
+console.log(process.env.NODE_ENV);
+
+// ⬇️ Turn into being...
+console.log('development');
+```
+
+### Example
+
+In the following example, the `ENABLE_VCONSOLE` and `APP_CONTEXT` are injected into the code:
+
+```js
+export default {
+  source: {
+    globalVars: {
+      ENABLE_VCONSOLE: true,
+      APP_CONTEXT: { answer: 42 },
+    },
+  },
+};
+```
+
+You can use them directly in your code:
+
+```js
+if (ENABLE_VCONSOLE) {
+  // do something
+}
+
+console.log(APP_CONTEXT);
+```
+
+### Function Usage
+
+- **Type:**
+
+```ts
+type GlobalVarsFn = (
+  obj: Record<string, JSONValue>,
+  utils: { env: NodeEnv; target: BuilderTarget },
+) => Record<string, JSONValue> | void;
+```
+
+You can set `source.globalVars` to a function to dynamically setting some environment variables.
+
+For example, dynamically set according to the build target:
+
+```js
+export default {
+  source: {
+    globalVars(obj, { target }) {
+      obj['MY_TARGET'] = target === 'node' ? 'server' : 'client';
+    },
+  },
+};
+```
+
+### Difference with define
+
+You can take `source.globalVars` as the syntax sugar of `source.define`, the only difference is that `source.globalVars` will automatically stringify the value, which makes it easier to set the value of global variables. The values of `globalVars` should be JSON-safe to ensure it can be serialized.
+
+```js
+export default {
+  source: {
+    globalVars: {
+      'process.env.BUILD_VERSION': '0.0.1',
+      'import.meta.foo': { bar: 42 },
+      'import.meta.baz': false,
+    },
+    define: {
+      'process.env.BUILD_VERSION': JSON.stringify('0.0.1'),
+      'import.meta': {
+        foo: JSON.stringify({ bar: 42 }),
+        baz: JSON.stringify(false),
+      },
+    },
+  },
+};
+```
+
+### Precautions
+
+`source.globalVars` injects environment variables through string replacement, so it cannot take effect on dynamic syntaxes such as destructuring.
+
+When using destructuring assignment, Modern.js will not be able to determine whether the variable `NODE_ENV` is associated with the expression `process.env.NODE_ENV` to be replaced, so the following usage is invalid:
+
+```js
+const { NODE_ENV } = process.env;
+console.log(NODE_ENV);
+// ❌ Won't get a string.
+```

package/docs/en/configure/app/source/include.mdx

@@ -1,9 +1,26 @@
 ---
 title: include
+configName: source.include
 ---
 
 # source.include
 
-import Main from '@modern-js/builder-doc/docs/en/config/source/include.md';
+- **Type:** [RuleSetCondition[]](https://rspack.dev/config/module#condition)
+- **Default:**
 
-<Main />
+```ts
+const defaultInclude = [
+  [
+    /node_modules\/react-router/,
+    /node_modules\/react-router-dom/,
+    /node_modules\/@remix-run\/router/,
+    '/node_modules/.modern-js',
+  ],
+];
+```
+
+The `source.include` is used to specify additional JavaScript files that need to be compiled.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/source/mainEntryName.mdx

@@ -5,7 +5,7 @@ title: mainEntryName
 # source.mainEntryName
 
 - **Type:** `string`
-- **Default:** `main`
+- **Default:** `'main'`
 
 This option is used to configure the main entry name of Modern.js.
 

package/docs/en/configure/app/source/module-scopes.mdx

@@ -4,6 +4,66 @@ title: moduleScopes
 
 # source.moduleScopes
 
-import Main from '@modern-js/builder-doc/docs/en/config/source/moduleScopes.md';
+- **Type:** `Array<string | Regexp> | Function`
+- **Default:** `undefined`
+- **Bundler:** `only support webpack`
 
-<Main />
+Restrict importing paths. After configuring this option, all source files can only import code from the specific paths, and import code from other paths is not allowed.
+
+### Example
+
+First, we configure `moduleScopes` to only include the `src` directory:
+
+```js
+export default {
+  source: {
+    moduleScopes: ['./src'],
+  },
+};
+```
+
+Then we import the `utils/a` module outside the `src` directory in `src/App.tsx`:
+
+```js
+import a from '../utils/a';
+```
+
+After compiling, there will be a reference path error:
+
+![scopes-error](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/module-scopes-error.png)
+
+If we configure the `utils` directory in `moduleScopes`, the error will disappear.
+
+```js
+export default {
+  source: {
+    moduleScopes: ['./src', './utils'],
+  },
+};
+```
+
+### Array Type
+
+You can directly set several paths like this:
+
+```js
+export default {
+  source: {
+    moduleScopes: ['./src', './shared', './utils'],
+  },
+};
+```
+
+### Function Type
+
+`moduleScopes` also supports setting as a function, which can be modified instead of overriding the default value:
+
+```js
+export default {
+  source: {
+    moduleScopes: scopes => {
+      scopes.push('./shared');
+    },
+  },
+};
+```

package/docs/en/configure/app/source/pre-entry.mdx

@@ -1,9 +1,15 @@
 ---
 title: preEntry
+configName: source.preEntry
 ---
 
 # source.preEntry
 
-import Main from '@modern-js/builder-doc/docs/en/config/source/preEntry.md';
+- **Type:** `string | string[]`
+- **Default:** `[]`
 
-<Main />
+Add a script before the entry file of each page. This script will be executed before the page code. It can be used to execute global logics, such as injecting polyfills, setting global styles, etc.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/source/resolve-extension-prefix.mdx

@@ -4,6 +4,52 @@ title: resolveExtensionPrefix
 
 # source.resolveExtensionPrefix
 
-import Main from '@modern-js/builder-doc/docs/en/config/source/resolveExtensionPrefix.md';
+- **Type:** `string | Record<BuilderTarget, string>`
+- **Default:** `undefined`
 
-<Main />
+Add a prefix to [resolve.extensions](https://webpack.js.org/configuration/resolve/#resolveextensions).
+
+If multiple files share the same name but have different extensions, Modern.js will resolve the one with the extension listed first in the array and skip the rest.
+
+### Example
+
+```js
+export default {
+  source: {
+    resolveExtensionPrefix: '.web',
+  },
+};
+```
+
+With the configuration above, the extensions array will become:
+
+```js
+// before
+const extensions = ['.js', '.ts', ...];
+
+// after
+const extensions = ['.web.js', '.js', '.web.ts' , '.ts', ...];
+```
+
+When `import './foo'` in the code, the `foo.web.js` file will be resolved first, then the `foo.js` file.
+
+#### Set according to Targets
+
+When you build multiple targets at the same time, you can set different extension prefix for different targets. At this point, you need to set `resolveExtensionPrefix` to an object whose key is the corresponding build target.
+
+For example to set different extension prefix for `web` and `node`:
+
+```js
+export default {
+  output: {
+    source: {
+      resolveExtensionPrefix: {
+        web: '.web',
+        node: '.node',
+      },
+    },
+  },
+};
+```
+
+When `import './foo'` in the code, the `foo.node.js` file will be resolved for node target, and the `foo.web.js` file will be resolved for web target.