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

package/docs/en/configure/_meta.json

@@ -0,0 +1,78 @@
+[
+  "app/usage",
+  {
+    "type": "dir",
+    "name": "app/dev",
+    "label": "dev",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "app/bff",
+    "label": "bff",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "app/html",
+    "label": "html",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "app/tools",
+    "label": "tools",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "app/source",
+    "label": "source",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "app/resolve",
+    "label": "resolve",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "app/server",
+    "label": "server",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "app/output",
+    "label": "output",
+    "collapsed": true
+  },
+  "app/plugins",
+  {
+    "type": "dir",
+    "name": "app/security",
+    "label": "security",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "app/runtime",
+    "label": "runtime",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "app/performance",
+    "label": "performance",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "app/experiments",
+    "label": "experiments",
+    "collapsed": true
+  },
+  "app/builder-plugins",
+  "app/split-chunks"
+]

package/docs/en/configure/app/bff/cross-project.mdx

@@ -0,0 +1,24 @@
+---
+title: crossProject
+---
+
+# bff.crossProject
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+import EnableBFFCaution from "@site-docs-en/components/enable-bff-caution";
+
+<EnableBFFCaution />
+
+This configuration is used to enable BFF cross-project invocation functionality. When enabled, the current project can be used as a BFF producer, generating an SDK that can be directly called by other projects.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    crossProject: true,
+  },
+});
+```
+
+For detailed configuration and usage of BFF cross-project invocation, please refer to the [BFF Cross-Project Invocation Guide](/guides/advanced-features/bff/cross-project.html).

package/docs/en/configure/app/bff/effect.mdx

@@ -0,0 +1,152 @@
+---
+title: effect
+---
+
+# bff.effect
+
+- **Type:**
+
+```ts
+type BffEffectUserConfig = {
+  entry?: string;
+  openapi?: boolean | { path?: string };
+  dataPlatform?: {
+    enabled?: boolean;
+    requireEnvelope?: boolean;
+    envelopeHeader?: string;
+    expectedNamespace?: string;
+    validateOrigin?: boolean;
+    requireTraceContext?: boolean;
+    selection?: {
+      maxDepth?: number;
+      maxFields?: number;
+      allowedLeafPaths?: string[];
+    };
+    batch?: {
+      enabled?: boolean;
+      endpoint?: `/${string}`;
+      maxBatchSize?: number;
+      maxBatchBytes?: number;
+      flushIntervalMs?: number;
+      maxConcurrency?: number;
+      requestTimeoutMs?: number;
+      allowedMethods?: string[];
+    };
+  };
+};
+```
+
+- **Default:** `{}`
+
+import EnableBFFCaution from "@site-docs-en/components/enable-bff-caution";
+
+<EnableBFFCaution />
+
+`bff.effect` is only effective when `bff.runtimeFramework` is set to `'effect'`.
+
+For Effect v4, TypeScript should use export-map aware module resolution.
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "Bundler"
+  }
+}
+```
+
+## bff.effect.entry
+
+- **Type:** `string`
+- **Default:** `<apiDirectory>/effect/index`
+
+Specifies the entry module for Effect HttpApi runtime.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    runtimeFramework: 'effect',
+    effect: {
+      entry: './api/effect/index',
+    },
+  },
+});
+```
+
+## bff.effect.openapi
+
+- **Type:** `boolean | { path?: string }`
+- **Default:** `false`
+
+Enable OpenAPI endpoint generation for Effect HttpApi runtime.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    runtimeFramework: 'effect',
+    effect: {
+      openapi: {
+        path: '/openapi.json',
+      },
+    },
+  },
+});
+```
+
+## bff.effect.dataPlatform
+
+- **Type:**
+
+```ts
+{
+  enabled?: boolean;
+  requireEnvelope?: boolean;
+  envelopeHeader?: string;
+  expectedNamespace?: string;
+  validateOrigin?: boolean;
+  requireTraceContext?: boolean;
+  selection?: {
+    maxDepth?: number;
+    maxFields?: number;
+    allowedLeafPaths?: string[];
+  };
+  batch?: {
+    enabled?: boolean;
+    endpoint?: `/${string}`;
+    maxBatchSize?: number;
+    maxBatchBytes?: number;
+    flushIntervalMs?: number;
+    maxConcurrency?: number;
+    requestTimeoutMs?: number;
+    allowedMethods?: string[];
+  };
+}
+```
+
+- **Default:** `{ enabled: true }`
+
+Configure request-envelope validation for Effect runtime.
+
+Generated Effect client requests batching against `${bff.prefix}${batch.endpoint}` (for example, `/bff-api/_data/batch`).
+
+When `validateOrigin` is enabled, runtime compares envelope origin with request `Origin` header first, then falls back to request URL origin.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    runtimeFramework: 'effect',
+    effect: {
+      dataPlatform: {
+        requireEnvelope: true,
+        expectedNamespace: 'my-app',
+        selection: {
+          maxDepth: 6,
+          maxFields: 200,
+        },
+      },
+    },
+  },
+});
+```
+
+`batch.flushIntervalMs` controls client-side micro-batch window in generated Effect client. `maxConcurrency` and `requestTimeoutMs` are applied by the server batch gateway when dispatching items.

package/docs/en/configure/app/bff/prefix.mdx

@@ -0,0 +1,33 @@
+---
+title: prefix
+---
+
+# bff.prefix
+
+- **Type:** `string`
+- **Default:** `/api`
+
+import EnableBFFCaution from "@site-docs-en/components/enable-bff-caution";
+
+<EnableBFFCaution />
+
+By default, the prefix for accessing routes in the BFF API directory is `/api`, as shown in the following directory structure:
+
+```bash
+api
+└── hello.ts
+```
+
+The route corresponding to `api/hello.ts` when accessed is `localhost:8080/api/hello`.
+
+This configuration option can modify the default route prefix:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    prefix: '/api-demo',
+  },
+});
+```
+
+The corresponding route for `api/hello.ts` when accessed is `localhost:8080/api-demo/hello`.

