@bleedingdev/modern-js-main-doc 3.4.0-ultramodern.9 → 3.5.0-ultramodern.1

package/docs/en/guides/get-started/ultramodern.mdx

@@ -7,14 +7,16 @@ sidebar_position: 2
 
 This page compares **UltraModern.js 3.0** with the Modern.js 3.x line this fork tracks. The baseline is the current merged Modern.js `release-v3.x` baseline, not a frozen patch-version snapshot.
 
-UltraModern.js 3.0 is our SuperApp framework forked from Modern.js. It keeps compatibility with the Modern.js plugin/runtime mental model where that helps adoption, but it is positioned as a separate framework for Effect-first BFFs, TanStack Router, SSR, Module Federation, and independently deployable Micro Verticals.
+UltraModern.js 3.0 is our SuperApp framework forked from Modern.js. It keeps the Modern.js plugin/runtime mental model where that helps adoption, but it is positioned as a separate framework for Effect HttpApi-first HTTP APIs, TanStack Router, SSR, Module Federation, and independently deployable Micro Verticals.
 
 ## Design Principles
 
 - Keep deltas explicit and auditable.
-- Preserve compatibility with useful Modern.js concepts without presenting UltraModern.js as a preset-only variant.
+- Keep upstream Modern.js merge compatibility explicit: generic Modern.js runtime
+  code can remain where it belongs, while UltraModern-generated surfaces stay
+  strict.
 - Add platform-level contracts only where they improve cross-team reliability.
-- Keep opt-out switches and explicit compatibility lanes available.
+- Keep escape hatches explicit and outside the generated HTTP API path.
 
 ## Compatibility Contract
 
@@ -24,7 +26,9 @@ UltraModern.js 3.0 keeps:
 - Existing project structure and command flow.
 - Progressive adoption path (apps can stay mostly unchanged).
 
-UltraModern.js additions are designed as the default product surface for new SuperApps. Compatibility lanes remain available when they reduce migration risk, but the framework direction is Effect + TanStack + SSR + Micro Verticals.
+UltraModern.js additions are designed as the default product surface for new SuperApps. The framework direction is Effect + TanStack + SSR + Micro Verticals, and generated HTTP API work uses that direction by default instead of preserving parallel raw-handler layouts.
+Existing Modern.js apps can migrate gradually; once an API surface is generated
+or migrated as UltraModern HTTP API, it must use the strict Effect HttpApi path.
 
 ## Intentional Differences (v3 line)
 
@@ -33,7 +37,7 @@ UltraModern.js additions are designed as the default product surface for new Sup
 | Build diagnostics | RsDoctor is generally opt-in | Adds a first-class `performance.rsdoctor` config surface (opt-in; the earlier default-on behavior and diagnostics contract artifact were reverted) |
 | Output and static serving | Precompression behavior is app-defined | Enables `output.precompress` by default and serves `.br` / `.gz` variants via `Accept-Encoding` negotiation |
 | BFF runtime and contracts | Standard BFF runtime/client generation | Adds `requestId`-aware producer isolation, fail-fast initialization checks, and operation/trace correlation headers |
-| BFF runtime choices | Hono runtime path only in Modern.js 3.0 baseline (no built-in Effect runtime path) | Sets Effect as default runtime, enforces strict runtime split (`effect` -> `api/effect`, `hono` -> `api/lambda`), and adds Effect-Schema-first contracts plus MF failure-injection reliability coverage |
+| BFF runtime choices | Standard request-handler oriented BFF paths | Uses Effect `HttpApi` as the only generated HTTP API path (`api/index.ts`, `shared/api.ts`, `src/api/*`) and rejects raw handlers, manual parsing, manual `Response` construction, and Hono server imports in generated workspaces |
 | Telemetry standardization | Observability wiring is often app-specific | Adds framework-level telemetry pipeline with OTLP/VictoriaMetrics exporters, redaction, batching, and backpressure controls |
 | App-level MF SSR handshake | No dedicated super-app app-level stability contract focus | Adds `server.ssr.moduleFederationAppSSR` plus integration-tested env/config handshake |
 | MF vertical loading reliability | Retry/fallback patterns are often implemented per app | Adds deterministic timeout/network/contract-error reliability matrix and distributed OTEL continuity tests |
@@ -46,16 +50,19 @@ UltraModern.js additions are designed as the default product surface for new Sup
 
 - We do not hide the fork behind legacy Modern.js branding.
 - We do not optimize for generic Modern.js defaults when they conflict with SuperApp reliability.
