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

package/docs/configure/app/performance/dns-prefetch.md

@@ -0,0 +1,15 @@
+# performance.dnsPrefetch
+
+- **Type:** `undefined | string[]`
+
+- **Default:** `undefined`
+
+Specifies that the user agent should preemptively perform DNS resolution for the target resource's origin, refer to [dns-prefetch](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/dns-prefetch).
+
+After this property is set, the domain name can be resolved before the resource is requested, reducing request latency and improving loading performance.
+
+See [Using dns-prefetch](https://developer.mozilla.org/en-US/docs/Web/Performance/dns-prefetch) for more details.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - performance.dnsPrefetch](https://v2.rsbuild.dev/config/performance/dns-prefetch).
+:::

package/docs/configure/app/performance/preconnect.md

@@ -0,0 +1,16 @@
+# performance.preconnect
+
+- **Type:** `undefined | Array<string | PreconnectOption>`
+
+```ts
+interface PreconnectOption {
+  href: string;
+  crossorigin?: boolean;
+}
+```
+
+- **Default:** `undefined`
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - performance.preconnect](https://v2.rsbuild.dev/config/performance/preconnect).
+:::

package/docs/configure/app/performance/prefetch.md

@@ -0,0 +1,21 @@
+# performance.prefetch
+
+- **Type:** `undefined | true | PrefetchOption`
+
+```ts
+type IncludeType = 'async-chunks' | 'initial' | 'all-assets' | 'all-chunks';
+
+type Filter = Array<string | RegExp> | ((filename: string) => boolean);
+
+interface PrefetchOption {
+  type?: IncludeType;
+  include?: Filter;
+  exclude?: Filter;
+}
+```
+
+- **Default:** `undefined`
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - performance.prefetch](https://v2.rsbuild.dev/config/performance/prefetch).
+:::

package/docs/configure/app/performance/preload.md

@@ -0,0 +1,23 @@
+# performance.preload
+
+- **Type：** `undefined | true | PreloadOption`
+
+```ts
+type IncludeType = 'async-chunks' | 'initial' | 'all-assets' | 'all-chunks';
+
+type Filter = Array<string | RegExp> | ((filename: string) => boolean);
+
+interface PreloadOption {
+  type?: IncludeType;
+  include?: Filter;
+  exclude?: Filter;
+}
+```
+
+- **Default：** `undefined`
+
+Inject the [`<link rel="preload">`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Attributes/rel/preload) tags for the static assets generated by Rsbuild.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - performance.preload](https://v2.rsbuild.dev/config/performance/preload).
+:::

package/docs/configure/app/performance/print-file-size.md

@@ -0,0 +1,40 @@
+# performance.printFileSize
+
+- **Type:**
+
+```ts
+type PrintFileSizeOptions =
+  | {
+      /**
+       * whether to print total size
+       */
+      total?: boolean;
+      /**
+       * whether to print size of each file
+       */
+      detail?: boolean;
+      /**
+       * whether to print gzip-compressed size
+       */
+      compressed?: boolean;
+    }
+  | boolean;
+```
+
+- **Default:** `true`
+
+Whether to print the file sizes after production build.
+
+```bash
+info    Production file sizes:
+
+  File                                      Size         Gzipped
+  dist/static/js/lib-react.09721b5c.js      152.6 kB     49.0 kB
+  dist/html/main/index.html                 5.8 kB       2.5 kB
+  dist/static/js/main.3568a38e.js           3.5 kB       1.4 kB
+  dist/static/css/main.03221f72.css         1.4 kB       741 B
+```
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - performance.printFileSize](https://v2.rsbuild.dev/config/performance/print-file-size).
+:::

package/docs/configure/app/performance/profile.md

@@ -0,0 +1,10 @@
+# performance.profile
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether capture timing information for each module, same as the [profile](https://rspack.rs/config/other-options#profile) config of Rspack.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - performance.profile](https://v2.rsbuild.dev/config/performance/profile).
+:::

package/docs/configure/app/performance/remove-console.md

@@ -0,0 +1,10 @@
+# performance.removeConsole
+
+- **Type:** `boolean | ConsoleType[]`
+- **Default:** `false`
+
+Whether to remove `console.[methodName]` in production build.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - performance.removeConsole](https://v2.rsbuild.dev/config/performance/remove-console).
+:::

package/docs/configure/app/performance/remove-moment-locale.md

@@ -0,0 +1,10 @@
+# performance.removeMomentLocale
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to remove the locales of [moment.js](https://momentjs.com/).
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - performance.removeMomentLocale](https://v2.rsbuild.dev/config/performance/remove-moment-locale).
+:::

package/docs/configure/app/performance/rsdoctor.md

@@ -0,0 +1,38 @@
+# performance.rsdoctor
+
+- **Type:**
+
+```ts
+type RsdoctorConfig =
+  | boolean
+  | {
+      enabled?: boolean;
+      disableClientServer?: boolean;
+    };
+```
+
+- **Default:** `undefined`, Rsdoctor is disabled unless this option is configured.
+
+Configure Rsdoctor diagnostics in Modern.js build. Set this option to `true` to enable Rsdoctor:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  performance: {
+    rsdoctor: true,
+  },
+});
+```
+
+You can also use object form. When an object is provided, Rsdoctor is enabled unless `enabled` is set to `false`:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  performance: {
+    rsdoctor: {
+      enabled: true,
+    },
+  },
+});
+```
+
+To disable Rsdoctor after enabling it in shared config, set `rsdoctor` to `false` or set `enabled` to `false`.

package/docs/configure/app/plugins.md

@@ -0,0 +1,59 @@
+# plugins
+
+- **Type:** `CliPlugin[]`
+- **Default:** `[]`
+
+Used to configure custom Modern.js framework CLI plugins. For information on how to create custom CLI plugins, please refer to [How to Write CLI Plugins](/plugin/introduction.md#cli-plugins).
+
+## Note
+
+This option is **specifically for configuring framework CLI plugins**. If you need to configure other types of plugins, use the appropriate configuration method:
+
+- Use [builderPlugins](/configure/app/builder-plugins.md) for Rsbuild plugins.
+- Use [tools.bundlerChain](/configure/app/tools/bundler-chain.md) for Rspack plugins.
+- Use the [plugins field in runtime config](/configure/app/runtime/plugins.md) for framework Runtime plugins.
+
+## Examples
+
+Below are examples of using CLI plugins:
+
+### Using plugins from npm
+
+To use plugins from the npm registry, first install the plugins and then import them in your configuration:
+
+```ts title="modern.config.ts"
+import { myPlugin } from 'my-plugin';
+
+export default defineConfig({
+  plugins: [myPlugin()],
+});
+```
+
+### Using local plugins
+
+To use plugins from your local repository, import them directly using a relative path:
+
+```ts title="modern.config.ts"
+import { myPlugin } from './config/plugin/myPlugin';
+
+export default defineConfig({
+  plugins: [myPlugin()],
+});
+```
+
+### Plugin configuration
+
+If a plugin provides custom configuration options, pass them as parameters to the plugin function:
+
+```ts title="modern.config.ts"
+import { myPlugin } from 'my-plugin';
+
+export default defineConfig({
+  plugins: [
+    myPlugin({
+      foo: 1,
+      bar: 2,
+    }),
+  ],
+});
+```

package/docs/configure/app/resolve/alias-strategy.md

@@ -0,0 +1,10 @@
+# resolve.aliasStrategy
+
+- **Type:** `'prefer-tsconfig' | 'prefer-alias'`
+- **Default:** `'prefer-tsconfig'`
+
+Set the strategy for path alias resolution, to control the priority relationship between the paths option in `tsconfig.json` and the [resolve.alias](https://v2.rsbuild.rs/config/resolve/alias) option of Rsbuild.
+
+:::info
+该配置项的使用方式与 Rsbuild 完全一致。详细信息请参考 [Rsbuild - resolve.aliasStrategy](https://v2.rsbuild.dev/config/resolve/alias-strategy)。
+:::

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

@@ -0,0 +1,9 @@
+# resolve.alias
+
+- **Type:** `string[]`
+
+Create aliases for module paths to simplify import paths or redirect module references.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - resolve.alias](https://v2.rsbuild.dev/config/resolve/alias).
+:::

package/docs/configure/app/resolve/condition-names.md

@@ -0,0 +1,13 @@
+# resolve.conditionNames
+
+- **Type:** `string[]`
+- **Default:** Same as Rspack's `resolve.conditionNames`
+
+Specifies the condition names used to match entry points in the [exports](https://nodejs.org/api/packages.html#packages_exports) of a package.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - resolve.extensions](https://v2.rsbuild.dev/config/resolve/extensions).
+:::
+:::warning
+Do not enable this configuration option for SSR applications, as it will cause SSR rendering to fail.
+:::

package/docs/configure/app/resolve/dedupe.md

@@ -0,0 +1,9 @@
+# resolve.dedupe
+
+- **Type:** `string[]`
+
+Force Rsbuild to resolve the specified packages from project root, which is useful for deduplicating packages and reducing the bundle size. same as the [resolve.dedupe](https://v2.rsbuild.rs/config/resolve/dedupe) config of Rsbuild.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - resolve.dedupe](https://v2.rsbuild.dev/config/resolve/dedupe).
+:::

package/docs/configure/app/resolve/extensions.md

@@ -0,0 +1,13 @@
+# resolve.extensions
+
+- **Type:** `string[]`
+- **Default:** `['.ts', '.tsx', '.mjs', '.js', '.jsx', '.json']`
+
+Automatically resolve file extensions when importing modules. This means you can import files without explicitly writing their extensions.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - resolve.extensions](https://v2.rsbuild.dev/config/resolve/extensions).
+:::
+:::warning
+Do not enable this configuration option for SSR applications, as it will cause SSR rendering to fail.
+:::

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',
+    },
+  },
+});
+```