package/docs/en/configure/app/bff/runtime-framework.mdx

@@ -0,0 +1,28 @@
+---
+title: runtimeFramework
+---
+
+# bff.runtimeFramework
+
+- **Type:** `'hono' | 'effect'`
+- **Default:** `'effect'`
+
+import EnableBFFCaution from "@site-docs-en/components/enable-bff-caution";
+
+<EnableBFFCaution />
+
+Controls which runtime framework Modern.js uses for BFF routing.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    runtimeFramework: 'effect',
+  },
+});
+```
+
+- Set to `'effect'` to run BFF only from `api/effect/index` (Effect HttpApi runtime).
+- Set to `'hono'` to run BFF only from file-convention handlers under `api/lambda/**`.
+
+There is no implicit fallback between runtimes. Choose one runtime mode per app.
+If you want the public UltraModern preset that prefers the Effect lane, configure it explicitly in your app or scaffold with the create template's Effect path.

package/docs/en/configure/app/builder-plugins.mdx

@@ -0,0 +1,70 @@
+---
+sidebar_position: 21
+---
+
+# builderPlugins
+
+- **Type:** `RsbuildPlugin[]`
+- **Default:** `[]`
+
+Used to configure the Rsbuild plugin.
+
+Rsbuild is the build tool of Modern.js, please read [Build Engine](/guides/concept/builder) for background. If you want to know how to write Rsbuild plugins, you can refer to [Rsbuild - Plugin System](https://v2.rsbuild.rs/plugins/dev/index).
+
+## Precautions
+
+This option **is used to configure the Rsbuild plugins**. If you need to configure other types of plugins, please select the corresponding configs:
+
+- Use [plugins](/configure/app/plugins) to configure Modern.js framework plugins.
+- Use [tools.bundlerChain](/configure/app/tools/bundler-chain) to configure Rspack plugins.
+
+## When to use
+
+In most scenarios, we recommend you to use the Modern.js framework plugin, which can be registered through the [plugins](/configure/app/plugins) config. Because the API provided by the framework plugin is richer and more capable, while the API provided by the Rsbuild plugin can only be used to build scenes.
+
+When you need to reference some existing Rsbuild plugins (and there is no related capability in Modern.js), or reuse Rsbuild plugins between different frameworks, you can use the `builderPlugins` field to register them.
+
+## Example
+
+Below is an example of using the Rsbuild plugin.
+
+### Using plugins on npm
+
+To use a plugin on npm, you need to install the plugin through the package manager and import it.
+
+```ts title="modern.config.ts"
+import myRsbuildPlugin from 'my-rsbuild-plugin';
+
+export default defineConfig({
+  builderPlugins: [myRsbuildPlugin()],
+});
+```
+
+### Using local plugins
+
+Use the plugin in the local code repository, you can import it directly through the relative path import.
+
+```ts title="modern.config.ts"
+import myRsbuildPlugin from './plugin/myRsbuildPlugin';
+
+export default defineConfig({
+  builderPlugins: [myRsbuildPlugin()],
+});
+```
+
+### Plugin configuration options
+
+If the plugin provides some custom configuration options, you can pass in the configuration through the parameters of the plugin function.
+
+```ts title="modern.config.ts"
+import myRsbuildPlugin from 'my-rsbuild-plugin';
+
+export default defineConfig({
+  builderPlugins: [
+    myRsbuildPlugin({
+      foo: 1,
+      bar: 2,
+    }),
+  ],
+});
+```

package/docs/en/configure/app/dev/asset-prefix.mdx

@@ -0,0 +1,18 @@
+---
+title: assetPrefix
+---
+
+# dev.assetPrefix
+
+- **Type:** `boolean | string | 'auto'`
+- **Default:** `'/'`
+
+This configuration item is used to set the URL prefix of static resources in **development mode**.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="dev.assetPrefix" />
+
+:::warning
+Please note that this configuration item is only applicable in development mode. In production mode, please use the [output.assetPrefix](/configure/app/output/asset-prefix) configuration item for setting.
+:::

package/docs/en/configure/app/dev/before-start-url.mdx

@@ -0,0 +1,21 @@
+---
+title: beforeStartUrl
+---
+
+# dev.beforeStartUrl
+
+- **Type:** `() => Promise<void> | void`
+- **Default:** `undefined`
+
+`dev.beforeStartUrl` is used to execute a callback function before opening the `startUrl`, this config needs to be used together with `dev.startUrl`.
+
+```js
+export default {
+  dev: {
+    startUrl: true,
+    beforeStartUrl: async () => {
+      await doSomeThing();
+    },
+  },
+};
+```

package/docs/en/configure/app/dev/client.mdx

@@ -0,0 +1,45 @@
+---
+title: client
+---
+
+# dev.client
+
+- **Type:**
+
+```ts
+type Client = {
+  // The protocol name for the WebSocket request
+  protocol?: 'ws' | 'wss';
+  // The path for the WebSocket request
+  path?: string;
+  // The port number for the WebSocket request
+  port?: string | number;
+  // The host for the WebSocket request
+  host?: string;
+  // The maximum number of reconnection attempts after a WebSocket request is disconnected.
+  reconnect?: number;
+  // Whether to display an error overlay in the browser when a compilation error occurs
+  overlay?: boolean;
+};
+```
+
+- **Default:**
+
+```js
+const defaultConfig = {
+  path: '/webpack-hmr',
+  port: '<port>',
+  // By default it is set to "location.hostname"
+  host: '',
+  // By default it is set to "location.protocol === 'https:' ? 'wss' : 'ws'""
+  protocol: undefined,
+  reconnect: 100,
+  overlay: false,
+};
+```
+
+Configure the client code injected by Modern.js during the development process. This can be used to set the WebSocket URL for HMR.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="dev.client" />

package/docs/en/configure/app/dev/hmr.mdx

@@ -0,0 +1,14 @@
+---
+title: hmr
+---
+
+# dev.hmr
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Whether to enable Hot Module Replacement.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="dev.hmr" />

package/docs/en/configure/app/dev/host.mdx

@@ -0,0 +1,22 @@
+---
+title: host
+---
+
+# dev.host
+
+- **Type:** `string`
+- **Default:** `0.0.0.0`
+
+Specify the host that the dev server listens to.
+
+By default, the dev server will listen to `0.0.0.0`, which means listening to all network interfaces, including `localhost` and public network addresses.
+
+If you want the dev server to listen only on `localhost`, you can set it to:
+
+```ts
+export default {
+  dev: {
+    host: 'localhost',
+  },
+};
+```

package/docs/en/configure/app/dev/https.mdx

@@ -0,0 +1,81 @@
+---
+title: https
+---
+
+# dev.https
+
+- **Type:** `boolean | { key: string; cert: string }`
+- **Default:** `false`
+
+After configuring this option, you can enable HTTPS Dev Server, and disabling the HTTP Dev Server.
+
+HTTP:
+
+```bash
+  > Local: http://localhost:8080/
+  > Network: http://192.168.0.1:8080/
+```
+
+HTTPS:
+
+```bash
+  > Local: https://localhost:8080/
+  > Network: https://192.168.0.1:8080/
+```
+
+#### Automatically generate certificates
+
+You can directly set `https` to `true`, Modern.js will automatically generate the HTTPS certificate based on [devcert](https://github.com/davewasmer/devcert).
+
+When using this method, you need to manually install the [devcert](https://github.com/davewasmer/devcert) dependency in your project:
+
+```bash
+# npm
+npm install devcert@1.2.2 -D
+
+# yarn
+yarn add devcert@1.2.2 -D
+
+# pnpm
+pnpm add devcert@1.2.2 -D
+```
+
+Then configure `dev.https` to `true`:
+
+```ts
+export default {
+  dev: {
+    https: true,
+  },
+};
+```
+
+The devcert has some limitations, it does not currently support IP addresses yet.
+
+:::tip
+The https proxy automatically installs the certificate and needs root authority, please enter the password according to the prompt.
+**The password is only used to trust the certificate, and will not be leaked or be used elsewhere**.
+:::
+
+#### Manually set the certificate
+
+You can also manually pass in the certificate and the private key required in the `dev.https` option. This parameter will be directly passed to the createServer method of the https module in Node.js.
+
+For details, please refer to [https.createServer](https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener).
+
+```ts
+import fs from 'fs';
+
+export default {
+  dev: {
+    https: {
+      key: fs.readFileSync('certificates/private.pem'),
+      cert: fs.readFileSync('certificates/public.pem'),
+    },
+  },
+};
+```
+
+#### Clean up cert cache
+
+The certificate created by devcert is saved in `~/Library/Application\ Support/devcert`. You may do some cleanup if needed.

package/docs/en/configure/app/dev/lazy-compilation.mdx

@@ -0,0 +1,45 @@
+---
+title: lazyCompilation
+---
+
+# dev.lazyCompilation
+
+- **Type:**
+
+```ts
+type LazyCompilationOptions =
+  | boolean
+  | {
+      /**
+       * Enable lazy compilation for entries.
+       */
+      entries?: boolean;
+      /**
+       * Enable lazy compilation for dynamic imports.
+       */
+      imports?: boolean;
+      /**
+       * Specify which imported modules should be lazily compiled.
+       */
+      test?: RegExp | ((m: Module) => boolean);
+      /**
+       * The path to a custom runtime code that overrides the default lazy compilation client.
+       */
+      client?: string;
+      /**
+       * Tells the client the server URL that needs to be requested.
+       */
+      serverUrl?: string;
+    };
+```
+
+- **Default:** `false`
+
+Enable lazy compilation (compilation on demand), implemented based on Rspack's [lazy compilation](https://rspack.rs/guide/features/lazy-compilation) feature.
+
+import RsbuildLink from '@site/src/components/RsbuildLink';
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to <RsbuildLink configName="dev.lazyCompilation"/>。
+In Rspack build mode,
+:::

package/docs/en/configure/app/dev/live-reload.mdx

@@ -0,0 +1,14 @@
+---
+title: liveReload
+---
+
+# dev.liveReload
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Whether to reload the page when source files are changed.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="dev.liveReload" />

package/docs/en/configure/app/dev/progress-bar.mdx

@@ -0,0 +1,23 @@
+---
+title: progressBar
+---
+
+# dev.progressBar
+
+- **Type:**
+
+```ts
+type ProgressBar =
+  | boolean
+  | {
+      id?: string;
+    };
+```
+
+- **Default:** true
+
+Whether to display progress bar during compilation.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="dev.progressBar" />