@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

package/docs/en/configure/app/server/ssr-by-entries.mdx

@@ -0,0 +1,29 @@
+---
+title: ssrByEntries
+---
+
+# server.ssrByEntries
+
+- **Type:** `Object`
+- **Default:** `undefined`
+
+Set SSR options by entry, and the properties inside the option are the same as [ssr](./ssr.mdx). The specified value will be replaced and merged with the content of the SSR attribute, for example:
+
+:::info
+The "entry name" defaults to the directory name. In a few cases, when defining an entry through `source.entries`, the entry name is the `key` of the `source.entries` object.
+
+:::
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    ssr: true,
+    ssrByEntries: {
+      // page-a does not enable SSR
+      'page-a': false,
+    },
+  },
+});
+```
+
+In the above configuration, the project enables SSR as a whole, but the SSR rendering ability is disabled for the `page-a` entry.

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

@@ -0,0 +1,85 @@
+---
+title: ssr
+---
+
+# server.ssr
+
+- **Type:** `boolean` | `Object`
+- **Default:** `false`
+
+Enable SSR configuration.
+
+### Boolean Type
+
+When the value type is `boolean`, it indicates whether to enable SSR deployment mode. The default is `false` to disable it.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    ssr: true,
+  },
+});
+```
+
+### Object Type
+
+When the value type is `Object`, the following properties can be configured:
+
+| Name              | Type                                                         | Default                                   | Description                                                                     |
+| ---------------- | ------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------- |
+| mode             | `string`                                  | `stream`          | which defaults to using streaming rendering. Configure `string` to use `renderToString` for 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 |
+| 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      |
+| 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`](/guides/basic-features/routes/routes#error-handling) 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) |
+| moduleFederationAppSSR | `boolean`                            | `false`           | Enables app-level Module Federation SSR contract handshake. Enable this in both host and remote apps when using app-level MF SSR |
+
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    ssr: {
+      forceCSR: true,
+      mode: 'stream',
+      unsafeHeaders: ['User-Agent'],
+      moduleFederationAppSSR: true,
+    },
+  },
+});
+```
+
+### Active Fallback
+
+In a production environment, there are scenarios where it is necessary to actively fallback an SSR project to CSR. Examples include
+
+1. When the SSR fails, a fallback to the CSR is required to ensure product availability.
+
+2. When the SSR is working normally, but there are rendering failures during csr, debugging is required.
+
+3. When the SSR server is under heavy load, it may be necessary to fallback some traffic directly to the CSR to avoid service downtime.
+
+By configuring `server.ssr.forceCSR` to `true` in the project, you can control this behavior through query strings or request headers.
+
+For example, in a custom Web Server middleware, you can actively fallback when traffic exceeds a certain threshold:
+
+```ts title="server/modern.server.ts"
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
+
+export const handler: MiddlewareHandler = async (c, next) => {
+  if (condition) {
+    c.set('forceCSR', '1');
+  }
+  await next();
+};
+
+export default defineServerConfig({
+  middlewares: [
+    {
+      name: 'request-middleware',
+      handler,
+    },
+  ],
+});
+```

package/docs/en/configure/app/server/tsconfig-path.mdx

@@ -0,0 +1,63 @@
+---
+title: tsconfigPath
+---
+
+# server.tsconfigPath
+
+- **Type:** `string`
+- **Default:** `<appDirectory>/tsconfig.json`
+
+Specifies the tsconfig file used by server-side TypeScript processes.
+
+This option affects:
+
+- BFF / API compilation (`@modern-js/plugin-bff`)
+- Custom server compilation (`*.ts` files under `server/`)
+- Runtime Node-native TypeScript registration, such as SSR, `modern.config.ts`, and `.ts` files under `config/`
+
+When this option is not set, `<appDirectory>/tsconfig.json` is used by default.
+
+## When to use
+
+Use this option when frontend and server-side code need different TypeScript configurations.
+
+For example, the frontend can use `moduleResolution: "Bundler"`, while the server side uses `moduleResolution: "NodeNext"` for type resolution of conditional exports or subpath exports.
+
+## Example
+
+The example below uses `tsconfig.server.json` as the file name. You can use another name in your project.
+
+Add `<appDirectory>/tsconfig.server.json`:
+
+```jsonc title="tsconfig.server.json"
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "ES2022",
+    "lib": ["ESNext"],
+    "types": ["node"],
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  },
+  "include": ["api", "shared", "server", "config", "modern.config.ts"]
+}
+```
+
+Specify this file in `modern.config.ts`:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    tsconfigPath: './tsconfig.server.json',
+  },
+});
+```
+
+## Notes
+
+- `tsconfigPath` is resolved relative to `appDirectory`. Absolute paths are also supported.
+- It is recommended to inherit shared options such as `paths` from the root tsconfig through `extends`, instead of maintaining them in multiple files.
+- If the configured file does not exist, the runtime TypeScript setup will throw an error at startup.

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

@@ -0,0 +1,18 @@
+---
+title: aliasStrategy
+---
+
+# source.aliasStrategy
+
+:::warning Deprecation Warning
+`source.aliasStrategy` is deprecated, please use [resolve.aliasStrategy](/configure/app/resolve/alias-strategy) instead.
+:::
+
+- **Type:** `'prefer-tsconfig' | 'prefer-alias'`
+- **Default:** `'prefer-tsconfig'`
+
+`source.aliasStrategy` is used to control the priority between the `paths` option in `tsconfig.json` and the `alias` option in the bundler.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="source.aliasStrategy" />

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

@@ -0,0 +1,27 @@
+---
+title: alias
+---
+
+# source.alias
+
+:::warning Deprecation Warning
+`source.alias` is deprecated, please use [resolve.alias](/configure/app/resolve/alias) instead.
+:::
+
+- **Type:**
+
+```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://rspack.rs/config/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 RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="source.alias" />

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

