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

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.

package/docs/en/configure/app/source/resolve-main-fields.mdx

@@ -4,6 +4,43 @@ title: resolveMainFields
 
 # source.resolveMainFields
 
-import Main from '@modern-js/builder-doc/docs/en/config/source/resolveMainFields.md';
+- **Type:**
 
-<Main />
+```ts
+type Fields = (string | string[])[];
+
+type ResolveMainFields = Fields | Record<BuilderTarget, Fields>;
+```
+
+- **Default:** `undefined`
+
+This config will determine which field of `package.json` you use to import the `npm` module. Same as the [resolve.mainFields](https://webpack.js.org/configuration/resolve/#resolvemainfields) config of webpack.
+
+### Example
+
+```js
+export default {
+  source: {
+    resolveMainFields: ['main', 'browser', 'exports'],
+  },
+};
+```
+
+#### Set according to Targets
+
+When you build multiple targets at the same time, you can set different mainFields for different targets. At this point, you need to set `resolveMainFields` to an object whose key is the corresponding build target.
+
+For example to set different mainFields for `web` and `node`:
+
+```js
+export default {
+  output: {
+    source: {
+      resolveMainFields: {
+        web: ['main', 'browser', 'exports'],
+        node: ['main', 'node', 'exports'],
+      },
+    },
+  },
+};
+```

package/docs/en/configure/app/source/transform-import.mdx

@@ -1,9 +1,63 @@
 ---
 title: transformImport
+configName: source.transformImport
 ---
 
 # source.transformImport
 
-import Main from '@modern-js/builder-doc/docs/en/config/source/transformImport.md';
+Transform the import path, which can be used to modularly import the subpath of third-party packages. The functionality is similar to [babel-plugin-import](https://www.npmjs.com/package/babel-plugin-import)。
 
-<Main />
+- **Type:**
+
+```ts
+type TransformImport =
+  | Array<{
+      libraryName: string;
+      libraryDirectory?: string;
+      style?: string | boolean;
+      styleLibraryDirectory?: string;
+      camelToDashComponentName?: boolean;
+      transformToDefaultImport?: boolean;
+      customName?: string;
+      customStyleName?: string;
+    }>
+  | Function;
+```
+
+- **Default:**
+
+When the [Ant Design component library](https://www.npmjs.com/package/antd) &lt;= 4.x version is installed in the project, Modern.js will automatically add the following default configurations:
+
+```js
+const defaultAntdConfig = {
+  libraryName: 'antd',
+  libraryDirectory: isServer ? 'lib' : 'es',
+  style: true,
+};
+```
+
+When the [Arco Design component library](https://www.npmjs.com/package/@arco-design/web-react) is installed in the project, Modern.js will automatically add the following default configurations:
+
+```js
+const defaultArcoConfig = [
+  {
+    libraryName: '@arco-design/web-react',
+    libraryDirectory: isServer ? 'lib' : 'es',
+    camelToDashComponentName: false,
+    style: true,
+  },
+  {
+    libraryName: '@arco-design/web-react/icon',
+    libraryDirectory: isServer ? 'react-icon-cjs' : 'react-icon',
+    camelToDashComponentName: false,
+  },
+];
+```
+
+:::tip
+When you add configurations for `antd` or `@arco-design/web-react`, the priority will be higher than the default configurations mentioned above.
+:::
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/tools/autoprefixer.mdx

@@ -4,6 +4,45 @@ title: autoprefixer
 
 # tools.autoprefixer
 
-import Main from '@modern-js/builder-doc/docs/en/config/tools/autoprefixer.md';
+- **Type:** `Object | Function`
+- **Default:**
 
-<Main />
+```js
+{
+  flexbox: 'no-2009',
+  // Depends on the browserslist config in the project
+  // and the `output.overrideBrowserslist` (higher priority) config
+  overrideBrowserslist: browserslist,
+}
+```
+
+You can modify the config of [autoprefixer](https://github.com/postcss/autoprefixer) by `tools.autoprefixer`.
+
+### Object Type
+
+When `tools.autoprefixer` is configured as `Object` type, it is merged with the default config through Object.assign. For example:
+
+```js
+export default {
+  tools: {
+    autoprefixer: {
+      flexbox: 'no-2009',
+    },
+  },
+};
+```
+
+### Function Type
+
+When `tools.autoprefixer` is a Function, the default config is passed as the first parameter and can be directly modified or returned as the final result. For example:
+
+```js
+export default {
+  tools: {
+    autoprefixer(config) {
+      // modify flexbox config
+      config.flexbox = 'no-2009';
+    },
+  },
+};
+```