@modern-js/app-tools 3.7.0 → 3.8.0

package/docs/configure/app/runtime/0-intro.md

@@ -0,0 +1,58 @@
+# Introduce
+
+Modern.js runtime configuration should be centralized in the `src/modern.runtime.ts` file.
+
+:::info
+
+If this file doesn't exist in your project yet, create it with the following command:
+
+```bash
+touch src/modern.runtime.ts
+```
+
+:::
+
+## Basic Configuration
+
+```tsx
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+export default defineRuntimeConfig({
+  router: {
+    // Router configuration
+  },
+  // Other runtime modules...
+});
+```
+
+## Multi-Entry Configuration
+
+For multi-entry applications, `defineRuntimeConfig` can accept a function that returns specific configurations based on the entry name:
+
+```tsx
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+export default defineRuntimeConfig(entryName => {
+  if (entryName === 'main') {
+    return {
+      router: {
+        // Router configuration for "main" entry
+      },
+    };
+  }
+
+  // Configuration for other entries
+  return {
+    router: {
+      // Other entry router configuration
+    },
+  };
+});
+```
+
+:::tip
+
+Using the `src/modern.runtime.ts` configuration approach does not support exporting asynchronous functions, which is related to the rendering method of Modern.js. If you need to add asynchronous logic, please use the **[Runtime Plugin](/plugin/introduction.md#runtime-plugin)**.
+
+:::
+

package/docs/configure/app/runtime/plugins.md

@@ -0,0 +1,58 @@
+# plugins
+
+- **Type:** `RuntimePlugin[]`
+- **Default:** `[]`
+
+Used to configure custom Modern.js Runtime plugins. For details on how to create custom Runtime plugins, please refer to [How to Write Runtime Plugins](/plugin/introduction.md#runtime-plugins).
+
+:::info
+
+Runtime plugins must be configured in the `plugins` array within the `src/modern.runtime.ts` file.
+
+:::
+
+## Examples
+
+Here are examples demonstrating how to use Runtime plugins:
+
+### Using plugins from npm packages
+
+To use plugins published on npm, first install them via your package manager, then import them into your configuration.
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import { myPlugin } from 'my-plugin';
+
+export default defineRuntimeConfig({
+  plugins: [myPlugin()],
+});
+```
+
+### Using local plugins
+
+To use plugins from your local codebase, import them directly using relative paths.
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import { myPlugin } from './config/plugin/myPlugin';
+
+export default defineRuntimeConfig({
+  plugins: [myPlugin()],
+});
+```
+
+### Plugin configuration
+
+If a plugin supports custom configuration options, you can provide them as arguments to the plugin function.
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import { myPlugin } from './config/plugin/myPlugin';
+
+export default defineRuntimeConfig({
+  plugins: [myPlugin({
+    foo: 1,
+    bar: 2,
+  })],
+});
+```

package/docs/configure/app/runtime/router.md

@@ -0,0 +1,35 @@
+# router
+
+- **Type:** `Object`
+- **Default:** `{}`
+
+This configuration item is used to configure client-side routing, supporting the use of [conventional routing](/guides/concept/entries.md#convention-routing) provided by Modern.js for routing management.
+
+:::note
+The `router` configuration item **only takes effect when using conventional routing entries** (i.e., when there is a `routes/` directory in the entry). For controlled routing entries or custom entries, this configuration will not take effect.
+
+In multi-entry applications, you can configure different routing behaviors for different entries using the function form of `defineRuntimeConfig`. For more details, see [Runtime Configuration Introduction](/configure/app/runtime/0-intro.md#multi-entry-configuration).
+:::
+
+## basename
+
+- **Type:** `string`
+- **Default:** `/`
+
+Sets the `basename` for client-side routing, typically used when the application needs to be deployed under a non-root path of the domain.
+
+:::tip
+It is recommended to use [`server.baseUrl`](/configure/app/server/base-url.md) for configuration.
+:::
+
+## supportHtml5History
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+If the value of `supportHtml5History` is `true`, `BrowserRouter` would be used, otherwise `HashRouter` would be used. `BrowserRouter` is recommended.
+
+:::warning
+When SSR is enabled, `supportHtml5History` is not supported.
+
+:::

package/docs/configure/app/security/check-syntax.md

@@ -0,0 +1,69 @@
+# security.checkSyntax
+
+- **Type:**
+
+```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.minify** to false 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/rstackjs/rsbuild-plugin-check-syntax).

package/docs/configure/app/security/nonce.md

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

package/docs/configure/app/security/sri.md

@@ -0,0 +1,20 @@
+# security.sri
+
+- **Type**
+
+```ts
+type SriOptions = {
+  hashFuncNames?: [string, ...string[]];
+  enabled?: 'auto' | true | false;
+};
+```
+
+- **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://v2.rsbuild.rs/zh/config/security/sri).
+
+This configuration type is not completely consistent with Rsbuild and will be automatically converted during the build process.
+:::

package/docs/configure/app/server/base-url.md

@@ -0,0 +1,26 @@
+# server.baseUrl
+
+- **Type:** `string | string[]`
+- **Default:** `undefined`
+
+Uniformly set the prefix of server-side routes (commonly used in situations where multiple applications share the same domain name to distinguish traffic).
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    // All generated routes will automatically have the prefix `/base`
+    // Generated server-side route file path: dist/route.json
+    baseUrl: '/base'
+
+    // Multiple baseUrl
+    baseUrl: ['/base-new', '/base-old']
+  }
+})
+```
+
+After running `dev`, you will see that the route access will have the corresponding prefix added:
+
+```bash
+  > Local:    http://localhost:8080/base/
+  > Network:  http://192.168.0.1:8080/base/
+```

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

@@ -0,0 +1,18 @@
+# server.port
+
+- **Type:** `number`
+- **Default:** `8080`
+
+When running the `dev` and `serve` commands, Modern.js will start with `8080` as the default port and automatically increase the port number when the port is occupied. You can use this configuration to modify the port number that the Server starts with:
+
+```js title="modern.config.ts"
+export default defineConfig({
+  server: {
+    port: 3000,
+  },
+});
+```
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - server.port](https://v2.rsbuild.dev/config/server/port).
+:::

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

@@ -0,0 +1,22 @@
+# server.publicRoutes
+
+- **Type:** `Object`
+- **Default:** Server-side routing rules generated based on file conventions, with one route rule generated for each file.
+
+This configuration option only applies to server-side routing and can customize the access route of resources under `config/public/`.
+
+The `key` of the object is the relative file path of the `config/public/` (without using `./`), and the value can be a `string`.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    publicRoutes: {
+      // Set a long route
+      'index.json': '/user-config/card-info/extra/help.json',
+
+      // Set a route without a suffix
+      'robot.txt': '/app/authentication',
+    },
+  },
+});
+```

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,26 @@
+# server.rsc
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Enable React Server Components (RSC) configuration.
+
+When set to `true`, enables React Server Components support in Modern.js. This allows components to be rendered on the server, providing better performance and developer experience.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    rsc: true,
+  },
+});
+```
+
+:::tip Prerequisites
+Before enabling RSC, ensure:
+
+1. React and React DOM are upgraded to version 19 (recommended 19.2.4 or above)
+2. Install the `react-server-dom-rspack@0.0.2` dependency
+
+:::
+
+For more information about using RSC, see the [React Server Components guide](/guides/basic-features/render/rsc.md).

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,78 @@
+# server.ssr
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Enalbe 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) |
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    ssr: {
+      forceCSR: true,
+      mode: 'stream',
+      unsafeHeaders: ['User-Agent']
+    },
+  },
+});
+```
+
+### 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 ts-node 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, TypeScript / ts-node 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',
+  },
+});
+```