@@ -0,0 +1,24 @@
+---
+title: configDir
+---
+
+# source.configDir
+
+- **Type:** `string`
+- **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).
+
+This option allows you to customize the directory of the configuration files.
+
+For example, adjust the assets directory to the `resources` directory:
+
+```js title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    configDir: './resources',
+  },
+});
+```

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

@@ -0,0 +1,29 @@
+---
+title: decorators
+---
+
+# source.decorators
+
+- **Type:**
+
+```ts
+type Decorators = {
+  version?: 'legacy' | '2022-03';
+};
+```
+
+- **Default:**
+
+```ts
+const defaultDecorators = {
+  version: 'legacy';
+};
+```
+
+Used to configure the decorators syntax.
+
+:::warning
+The usage of this configuration item is exactly the same as that of Rsbuild, but the default value is different. For detailed information, please refer to [Rsbuild - source.decorators](https://v2.rsbuild.rs/config/source/decorators).
+:::
+
+We found that most projects still use the `legacy` version of the decorator syntax, so the default value is `legacy`.

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

@@ -0,0 +1,20 @@
+---
+title: define
+---
+
+# source.define
+
+- **Type:** `Record<string, unknown>`
+- **Default:**
+
+```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 RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="source.define" />

package/docs/en/configure/app/source/disable-default-entries.mdx

@@ -0,0 +1,32 @@
+---
+title: disableDefaultEntries
+---
+
+# source.disableDefaultEntries
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Used to disable the functionality of automatically identifying page entry points based on directory structure.
+
+:::info
+By default, Modern.js automatically determines the entry points of pages based on directory conventions, as described in [Entries](/guides/concept/entries).
+
+:::
+
+To disable this default behavior, set the following:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    disableDefaultEntries: true,
+  },
+});
+```
+
+After disabling the default behavior, you will need to use the [`source.entries`](/configure/app/source/entries) configuration to define custom entry points.
+
+:::warning
+We recommend organizing your code using the directory conventions provided by Modern.js to make better use of the framework's functionality and to avoid some redundant configurations.
+
+:::

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

@@ -0,0 +1,54 @@
+---
+title: enableAsyncEntry
+---
+
+# source.enableAsyncEntry
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+This option is used for Rspack Module Federation scenario.
+
+When this option is enabled, Modern.js will wrap the automatically generated entry files with dynamic import (Asynchronous Boundaries), allowing page code to consume remote modules generated by Module Federation.
+
+## Background
+
+import ModuleFederation from '@site-docs-en/components/module-federation.mdx';
+
+<ModuleFederation />
+
+## Example
+
+First, enable this option in the configuration file:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    enableAsyncEntry: true,
+  },
+});
+```
+
+Then run the `dev` or `build` command, and you will see that the files automatically generated by Modern.js have the following structure:
+
+```bash
+node_modules
+  └─ .modern-js
+     └─ main
+        ├─ bootstrap.jsx  # asynchronous entry file
+        ├─ index.js      # real entry code
+        └─ index.html
+```
+
+The contents of `bootstrap.js` are as follows:
+
+```js
+import('./index.jsx');
+```
+
+At this point, you can consume any remote module in the current page.
+
+:::info
+Modern.js does not have ModuleFederationPlugin plugin built in. Please configure the ModuleFederationPlugin yourself via [tools.bundlerChain](/configure/app/tools/bundler-chain).
+
+:::

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

@@ -0,0 +1,30 @@
+---
+title: enableAsyncPreEntry
+---
+
+# source.enableAsyncPreEntry
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+When enabled, Modern.js will inject the modules configured in `source.preEntry` to the top of the auto-generated entry file (`index.jsx`) in order.
+
+This option only takes effect when `source.enableAsyncEntry` is enabled. If async entry is not enabled, this behavior will be skipped and the original builder-side `source.preEntry` injection remains unchanged.
+
+This option is mainly designed to work with `source.enableAsyncEntry`: when async entry is enabled, the final build entry becomes `bootstrap.jsx`, and the builder-side `source.preEntry` may not be injected into the real entry code. With `source.enableAsyncPreEntry` enabled, `preEntry` will be injected into `index.jsx` (the real entry code), so it also works in async entry scenarios.
+
+Meanwhile, when both `source.enableAsyncEntry` and `source.enableAsyncPreEntry` are enabled, Modern.js will not pass `source.preEntry` into builder config to avoid duplicate injection or injection into an unexpected entry.
+
+## Example
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    enableAsyncEntry: true,
+    enableAsyncPreEntry: true,
+    preEntry: ['./src/pre-a.ts', './src/pre-b.ts'],
+  },
+});
+```

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

