@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.97 → 3.5.0-ultramodern.99

package/docs/components/micro-master-manifest-config.mdx

@@ -0,0 +1,15 @@
+## manifest
+
+```ts
+interface Manifest {
+  getAppList?: () => Array<AppInfo>;
+}
+```
+
+### getAppList?
+
+Through the `getAppList` configuration, you can customize how to get remote list data
+
+```ts
+type GetAppList = () => Promise<Array<AppInfo>>;
+```

package/docs/components/micro-runtime-config.mdx

@@ -0,0 +1,17 @@
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+export default defineRuntimeConfig({
+  masterApp: {
+    apps: [{
+      name: 'Table',
+      entry: 'http://localhost:8081',
+      // activeWhen: '/table'
+    }, {
+      name: 'Dashboard',
+      entry: 'http://localhost:8082'
+      // activeWhen: '/dashboard'
+    }]
+  },
+});
+```

package/docs/components/module-federation.mdx

@@ -0,0 +1,7 @@
+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).

package/docs/components/nodeVersion.mdx

@@ -0,0 +1,28 @@
+Before getting started, you will need to install [Node.js](https://nodejs.org/), and ensure that your Node.js version is not lower than v20.19.5. **We recommend using the LTS version of Node.js 22.**
+
+You can check the currently used Node.js version with the following command:
+
+```bash
+node -v
+```
+
+If you do not have Node.js installed in your current environment, or the installed version is lower than v20.19.5, you can use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm) to install the required version.
+
+Here is an example of how to install the Node.js 22 LTS version via nvm:
+
+```bash
+# Install the long-term support version of Node.js 22
+nvm install 22 --lts
+
+# Make the newly installed Node.js 22 as the default version
+nvm alias default 22
+
+# Switch to the newly installed Node.js 22
+nvm use 22
+```
+
+:::tip nvm and fnm
+Both nvm and fnm are Node.js version management tools. Relatively speaking, nvm is more mature and stable, while fnm is implemented using Rust, which provides better performance than nvm.
+:::
+
+Additionally, after installing nvm or fnm, when there is a `.nvmrc` file containing `lts/jod` in the repository's root directory, the system will automatically install or switch to the correct Node.js version upon entering the repository.

package/docs/components/output-polyfill-extend.mdx

@@ -0,0 +1 @@
+Modern.js also provides a runtime Polyfill solution based on browser [UA](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/User-Agent) information. For detailed usage instructions, please refer to [Polyfill At Runtime](https://modernjs.dev/en/guides/advanced-features/compatibility.html#polyfill-at-runtime).

package/docs/components/prerequisites.mdx

@@ -0,0 +1,18 @@
+### Node.js
+
+import NodeVersion from '@site-docs-en/components/nodeVersion.mdx';
+
+<NodeVersion />
+
+### pnpm
+
+It is recommended to use [pnpm](https://pnpm.io/installation) to manage dependencies:
+
+```bash
+mise use pnpm@11.17.0
+```
+
+:::note
+Modern.js also supports dependency management with `yarn` and `npm`.
+
+:::

package/docs/components/release-note.mdx

@@ -0,0 +1 @@
+According to the [Release Note](https://github.com/web-infra-dev/modern.js/releases) on the official website, developers can also manually upgrade the project to the desired version.

package/docs/components/rsbuild-config-tooltip.mdx

@@ -0,0 +1,5 @@
+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={props.configName}/>.
+:::

package/docs/components/rsbuild.mdx

@@ -0,0 +1,3 @@
+[Rsbuild](https://v2.rsbuild.rs/) is an Rspack-based build tool for the web. The main goal of Rsbuild is to provide out-of-the-box build capabilities for Rspack users, allowing developers to start a web project with zero configuration.
+
+Rsbuild integrates high-performance Rust-based tools from the community, including Rspack and SWC, to provide first-class build speed and development experience.

package/docs/components/rsc-deploy-tip.mdx

@@ -0,0 +1 @@
+

package/docs/components/rspack.mdx

@@ -0,0 +1,3 @@
+[Rspack](https://rspack.rs/) is a high performance JavaScript bundler written in Rust. It offers strong compatibility with the webpack ecosystem, allowing for seamless replacement of webpack, and provides lightning fast build speeds.
+
+Compared to webpack, Rspack has significantly improved build performance, thanks not only to the language advantages brought by Rust, but also to its parallel architecture and incremental compilation features. Benchmarking has shown that Rspack can provide 5-10 times better compilation performance.

package/docs/components/rspackTip.mdx

@@ -0,0 +1,7 @@
+:::tip Rspack - A High Performance JavaScript Bundler
+
+import Rspack from './rspack.mdx';
+
+<Rspack />
+
+:::

package/docs/components/serve-command.mdx

@@ -0,0 +1,22 @@
+## modern serve
+
+The `modern serve` command is used to start an UltraModern.js project in the production environment. It can also be used to preview the artifacts built for the production environment locally. Please note that you need to execute the [`build`](/apis/app/commands#modern-build) command beforehand to generate the corresponding artifacts.
+
+```bash
+Usage: modern serve [options]
+
+Options:
+  -c --config <config>  specify the configuration file, which can be a relative or absolute path
+  -h, --help            show command help
+  --api-only            only run API service
+```
+
+By default, the project will run in `localhost:8080`, you can modify the server port number with `server.port`:
+
+```js
+export default defineConfig({
+  server: {
+    port: 8081,
+  },
+});
+```

package/docs/components/ssr-monitor.mdx

@@ -0,0 +1,3 @@
+:::tip
+SSR monitoring has been integrated into the Monitors module, see [Monitors](/guides/advanced-features/server-monitor/monitors) for details.
+:::

package/docs/components/swc.mdx

@@ -0,0 +1,3 @@
+[SWC](https://SWC.rs/) (Speedy Web Compiler) is a transformer and minimizer for JavaScript and TypeScript based on `Rust`. SWC can provide the same abilities with Babel, and it's more than 10x faster than Babel.
+
+Modern.js has a out-of-box plugin for SWC, power your Web application with Polyfill and minification, we also port some common used Babel plugins to SWC.

package/docs/components/tech-stack-node-framework.mdx

@@ -0,0 +1 @@
+Modern.js Server uses [Hono.js](https://hono.dev/) as the server runtime framework. For BFF, `bff.runtimeFramework` defaults to `effect`, while `hono` remains an explicit compatibility runtime. Effect and Hono BFF runtimes are strict modes (no implicit fallback). You can extend the Server based on the Hono.js ecosystem; refer to [Custom Web Server](/guides/advanced-features/web-server.html).

package/docs/components/turtorials-example-list.mdx

@@ -0,0 +1,2 @@
+- [Route Authorization](/tutorials/examples/csr-auth.html)
+- ...

package/docs/components/ua-polyfill.mdx

@@ -0,0 +1,44 @@
+### Polyfill At Runtime
+
+Modern.js also provides a runtime Polyfill solution based on browser [UA](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/User-Agent) information, which has the following advantages over Babel:
+
+- It will not be inserted into the code, and only delivers Polyfill code on-demand based on the device accessing the page, reducing the overall code size.
+- The same browser will share a Polyfill code. Therefore, with more and more projects, the UA-based Polyfill code will be delivered faster and faster, with overall speed exceeding conventional solutions.
+
+Modern.js provides the `@modern-js/plugin-polyfill` plugin to implement this feature. You can enable it by installing the plugin:
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs
+  command={{
+    npm: 'npm install @modern-js/plugin-polyfill',
+    yarn: 'yarn add @modern-js/plugin-polyfill',
+    pnpm: 'pnpm add @modern-js/plugin-polyfill',
+  }}
+/>
+
+Then register the Polyfill plugin in `modern.config.ts`:
+
+```ts title="modern.config.ts"
+import { polyfillPlugin } from '@modern-js/plugin-polyfill';
+
+export default defineConfig({
+  plugins: [..., polyfillPlugin()],
+});
+```
+
+After configuring `output.polyfill` as `ua` and executing `pnpm run build && pnpm run serve` to start the server, visiting the page can see that the HTML artifacts contains the following script:
+
+```js
+<script src="/__polyfill__" crossorigin></script>
+```
+
+When accessing the page on Chrome 51, you can see the content returned by `http://localhost:8080/__polyfill__` as follows:
+
+![ua-polyfill](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ua-polyfill.png)
+
+:::caution
+This feature only works when using Modern.js built-in Web Server.
+
+If you need to customize the HTML template, please refer to [HTML Template](/guides/basic-features/html.html). Manually modifying the template through `html.template` or `tools.html` may cause this feature to not work correctly.
+:::