-- We keep both runtime modes (`effect`, `hono`) as explicit choices and avoid implicit fallback between them.
-- We avoid incompatible API changes unless there is a hard reliability requirement.
+- We do not delete generic Modern.js Hono/file-convention runtime support just
+  to enforce UltraModern policy; the enforcement lives in UltraModern
+  generator, config, checks, and generated workspaces.
+- Generated UltraModern API work uses the Effect runtime only; raw Hono/function handlers are not part of the generated API architecture.
+- We make incompatible scaffold changes when they remove architecture drift.
 
 ## Migration Guide
 
-For teams already on Modern.js 3.0 or an older BleedingDev UltraModern scaffold, the adoption path remains compatibility-aware: keep the pieces that reduce risk, move toward MV-first / TanStack-first / Effect-first defaults, and keep fallback lanes explicit while you adopt UltraModern.js 3.0 as a separate framework.
+For teams already on Modern.js 3.0 or an older BleedingDev UltraModern scaffold, the adoption path is to move API work onto the strict Effect HttpApi surface instead of preserving older raw handler layouts.
 
-1. Keep existing React Router apps running as-is. TanStack Router is the preferred path for new scaffolds and incremental route adoption, but the React Router lane remains supported while teams move on their own schedule.
-2. Prefer `bff.runtimeFramework: 'effect'` for new BFF work, with the entry implemented at `api/effect/index.ts`. If your app already uses Hono handlers under `api/lambda/**`, keep `bff.runtimeFramework: 'hono'` until you are ready to move them; Hono remains a supported compatibility lane.
-3. Treat the baseline contracts as progressive defaults, not a forced cutover. `MODERN_BASELINE_ENABLE_MF_SSR`, `MODERN_BASELINE_ENABLE_BFF_REQUEST_ID`, and `MODERN_BASELINE_ENABLE_TELEMETRY_EXPORTERS` already let each app opt out while it converges on the preferred stack.
+1. Keep existing Modern.js apps running as-is while they are outside the generated UltraModern surface. TanStack Router is the preferred path for new scaffolds and incremental route adoption, but route migration can happen on the team's schedule.
+2. Use `bff.runtimeFramework: 'effect'` with `bff.effect.strictEffectApproach: true` for API work. Entries live at `api/index.ts`, contracts live at `shared/api.ts`, clients live under `src/api/*`, and request/response/error shapes come from Effect `Schema` plus `HttpApi`.
+3. Treat raw handlers, `api/lambda/**`, manual `Response` construction, and manual request parsing as migration defects in generated or migrated UltraModern workspaces.
 4. The public preset now ships with explicit release and certification gates. Generated workspaces include `.github/workflows/ultramodern-workspace-gates.yml`, so `pnpm check` and `pnpm build` stay part of the local adoption contract from day one while CI runs the primitive gates as parallel matrix jobs.
 
 For an older generated workspace, migrate by treating the published cohort as
