@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.98 → 3.8.1-ultramodern.1

package/docs/configure/app/server/routes.md

@@ -0,0 +1,86 @@
+# server.routes
+
+- **Type:** `Object`
+- **Default:** Server-side routing rules generated based on file conventions, with one route rule generated for each entry, and the entry name is equal to the route path.
+
+This configuration option only applies to server-side routing and can customize the access route of application entries.
+
+## Custom access routes
+
+The `key` of the object is the name of the current application entry, and the value can be a `string | Array<string>`.
+
+When the value type is `string`, the current value represents the route path for accessing the entry.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    routes: {
+      // Default route is /entryName1, customized to /p/test1
+      entryName1: '/p/test1'
+      // Supports dynamic server-side routing configuration
+      entryName2: '/detail/:id'
+    }
+  }
+});
+```
+
+Multiple access routes can also be set for the entry through `Array<string>`:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    routes: {
+      'page-a': [`/a`, '/b'],
+    },
+  },
+});
+```
+
+At this time, the `page-a` entry can be accessed through both the `/a` and `/b` routes.
+
+After executing the `dev` command, you can view two route records for the `page-a` entry in `dist/route.json`:
+
+```json
+{
+  "routes": [
+    {
+      "urlPath": "/a",
+      "entryName": "page-a",
+      "entryPath": "html/page-a/index.html",
+      "isSPA": true,
+      "isSSR": false
+    },
+    {
+      "urlPath": "/b",
+      "entryName": "page-a",
+      "entryPath": "html/page-a/index.html",
+      "isSPA": true,
+      "isSSR": false
+    }
+  ]
+}
+```
+
+## Custom response headers
+
+Response headers can be set by configuring the `resHeaders` of the entry:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    routes: {
+      'page-a': {
+        route: ['/a', '/b'],
+        resHeaders: {
+          'x-modern-test': '1',
+        },
+      },
+    },
+  },
+});
+```
+
+:::note
+This configuration takes effect in both the production and development environments, and different response headers can be set according to the NODE\_ENV to distinguish between environments. However, if you only need to set response headers in the development environment, it is recommended to use `tools.devServer.headers`.
+
+:::

package/docs/configure/app/server/rsc.md

@@ -0,0 +1,22 @@
+# server.rsc
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Configure React Server Components (RSC).
+
+:::warning UltraModern availability
+RSC is not shipped or supported in the current UltraModern company distribution. Keep this option `false`. The Rspack Flight runtime remains under upstream review, and enabling RSC intentionally fails unless an application supplies the complete optional toolchain.
+
+Do not install `react-server-dom-rspack` or add an application-level pnpm patch to bypass this boundary.
+:::
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    rsc: false,
+  },
+});
+```
+
+The [React Server Components guide](/guides/basic-features/render/rsc.md) is retained as reference material for future upstream adoption.

package/docs/configure/app/server/ssr-by-entries.md

@@ -0,0 +1,25 @@
+# server.ssrByEntries
+
+- **Type:** `Object`
+- **Default:** `undefined`
+
+Set SSR options by entry, and the properties inside the option are the same as [ssr](/configure/app/server/ssr.md). 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/configure/app/server/ssr.md

@@ -0,0 +1,80 @@
+# 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](/guides/basic-features/data/data-fetch.md#data-loader-recommended), it will default to rendering the [`Error`](/guides/basic-features/routes/routes.md#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](/guides/basic-features/data/data-fetch.md#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/configure/app/server/tsconfig-path.md

@@ -0,0 +1,59 @@
+# 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/configure/app/source/alias-strategy.md

@@ -0,0 +1,14 @@
+# source.aliasStrategy
+
+:::warning Deprecation Warning
+`source.aliasStrategy` is deprecated, please use [resolve.aliasStrategy](/configure/app/resolve/alias-strategy.md) 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.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - source.aliasStrategy](https://v2.rsbuild.dev/config/source/alias-strategy).
+:::

package/docs/configure/app/source/alias.md

@@ -0,0 +1,23 @@
+# source.alias
+
+:::warning Deprecation Warning
+`source.alias` is deprecated, please use [resolve.alias](/configure/app/resolve/alias.md) 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).
+:::
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - source.alias](https://v2.rsbuild.dev/config/source/alias).
+:::

package/docs/configure/app/source/config-dir.md

@@ -0,0 +1,20 @@
+# 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.md).
+
+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/configure/app/source/decorators.md

@@ -0,0 +1,25 @@
+# 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/configure/app/source/define.md

@@ -0,0 +1,16 @@
+# 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.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - source.define](https://v2.rsbuild.dev/config/source/define).
+:::

package/docs/configure/app/source/disable-default-entries.md

@@ -0,0 +1,28 @@
+# 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.md).
+
+:::
+
+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.md) 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/configure/app/source/enable-async-entry.md

@@ -0,0 +1,54 @@
+# 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
+
+Module Federation (MF) is a technology solution that allows multiple JavaScript applications to share code and resources. Similar to microservices architecture on the server side, it allows you to split large applications into multiple independent smaller applications that can be developed, tested, and deployed independently, while dynamically loading modules from other applications at runtime.
+
+Module Federation solves the problem of code duplication across multiple frontend applications. In the traditional approach, if multiple applications need to use the same components or utility functions, you would need to duplicate this code in each application, leading to code duplication, high maintenance costs, and larger application sizes. With Module Federation, you can place common code in one application and have other applications load it dynamically as needed, enabling code sharing and reducing duplication.
+
+Module Federation 2.0 supports [Rspack](https://rspack.rs/) build tools, and provides enhanced features such as dynamic type hints, Manifest, Federation Runtime, runtime plugin system, and Chrome Devtools support for better development experience and debugging capabilities. You can visit the [Module Federation official documentation](https://module-federation.io/) to learn more.
+
+Modern.js provides an example project for Module Federation. Please refer to [module-federation-examples - modernjs](https://github.com/module-federation/module-federation-examples/tree/db5bdbeee56f779999a2c591fc553eb94eb20b36/modernjs).
+
+## 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.md).
+
+:::

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

@@ -0,0 +1,26 @@
+# 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/configure/app/source/entries-dir.md

@@ -0,0 +1,35 @@
+# 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',
+};
+```