package/docs/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/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/configure/app/bff/effect.mdx

@@ -0,0 +1,319 @@
+---
+title: effect
+---
+
+# bff.effect
+
+- **Type:**
+
+```ts
+type BffEffectUserConfig = {
+  entry?: string;
+  strictEffectApproach?: true;
+  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'`.
+
+:::caution Install the Effect peers yourself
+`effect` and `@effect/opentelemetry` are **optional exact peer dependencies** of
+`@modern-js/plugin-bff`, not dependencies. The plugin no longer bundles a copy —
+Effect 4 derives `Context` / `Service` keys per module instance, so a bundled copy
+would give your app a second Effect identity. Before setting
+`runtimeFramework: 'effect'` or importing `@modern-js/plugin-bff/effect`,
+`/effect-server`, `/effect-edge` or `/effect-client`, install the exact cohort:
+
+```bash
+pnpm add effect@4.0.0-beta.102 @effect/opentelemetry@4.0.0-beta.102
+```
+
+The pin is exact because UltraModern ships Effect as one lockstep cohort. Apps
+using only `runtimeFramework: 'hono'` or the `./data-platform` lane need neither
+package.
+:::
+
+Generated UltraModern workspaces use this runtime as the only generated HTTP API
+path. The API contract lives at `shared/api.ts`, the server runtime lives at
+`api/index.ts`, clients live under `src/api/*-client.ts`, and generated checks
+reject `api/effect`, `api/lambda`, `shared/effect`, `src/effect`, Hono server
+imports, raw request handlers, manual request parsing, and manual `Response`
+construction in API modules.
+
+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>/index`
+
+Specifies the entry module for Effect HttpApi runtime.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    runtimeFramework: 'effect',
+    effect: {
+      entry: './api/index',
+    },
+  },
+});
+```
+
+## bff.effect.strictEffectApproach
+
+- **Type:** `true`
+- **Default:** `true`
+
+Effect BFF modules must expose the strict Effect API surface
+(`defineEffectBff(...)` or `{ api, layer }`) and raw request handlers are
+rejected. Generated UltraModern apps write this marker explicitly and pair it
+with source checks that reject Hono server imports, manual request parsing, and
+manual `Response` construction in generated API modules.
+
+## 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:**
+
+```ts
+{
+  enabled: true,
+  requireEnvelope: false,
+  envelopeHeader: 'x-modernjs-data-envelope',
+  validateOrigin: true,
+  requireTraceContext: false,
+  batch: {
+    enabled: true,
+    endpoint: '/_data/batch',
+    maxBatchSize: 16,
+    maxBatchBytes: 64 * 1024,
+    flushIntervalMs: 8,
+    maxConcurrency: 4,
+    requestTimeoutMs: 10000,
+    allowedMethods: ['GET'],
+  },
+}
+```
+
+Configure request-envelope validation for Effect runtime.
+
+Generated Effect client requests batching against `${bff.prefix}${batch.endpoint}` (for example, `/bff-api/_data/batch`).
+
+Envelope validation is enabled by default but optional: requests without an envelope pass unless `requireEnvelope` is `true`. If an envelope is present, runtime validates it against the configured namespace, origin, trace, and selection policy. `expectedNamespace` is unset by default, and `selection` has no default limits unless configured.
+
+Origin validation is enabled by default. Runtime compares envelope origin with request `Origin` header first, then falls back to request URL origin; set `validateOrigin: false` to disable that comparison.
+
+```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 the client-side micro-batch window in the generated Effect client. `maxConcurrency` and `requestTimeoutMs` are applied by the server batch gateway when dispatching items.
+
+The generated `api.client.*` API only exists for loader-materialized `@api/index` imports. Directly importing the server entry (`api/index`) exposes the Effect BFF definition; its `client` property is a placeholder that fails on operation access.
+
+## Effect cohort
+
+UltraModern-generated workspaces pin the framework-compatible Effect cohort
+through `pnpm-workspace.yaml` overrides. For the current UltraModern cohort,
+generated apps use:
+
+```yaml
+minimumReleaseAgeExclude:
+  - 'effect@4.0.0-beta.102'
+  - '@effect/opentelemetry@4.0.0-beta.102'
+
+trustPolicyExclude:
+  - 'effect@4.0.0-beta.102'
+  - '@effect/opentelemetry@4.0.0-beta.102'
+
+overrides:
+  '@effect/opentelemetry': 4.0.0-beta.102
+  '@effect/vitest': 4.0.0-beta.102
+  effect: 4.0.0-beta.102
+```
+
+Do not add a different direct `effect` version in an app package. A mismatched
+Effect beta can fail while building layers or HTTP middleware because runtime
+services come from different package instances. Keep the generated
+policy exclusion entries with the same Effect cohort; they handle the
+framework-selected Effect beta versions before the 24-hour maturity window and
+the `effect`/`@effect/opentelemetry` trusted-publisher to provenance metadata
+transition without weakening UltraModern API architecture checks.
+
+## Contract tests
+
+Strict Effect APIs should test the declared `HttpApi` contract, not a raw
+request handler. Edge-compatible tests can use the framework helper:
+
+```ts
+import { createEffectBffTestHandler } from '@modern-js/plugin-bff/effect-edge';
+import apiModule from '../api/index';
+
+const testApi = await createEffectBffTestHandler({
+  module: apiModule,
+  prefix: '/api',
+});
+
+const response = await testApi.handler(new Request('http://localhost/api/ping'));
+```
+
+If you manually compose an Effect web handler in a low-level proof, provide the
+platform services explicitly:
+
+```ts
+import {
+  HttpApiBuilder,
+  HttpRouter,
+  HttpServer,
+  Layer,
+} from '@modern-js/plugin-bff/effect-server';
+
+const handler = HttpRouter.toWebHandler(
+  HttpApiBuilder.layer(api).pipe(
+    Layer.provide(apiGroupLayer),
+    Layer.provide(HttpServer.layerServices),
+  ),
+).handler;
+```
+
+Prefer the generated helper unless the test needs to inspect the low-level
+Effect router composition.
+
+## Dynamic CORS
+
+For dynamic origin predicates, use Effect HTTP middleware as a layer. In the
+current Effect v4 beta cohort, `HttpRouter.middleware(...)` returns a `Layer`
+directly:
+
+```ts
+import {
+  Effect,
+  HttpApiBuilder,
+  HttpMiddleware,
+  HttpRouter,
+  Layer,
+} from '@modern-js/plugin-bff/effect-server';
+
+const corsLayer = HttpRouter.middleware(
+  Effect.succeed(
+    HttpMiddleware.cors({
+      allowedOrigins: origin =>
+        origin.endsWith('.example.com') ? origin : undefined,
+    }),
+  ),
+);
+
+const layer = HttpApiBuilder.layer(api).pipe(
+  Layer.provide(apiGroupLayer),
+  Layer.provide(corsLayer),
+);
+```
+
+Do not read a `.layer` property from `HttpRouter.middleware(...)`.
+
+## Other transports
+
+`strictEffectApproach` governs generated HTTP API modules. Effect RPC,
+WebSockets, and other transports remain valid when they are modeled as explicit
+transport surfaces with typed Effect programs. They do not make raw HTTP
+request handlers valid inside generated UltraModern API modules.