@@ -71,14 +78,90 @@ mise exec -- pnpm check
 mise exec -- pnpm build
 ```
 
+Strict generated API migration requires `3.5.0-ultramodern.1` or newer.
+`3.4.0-ultramodern.20` and earlier cohorts do not include this full direct
+`api/index.ts` generator, generated `.mts` checks, strict Oxlint boundary rule
+set, Effect cohort overrides, and strict Effect migration command. Agents that
+cannot install that BleedingDev cohort yet should use the local Modern.js
+workspace for migration validation; otherwise pin `3.5.0-ultramodern.1` or
+newer with `--ultramodern-package-version`.
+
+Before hand-editing package aliases or generated metadata, run the framework
+migration command from the target workspace:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create@3.5.0-ultramodern.1 ultramodern \
+  migrate-strict-effect --version 3.5.0-ultramodern.1
+pnpm api:check
+pnpm contract:check
+```
+
+The command updates `.modernjs/ultramodern.json`, root
+`modernjs.packageSource`, generated Modern package aliases, direct topology API
+metadata, and the pnpm lockfile. Remaining failures are source migration work:
+move code to `shared/api.ts`, `api/index.ts`, and `src/api/*-client.ts`, then
+delete `api/effect`, `api/lambda`, `shared/effect`, and `src/effect`.
+
+Generated strict Effect workspaces pin the compatible Effect cohort with pnpm
+overrides: `effect@4.0.0-beta.89` and `@effect/vitest@4.0.0-beta.89`. Do not
+add app-local direct Effect versions that disagree with those overrides.
+
+Gradual migration means old, unmigrated Modern.js apps can keep their existing
+runtime until they are converted. Once a surface is generated or migrated as
+UltraModern HTTP API, it uses Effect HttpApi only; do not keep Hono, lambda
+handlers, or raw request handlers inside that UltraModern API surface.
+
+When migrating a generated workspace that already has nested Effect API files, make the
+move explicit and do not keep compatibility aliases:
+
+1. Move each vertical server entry from `verticals/<id>/api/effect/index.ts` to
+   `verticals/<id>/api/index.ts`.
+2. Move each shared API contract from `verticals/<id>/shared/effect/api.ts` to
+   `verticals/<id>/shared/api.ts`.
+3. Move generated clients from `verticals/<id>/src/effect/*-client.ts` to
+   `verticals/<id>/src/api/*-client.ts`.
+4. Move shell API aggregates from `apps/shell-super-app/src/effect/*` to
+   `apps/shell-super-app/src/api/*`.
+5. Update imports and package exports to use `./api`, `./api/client`, and
+   `@<workspace>/<vertical>/api/client`; remove `./effect/client`,
+   `./shared/effect/api`, and shared Effect API packages.
+6. Update every vertical `modern.config.ts` to use
+   `bff.effect.entry: './api/index'` and
+   `bff.effect.strictEffectApproach: true`.
+7. Update topology so API metadata lives directly under `api` with
+   `api.bff.strictEffectApproach: true`; do not keep `api.effect`.
+8. Run `pnpm api:check`,
+   `scripts/validate-ultramodern-workspace.mts`, `pnpm check`, and
+   `pnpm build`.
+
+If a migration fails, fix the owning generated contract, topology, package
+exports, or API module. Do not add app-level aliases, raw request handlers,
+manual `Response` construction, local type casts, or package shims to make the
+old layout pass.
+
+Effect RPC, WebSockets, and other transports should be added as explicit
+transport surfaces when needed. They do not make raw request handlers valid
+inside generated HTTP API modules.
+
+Strict API tests should exercise the `HttpApi` contract. Use
+`createEffectBffTestHandler` from `@modern-js/plugin-bff/effect-edge` for
+edge-compatible proof tests; if you manually compose a web handler, provide
+`HttpServer.layerServices` beside your API group layer before calling
+`HttpRouter.toWebHandler`.
+
+For dynamic origin CORS predicates inside strict Effect HTTP APIs, prefer
+`HttpRouter.middleware(Effect.succeed(HttpMiddleware.cors(...)))`.
+`HttpRouter.middleware(...)` returns a `Layer` directly in the pinned Effect
+cohort; do not read a `.layer` property from it.
+
 Use one package-source strategy per repo. The published BleedingDev create
 package defaults to `--ultramodern-package-source=install` and records the
-exact cohort in `.modernjs/ultramodern-package-source.json`. Keep `--workspace`
-only for local monorepo testing against unreleased packages. Release proof and
-CI should pin the exact cohort with `--ultramodern-package-version` when a
-repo must prove a specific published framework version.
+exact cohort in `.modernjs/ultramodern.json`. Keep `--workspace` only for local
+monorepo testing against unreleased packages. Release proof and CI should pin
+the exact cohort with `--ultramodern-package-version` when a repo must prove a
+specific published framework version.
 
-Older repos with Effect BFF entries and `verbatimModuleSyntax` should update to
+Older repos with nested Effect entries and `verbatimModuleSyntax` should update to
 the latest BleedingDev cohort instead of adding app-level `"type": "module"`
 metadata, Module Federation shims, or custom server wrappers. The framework BFF
 compiler normalizes CommonJS server output while generated app packages keep
@@ -92,11 +175,18 @@ repos by hand-editing generated worker output; upgrade the framework cohort and
 rerun the generated validation instead.
 
 After installing the new cohort, run the generated
-`scripts/validate-ultramodern-workspace.mjs` contract check before accepting
+`scripts/validate-ultramodern-workspace.mts` contract check before accepting
 manual edits. Fix topology, ownership, package-source, local overlay, generated
 contract, Tailwind prefix, or Module Federation conflicts in the owning files
 instead of patching generated output by hand.
 
+Cloudflare D1 bindings are first-class on `deploy.worker.d1Databases`; use that
+config instead of app-local postprocessing when a generated app owns D1
+migrations. Cloudflare public output excludes server-only `api` and `shared`
+directories by default, and generated Modern/Rspack caches are isolated per app
+and build target so local `build` and `cloudflare:build` runs do not share the
+same Rspack cache directory.
+
 ## Human Workflow
 
 The public BleedingDev create package has one supported generated product. The