@@ -0,0 +1,39 @@
+---
+title: entriesDir
+---
+
+# source.entriesDir
+
+- **Type:** `string`
+- **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.
+
+For example, with the following configuration and directory structure:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    entriesDir: './src/pages',
+  },
+});
+```
+
+```bash title="Project directory structure"
+.
+└── src
+    └── pages
+        ├── a
+        │   └── App.tsx
+        └── b
+            └── App.tsx
+```
+
+Modern.js will generate the build entries `a` and `b` based on the `./src/pages` directory structure. The result is as follows:
+
+```js
+const entry = {
+  a: './src/pages/a/App.tsx',
+  b: './src/pages/b/App.tsx',
+};
+```

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

@@ -0,0 +1,183 @@
+---
+title: entries
+---
+
+# source.entries
+
+- **Type:**
+
+```ts
+type Entries = Record<
+  string,
+  | string
+  | {
+      entry: string;
+      disableMount?: boolean;
+    }
+>;
+```
+
+- **Default:** The entry object calculated based on the directory structure of the current project.
+
+Used to configure custom page entries.
+
+:::tip When to use
+For most scenarios, the entry automatically generated by Modern.js based on the directory structure can meet the requirements. For details, please refer to [Entry](/guides/concept/entries).
+
+If you need to customize page entries, you can set them through this option.
+
+:::
+
+## String
+
+When the value of the `entries` object is of type `string`, it represents the file path of the entry module:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    entries: {
+      // Specify a new entry named 'my-entry'
+      'my-entry': './src/home/test/index.ts',
+    },
+    disableDefaultEntries: true,
+  },
+});
+```
+
+By default, the configured entry is equivalent to `App.tsx`, which means that the specified entry file **only needs to export the root component of the application**.
+
+For example, the following directory structure:
+
+```bash
+.
+├── src
+│   └── entry
+│       ├── chat.tsx
+│       └── home.tsx
+└── package.json
+```
+
+The above directory does not conform to the directory structure convention of Modern.js, so Modern.js will not get any default entries when analyzing the directory structure.
+
+If you do not want to change the directory structure (such as project migration), you can customize the entry through `source.entries`:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    entries: {
+      home: './src/entry/home.tsx',
+      chat: './src/entry/chat.tsx',
+    },
+    disableDefaultEntries: true,
+  },
+});
+```
+
+## Object
+
+When the value is `Object`, the following attributes can be configured:
+
+- `entry`: `string`, the entry file path.
+- `disableMount`: `boolean = false`, disable Modern.js's behavior of automatically generating entry code.
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    entries: {
+      'my-entry': {
+        // entry file path
+        entry: './src/my-page/index.tsx',
+        disableMount: true,
+      },
+    },
+    // Disable default entry scanning
+    disableDefaultEntries: true,
+  },
+});
+```
+
+### Disable entry file generation
+
+By default, the configured entry is equivalent to `App.tsx`, and Modern.js will automatically generate an entry file to reference the entry you configured.
+
+If you want to disable the logic of Modern.js automatically generating entry files, you can set the `disableMount` property to `true`.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    entries: {
+      'my-entry': {
+        entry: './src/my-page/index.tsx',
+        disableMount: true,
+      },
+    },
+    // Disable default entry scanning
+    disableDefaultEntries: true,
+  },
+});
+```
+
+### Conventional Routing
+
+If you need to enable conventional routing for a custom entry, you can set `entry` to a directory path:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    entries: {
+      // enable conventional routing
+      entry_spa: {
+        // The entry path of conventional routing must be set to a directory
+        entry: './src/about',
+      },
+    },
+    // Disable default entry scanning
+    disableDefaultEntries: true,
+  },
+});
+```
+
+## Entry Merge Rules
+
+After setting `source.entries`, if `disableDefaultEntries: true` is not set, Modern.js will merge the custom entry with the entry obtained by analyzing the directory structure.
+
+The merge rule is:
+
+- Compare the entry paths set by the custom entry setting and the default entry path. When the entry paths are the same, the custom entry will override the default entry.
+
+For example, the following directory structure:
+
+```bash
+.
+├── src
+│   ├── chat
+│   │   └── App.tsx
+│   └── home
+│       └── index.ts
+└── package.json
+```
+
+Modern.js will analyze the `src/` directory and get the default entries `chat` and `home`. When the user configures as follows in the `modern.config.ts` file:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    entries: {
+      index: './src/home/index.ts',
+    },
+  },
+};
+```
+
+It can be seen that the path of the custom entry `index` is the same as the path of the default entry `home`. During the merge process, `index` will override `home`, and the final entry is as follows:
+
+- `chat -> ./src/chat/App.tsx`
+- `index -> ./src/home/index.ts`

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

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