@@ -182,10 +272,10 @@ addUltramodernVertical({
 ```
 
 The public result includes the workspace root, package source, created apps,
-created paths, rewritten paths, assigned ports, Module Federation names, Effect
-API prefixes, generated contract path, and warnings. MicroVertical dry-run
+created paths, rewritten paths, assigned ports, Module Federation names, API
+prefixes, generated contract path, and warnings. MicroVertical dry-run
 returns the same shape plus `dryRun`, `selectedPort`, `moduleFederationRemote`,
-`effectApiPrefix`, `jsonMutations`, `shellDependencyChanges`, and
+`apiPrefix`, `jsonMutations`, `shellDependencyChanges`, and
 `generatedContractChanges`; it prints JSON from the CLI and writes no files.
 
 CodeSmith consumers can use the adapter subpath:
@@ -239,8 +329,8 @@ non-indexable routes emit no JSON-LD by default. Public route owners can add
 `jsonLd` beside localized paths and use the generated
 `src/routes/ultramodern-jsonld.ts` helpers for common schema.org shapes.
 
-The generated contract writes `.modernjs/ultramodern-generated-contract.json`
-with a `cssFederation` section:
+The generated contract writes `.modernjs/ultramodern.json` with a
+`cssFederation` section:
 
 - `packages/shared-design-tokens` owns the shared token layer and exports `./tokens.css`.
 - Shell CSS owns only shell base and overlay layers under `[data-app-id="shell-super-app"]`.
@@ -248,7 +338,7 @@ with a `cssFederation` section:
 - Tailwind CSS v4 is local to each generated app through `@tailwindcss/postcss`; shared base styles must not be duplicated by verticals.
 - SSR first paint requires shared token CSS and app-owned CSS to be emitted by Modern/Rspack assets. Vertical CSS is loaded through manifest ownership, not copied into shell source.
 
-Version switching must select UI, Effect API, CSS, i18n JSON, and MF manifest evidence from the same vertical build marker. A shell render that only changes the UI marker is not enough.
+Version switching must select UI, API, CSS, i18n JSON, and MF manifest evidence from the same vertical build marker. A shell render that only changes the UI marker is not enough.
 
 ### Validation And Deploy
 

package/docs/en/guides/upgrade/config.mdx

@@ -314,7 +314,7 @@ export default {
 
 ### tools.pug
 
-**Change**: This configuration has been deprecated, use Rsbuild's [Pug plugin](https://github.com/rspack-contrib/rsbuild-plugin-pug) to enable support.
+**Change**: This configuration has been deprecated, use Rsbuild's [Pug plugin](https://github.com/rstackjs/rsbuild-plugin-pug) to enable support.
 
 **Migration Example**:
 

package/docs/en/plugin/introduction.mdx

@@ -131,21 +131,21 @@ The following are official Rsbuild plugins that are already built into Modern.js
 | [React Plugin](https://v2.rsbuild.rs/plugins/list/plugin-react)                        | Provides support for React                                                                                                                      | -                                                                                                                                     |
 | [SVGR Plugin](https://v2.rsbuild.rs/plugins/list/plugin-svgr)                          | Supports converting SVG images into React components                                                                                            | [output.disableSvgr](/configure/app/output/disable-svgr)<br />[output.svgDefaultExport](/configure/app/output/svg-default-export)     |
 | [Assets Retry Plugin](https://github.com/rstackjs/rsbuild-plugin-assets-retry)          | Automatically retries requests when static asset loading fails                                                                                  | [output.assetsRetry](/configure/app/output/assets-retry.html)                                                                         |
-| [Type Check Plugin](https://github.com/rspack-contrib/rsbuild-plugin-type-check)       | Runs TypeScript type checking in a separate process                                                                                             | [output.disableTsChecker](/configure/app/output/disable-ts-checker.html)<br />[tools.tsChecker](/configure/app/tools/ts-checker.html) |
-| [Source Build Plugin](https://github.com/rspack-contrib/rsbuild-plugin-source-build)   | For monorepo scenarios, supports referencing source code from other subdirectories and completing builds and hot updates                        | [experiments.sourceBuild](/configure/app/experiments/source-build.html)                                                               |
-| [Check Syntax Plugin](https://github.com/rspack-contrib/rsbuild-plugin-check-syntax)   | Analyzes the syntax compatibility of the build artifacts to determine if there are any advanced syntax features that cause compatibility issues | [security.checkSyntax](/configure/app/security/check-syntax.html)                                                                     |
-| [CSS Minimizer Plugin](https://github.com/rspack-contrib/rsbuild-plugin-css-minimizer) | Used to customize the CSS compression tool, switch to [cssnano](https://cssnano.co/) or other tools for CSS compression                         | [tools.minifyCss](/configure/app/tools/minify-css.html)                                                                               |
-| [Rem Plugin](https://github.com/rspack-contrib/rsbuild-plugin-rem)                     | Implements rem adaptive layout for mobile pages                                                                                                 | [output.convertToRem](/configure/app/output/convert-to-rem.html)                                                                      |
+| [Type Check Plugin](https://github.com/rstackjs/rsbuild-plugin-type-check)             | Runs TypeScript type checking in a separate process                                                                                             | [output.disableTsChecker](/configure/app/output/disable-ts-checker.html)<br />[tools.tsChecker](/configure/app/tools/ts-checker.html) |
+| [Source Build Plugin](https://github.com/rstackjs/rsbuild-plugin-source-build)   | For monorepo scenarios, supports referencing source code from other subdirectories and completing builds and hot updates                        | [experiments.sourceBuild](/configure/app/experiments/source-build.html)                                                               |
+| [Check Syntax Plugin](https://github.com/rstackjs/rsbuild-plugin-check-syntax)   | Analyzes the syntax compatibility of the build artifacts to determine if there are any advanced syntax features that cause compatibility issues | [security.checkSyntax](/configure/app/security/check-syntax.html)                                                                     |
+| [CSS Minimizer Plugin](https://github.com/rstackjs/rsbuild-plugin-css-minimizer) | Used to customize the CSS compression tool, switch to [cssnano](https://cssnano.co/) or other tools for CSS compression                         | [tools.minifyCss](/configure/app/tools/minify-css.html)                                                                               |
+| [Rem Plugin](https://github.com/rstackjs/rsbuild-plugin-rem)                     | Implements rem adaptive layout for mobile pages                                                                                                 | [output.convertToRem](/configure/app/output/convert-to-rem.html)                                                                      |
 
 #### Plugins Not Built-in
 
 The following are official Rsbuild plugins that are not built into Modern.js:
 
-- [Image Compress Plugin](https://github.com/rspack-contrib/rsbuild-plugin-image-compress): Compresses image resources used in the project.
+- [Image Compress Plugin](https://github.com/rstackjs/rsbuild-plugin-image-compress): Compresses image resources used in the project.
 - [Stylus Plugin](https://v2.rsbuild.rs/plugins/list/plugin-stylus): Uses Stylus as the CSS preprocessor.
-- [UMD Plugin](https://github.com/rspack-contrib/rsbuild-plugin-umd): Used to build UMD format artifacts.
-- [YAML Plugin](https://github.com/rspack-contrib/rsbuild-plugin-yaml): Used to reference YAML files and convert them to JavaScript objects.
-- [TOML Plugin](https://github.com/rspack-contrib/rsbuild-plugin-toml): Used to reference TOML files and convert them to JavaScript objects.
+- [UMD Plugin](https://github.com/rstackjs/rsbuild-plugin-umd): Used to build UMD format artifacts.
+- [YAML Plugin](https://github.com/rstackjs/rsbuild-plugin-yaml): Used to reference YAML files and convert them to JavaScript objects.
+- [TOML Plugin](https://github.com/rstackjs/rsbuild-plugin-toml): Used to reference TOML files and convert them to JavaScript objects.
 
 import OtherPlugins from '@site-docs-en/components/other-plugins.mdx';
 

package/docs/zh/community/blog/v3-release-note.mdx

@@ -591,7 +591,7 @@ Modern.js 3.0 新项目默认使用 React 19，最低支持 React 18。
 
 #### Storybook Rsbuild
 
-在 Modern.js 3.0 中，我们基于 [Storybook Rsbuild](https://github.com/rspack-contrib/storybook-rsbuild) 实现了使用 Storybook 构建 Modern.js 应用。
+在 Modern.js 3.0 中，我们基于 [Storybook Rsbuild](https://github.com/rstackjs/storybook-rsbuild) 实现了使用 Storybook 构建 Modern.js 应用。
 
 通过 Storybook Addon，我们将 Modern.js 配置转换合并为 Rsbuild 配置，并通过 Storybook Rsbuild 驱动构建，让 Storybook 调试与开发命令保持配置对齐。
 

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

@@ -9,6 +9,7 @@ title: effect
 ```ts
 type BffEffectUserConfig = {
   entry?: string;
+  strictEffectApproach?: true;
   openapi?: boolean | { path?: string };
   dataPlatform?: {
     enabled?: boolean;
@@ -44,6 +45,12 @@ import EnableBFFCaution from "@site-docs/components/enable-bff-caution";
 
 仅当 `bff.runtimeFramework` 设置为 `'effect'` 时，`bff.effect` 才会生效。
 
+生成的 UltraModern workspace 只把这个运行时作为生成 HTTP API 路径。API 契约固定在
+`shared/api.ts`，服务端运行时固定在 `api/index.ts`，客户端固定在
+`src/api/*-client.ts`。生成检查会拒绝 `api/effect`、`api/lambda`、
+`shared/effect`、`src/effect`、Hono server import、原始 request handler、手写
+request parsing，以及 API 模块里的手写 `Response`。
+
 对于 Effect v4，TypeScript 需要使用支持 `exports` 映射的模块解析方式。
 
 ```json title="tsconfig.json"
@@ -58,7 +65,7 @@ import EnableBFFCaution from "@site-docs/components/enable-bff-caution";
 ## bff.effect.entry
 
 - **类型：** `string`
-- **默认值：** `<apiDirectory>/effect/index`
+- **默认值：** `<apiDirectory>/index`
 
 用于指定 Effect HttpApi 运行时入口模块。
 
@@ -67,12 +74,22 @@ export default defineConfig({
   bff: {
     runtimeFramework: 'effect',
     effect: {
-      entry: './api/effect/index',
+      entry: './api/index',
     },
   },
 });
 ```
 
+## bff.effect.strictEffectApproach
+
+- **类型：** `true`
+- **默认值：** `true`
+
+Effect BFF 模块必须导出严格 Effect API surface（`defineEffectBff(...)` 或
+`{ api, layer }`），原始 request handler 会被拒绝。生成的 UltraModern 应用会显式
+写入这个标记，并通过源码检查拒绝生成 API 模块中的 Hono server import、手写
+request parsing 和手写 `Response`。
+
 ## bff.effect.openapi
 
 - **类型：** `boolean | { path?: string }`
@@ -173,4 +190,93 @@ export default defineConfig({
 
 `batch.flushIntervalMs` 用于控制生成的 Effect 客户端微批处理窗口；`maxConcurrency` 与 `requestTimeoutMs` 由服务端批处理网关用于内部请求分发。
 
-生成的 `effectBff.client.*` API 只存在于 loader 物化后的 `@api/effect/*` 导入中。直接导入服务端入口（`api/effect/index`）时拿到的是 Effect BFF 定义；其中的 `client` 属性只是占位，并会在访问具体操作时报错。
+生成的 `api.client.*` API 只存在于 loader 物化后的 `@api/index` 导入中。直接导入服务端入口（`api/index`）时拿到的是 Effect BFF 定义；其中的 `client` 属性只是占位，并会在访问具体操作时报错。
+
+## Effect 版本组
+
+UltraModern 生成的 workspace 会通过 `pnpm-workspace.yaml` overrides 锁定与框架兼容的
+Effect 版本组。`3.5.0-ultramodern.1` 使用：
+
+```yaml
+overrides:
+  '@effect/vitest': 4.0.0-beta.89
+  effect: 4.0.0-beta.89
+```
+
+不要在应用包里添加不同版本的直接 `effect` 依赖。Effect beta 不一致时，Layer 或 HTTP
+middleware 构建可能因为运行时 service 来自不同包实例而失败。
+
+## 契约测试
+
+严格 Effect API 测试应当测试声明的 `HttpApi` 契约，而不是原始 request handler。
+Edge 兼容测试可以使用框架 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'));
+```
+
+如果低层 proof 必须手动组合 web handler，需要在调用 `HttpRouter.toWebHandler` 前提供
+`HttpServer.layerServices`：
+
+```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;
+```
+
+优先使用生成 helper，除非测试必须检查底层 Effect router 组合。
+
+## 动态 CORS
+
+需要动态 origin predicate 时，使用 Effect HTTP middleware 作为 Layer。在当前锁定的
+Effect v4 beta 版本组中，`HttpRouter.middleware(...)` 直接返回 `Layer`：
+
+```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),
+);
+```
+
+不要从 `HttpRouter.middleware(...)` 读取 `.layer` 属性。
+
+## 其他传输
+
+`strictEffectApproach` 约束生成的 HTTP API 模块。Effect RPC、WebSocket 和其他传输在
+建模为显式传输 surface、并使用类型化 Effect 程序时仍然有效。它们不让生成的
+UltraModern API 模块中的原始 HTTP request handler 变得有效。

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

@@ -21,8 +21,10 @@ export default defineConfig({
 });
 ```
 
-- 设置为 `'effect'` 时，仅从 `api/effect/index` 运行 BFF（Effect HttpApi 运行时）。
+- 设置为 `'effect'` 时，仅从 `api/index` 运行 BFF（Effect HttpApi 运行时）。
 - 设置为 `'hono'` 时，仅从 `api/lambda/**` 的文件约定处理函数运行 BFF。
 
 两种运行时之间没有隐式回退，应用需要显式选择其一。
-生成的 UltraModern 应用默认使用 Effect 分支；仅在需要兼容运行时时设置 `runtimeFramework: 'hono'`。
+生成的 UltraModern 应用默认使用严格 Effect API，并设置
+`bff.effect.strictEffectApproach: true`；`hono` 与 `api/lambda/**` 不是生成
+UltraModern HTTP API 的有效路径。

package/docs/zh/configure/app/experiments/source-build.mdx

@@ -21,7 +21,7 @@ export default {
 
 ### 选项
 
-`experiments.sourceBuild` 底层基于 [@rsbuild/plugin-source-build](https://github.com/rspack-contrib/rsbuild-plugin-source-build?tab=readme-ov-file#options) 实现，你可以传入插件选项，比如：
+`experiments.sourceBuild` 底层基于 [@rsbuild/plugin-source-build](https://github.com/rstackjs/rsbuild-plugin-source-build?tab=readme-ov-file#options) 实现，你可以传入插件选项，比如：
 
 ```ts
 export default {

package/docs/zh/configure/app/html/template-parameters.mdx

@@ -30,7 +30,7 @@ type DefaultParameters = {
 };
 ```
 
-定义 HTML 模板中的参数，对应 [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) 的 `templateParameters` 配置项。
+定义 HTML 模板中的参数，对应 [html-rspack-plugin](https://github.com/rstackjs/html-rspack-plugin) 的 `templateParameters` 配置项。
 
 import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
 

package/docs/zh/configure/app/output/convert-to-rem.mdx

@@ -80,5 +80,5 @@ export default {
 };
 ```
 
-详细用法可参考 [rsbuild-plugin-rem](https://github.com/rspack-contrib/rsbuild-plugin-rem)。
+详细用法可参考 [rsbuild-plugin-rem](https://github.com/rstackjs/rsbuild-plugin-rem)。
 

package/docs/zh/configure/app/security/check-syntax.mdx

@@ -70,4 +70,4 @@ error   [Syntax Checker] Find some syntax errors after production build:
 
 ### 选项
 
-`security.checkSyntax` 底层基于 `@rsbuild/plugin-check-syntax` 实现，具体选项可参考 [@rsbuild/plugin-check-syntax](https://github.com/rspack-contrib/rsbuild-plugin-check-syntax)。
+`security.checkSyntax` 底层基于 `@rsbuild/plugin-check-syntax` 实现，具体选项可参考 [@rsbuild/plugin-check-syntax](https://github.com/rstackjs/rsbuild-plugin-check-syntax)。

package/docs/zh/configure/app/tools/html-plugin.mdx

@@ -38,7 +38,7 @@ const defaultOptions = {
 SSR 应用请勿启用 `minify.removeComments` 配置项，否则会导致 SSR 渲染失败。
 :::
 
-通过 `tools.htmlPlugin` 可以修改 [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) 的配置项。
+通过 `tools.htmlPlugin` 可以修改 [html-rspack-plugin](https://github.com/rstackjs/html-rspack-plugin) 的配置项。
 
 import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
 

package/docs/zh/configure/app/tools/ts-checker.mdx

@@ -43,6 +43,8 @@ const defaultOptions = {
 
 ## 示例
 
+### Object 类型
+
 当 `tsChecker` 的值为 Object 类型时，会与默认配置进行深层合并。
 
 ```ts
@@ -57,6 +59,23 @@ export default {
 };
 ```
 
+### Function 类型
+
+当 `tsChecker` 的值为函数时，默认配置会作为第一个参数传入。你可以直接修改配置对象，也可以返回一个对象作为最终配置。
+
+```ts
+export default {
+  tools: {
+    tsChecker(options) {
+      options.async = false;
+      return options;
+    },
+  },
+};
+```
+
+> 更多详情请参考 [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check)。
+
 ## TypeScript Go 默认开启
 
 类型检查默认使用 [TypeScript Go](https://github.com/microsoft/typescript-go)（`tsgo`）。该能力由 [`@rsbuild/plugin-type-check`](https://github.com/rstackjs/rsbuild-plugin-type-check) 底层集成的 [`ts-checker-rspack-plugin`](https://github.com/rstackjs/ts-checker-rspack-plugin) 提供，可以将类型检查耗时减少约 5-10 倍。

package/docs/zh/guides/advanced-features/bff/data-platform.mdx

@@ -59,9 +59,9 @@ Envelope 校验默认开启，但只有设置 `requireEnvelope` 时才强制要
 
 ## Effect 客户端自动行为
 
-使用生成的 Effect 客户端（`@api/effect/index`）时，Modern.js 会在同源请求中自动附加序列化的 envelope 请求头（`x-modernjs-data-envelope`）。
+使用生成的 Effect 客户端（`@api/index`）时，Modern.js 会在同源请求中自动附加序列化的 envelope 请求头（`x-modernjs-data-envelope`）。
 
-生成客户端由 loader 物化。请在浏览器或会被客户端打包的代码中通过 `@api/effect/*` 导入；直接导入服务端入口（`api/effect/index`）时拿到的是 Effect BFF 定义，其中只包含占位的 `client`。
+生成客户端由 loader 物化。请在浏览器或会被客户端打包的代码中通过 `@api/index` 导入；直接导入服务端入口（`api/index`）时拿到的是 Effect BFF 定义，其中只包含占位的 `client`。
 
 Envelope 默认包含：
 

package/docs/zh/guides/advanced-features/bff/frameworks.mdx

@@ -7,11 +7,19 @@ title: 运行时框架
 
 Modern.js 目前支持两种 BFF 运行时框架：
 
-- `effect`（默认）：使用 `api/effect/index` 的 [Effect HttpApi](https://effect.website/) 运行时。
+- `effect`（默认）：使用 `api/index` 的 [Effect HttpApi](https://effect.website/) 运行时。
 - `hono`：使用 `api/lambda/**` 的文件约定 BFF 处理函数。
 
 `effect` 与 `hono` 为严格模式，两者之间不会自动回退。
 
+::::info
+本页记录通用 Modern.js 运行时能力。生成的 UltraModern workspace 始终使用
+`effect` 运行时，并设置 `bff.effect.strictEffectApproach: true`。新增或修改生成的
+UltraModern HTTP API 时，先改 `shared/api.ts`，再改 `api/index.ts`；不要在这些
+workspace 中加入 Hono/file-convention handler、原始 request parsing 或手写
+`Response`。
+::::
+
 ## 切换到 Effect 运行时
 
 ```ts title="modern.config.ts"
@@ -23,6 +31,8 @@ export default defineConfig({
   bff: {
     runtimeFramework: 'effect',
     effect: {
+      entry: './api/index',
+      strictEffectApproach: true,
       openapi: {
         path: '/openapi.json',
       },
@@ -33,7 +43,7 @@ export default defineConfig({
 
 先在共享目录中定义 Effect HttpApi 契约（前后端共享类型）：
 
-```ts title="shared/effect/api.ts"
+```ts title="shared/api.ts"
 import {
   HttpApi,
   HttpApiEndpoint,
@@ -41,18 +51,18 @@ import {
   Schema,
 } from '@modern-js/plugin-bff/effect-client';
 
-export const bffEffectApi = HttpApi.make('MyApi').add(
+export const bffApi = HttpApi.make('MyApi').add(
   HttpApiGroup.make('hello').add(
-    HttpApiEndpoint.get('ping', '/effect/ping', {
+    HttpApiEndpoint.get('ping', '/ping', {
       success: Schema.String,
     }),
   ),
 );
 ```
 
-然后在 `api/effect/index.ts` 中实现 Effect BFF 入口：
+然后在 `api/index.ts` 中实现 Effect BFF 入口：
 
-```ts title="api/effect/index.ts"
+```ts title="api/index.ts"
 import {
   Schema,
   Effect,
@@ -61,7 +71,7 @@ import {
   Layer,
   ServiceMap,
 } from '@modern-js/plugin-bff/effect-server';
-import { bffEffectApi } from '../../shared/effect/api';
+import { bffApi } from '../shared/api';
 
 class GreetingUnavailableError extends Schema.TaggedError<GreetingUnavailableError>()(
   'GreetingUnavailableError',
@@ -87,7 +97,7 @@ class GreetingService extends ServiceMap.Service<GreetingService>()('GreetingSer
   static readonly layer = Layer.effect(this, this.make);
 }
 
-const group = HttpApiBuilder.group(bffEffectApi, 'hello', handlers =>
+const group = HttpApiBuilder.group(bffApi, 'hello', handlers =>
   handlers.handle('ping', () =>
     GreetingService.use(service => service.hello()).pipe(
       Effect.catchTag('GreetingUnavailableError', error =>
@@ -97,23 +107,23 @@ const group = HttpApiBuilder.group(bffEffectApi, 'hello', handlers =>
   ),
 );
 
-const layer = HttpApiBuilder.layer(bffEffectApi).pipe(
+const layer = HttpApiBuilder.layer(bffApi).pipe(
   Layer.provide(group),
   Layer.provide(GreetingService.layer),
 );
 
-export default defineEffectBff({ api: bffEffectApi, layer });
+export default defineEffectBff({ api: bffApi, layer });
 ```
 
-在浏览器代码中通过 `@api/effect/index` 调用接口：
+在浏览器代码中通过 `@api/index` 调用接口：
 
 ```ts title="src/routes/page.tsx"
-import effectBff from '@api/effect/index';
+import api from '@api/index';
 
-const response = await effectBff.client.hello.ping({});
+const response = await api.client.hello.ping({});
 ```
 
-`effectBff.client.*` 由 BFF loader 针对 `@api/effect/*` 导入物化生成。不要直接导入 `api/effect/index` 并期望在服务端代码、脚本或测试中运行 `client`；直接导入入口时拿到的是服务端运行时定义，其中的 `client` 只是类型占位。
+`api.client.*` 由 BFF loader 针对 `@api/index` 导入物化生成。不要直接导入 `api/index` 并期望在服务端代码、脚本或测试中运行 `client`；直接导入入口时拿到的是服务端运行时定义，其中的 `client` 只是类型占位。
 
 import Hono from '@site-docs/components/hono';