@bleedingdev/modern-js-main-doc 3.9.0-ultramodern.2 → 3.9.0-ultramodern.20

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

@@ -18,17 +18,9 @@ UltraModern.js 3.0 is our SuperApp framework forked from Modern.js. It keeps the
 - Add platform-level contracts only where they improve cross-team reliability.
 - Keep escape hatches explicit and outside the generated HTTP API path.
 
-## Compatibility Contract
+## Current Workspace Contract
 
-UltraModern.js 3.0 keeps:
-
-- Modern.js app/config/plugin mental model.
-- 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. 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.
+UltraModern.js uses Effect HttpApi, TanStack Router, SSR, and independently deployable Micro Verticals. Generated workspaces use `api/index.ts`, `shared/api.ts`, and `src/api/*` with concrete Effect schemas. The CLI creates, adds to, and validates workspaces against the current contract.
 
 ## Intentional Differences (v3 line)
 
@@ -56,21 +48,9 @@ or migrated as UltraModern HTTP API, it must use the strict Effect HttpApi path.
 - 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 is to move API work onto the strict Effect HttpApi surface instead of preserving older raw handler layouts.
-
-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
-the source of truth:
+## Create and Validate a Workspace
 
 ```bash
-pnpm dlx @bleedingdev/modern-js-ultramodern-create@latest --help
-pnpm dlx @bleedingdev/modern-js-ultramodern-create@latest catalog --vertical --dry-run
 pnpm dlx @bleedingdev/modern-js-ultramodern-create@latest catalog --vertical
 mise install
 mise exec -- pnpm install
@@ -78,94 +58,31 @@ mise exec -- pnpm check
 mise exec -- pnpm build
 ```
 
-### Migrating localized Cloudflare SSR workspaces
-
-Current cohorts localize Cloudflare SSR workspaces.
-The framework moves bare locale-root redirects into the framework-owned
-Cloudflare Worker entry and the i18n server runtime. A request for `/` is
-redirected server-side with `302` to the negotiated locale path, for example
-`/cs` for `Accept-Language: cs-CZ` or `/en` for English and fallback traffic.
-
-Existing generated workspaces should upgrade the whole BleedingDev Modern
-package cohort together. Resolve the current cohort version first, then run
-the matching migration:
-
-```bash
-COHORT="$(npm view @bleedingdev/modern-js-ultramodern-create version)"
-pnpm dlx "@bleedingdev/modern-js-ultramodern-create@$COHORT" ultramodern \
-  migrate-strict-effect --version "$COHORT"
-pnpm install
-pnpm check
-pnpm build
-pnpm cloudflare:build
-```
-
-For deployed Cloudflare Workers, redeploy after the cohort update and verify
-the root response before accepting the migration:
+Localized Cloudflare SSR workspaces redirect `/` on the server to the negotiated locale. For example, `Accept-Language: cs-CZ` returns `302` with `Location: /cs`, `Cache-Control: private, no-store`, and `Vary` covering locale detection headers. Validate the deployed Worker with:
 
 ```bash
 curl -I -H 'Accept-Language: cs-CZ,cs;q=0.9,en;q=0.1' https://<worker-host>/
 ```
 
-The expected response is `302` with `Location: /cs` or the matching locale,
-`Cache-Control: private, no-store`, and `Vary` covering the locale detection
-headers. Following the redirect should return the SSR locale page with the
-matching document language and i18n SSR data.
-
-Do not fix older root `404` responses by adding app-owned root route files,
-client-side redirects, custom navigation wrappers, Cloudflare Worker
-postprocessing, generated output edits, or local redirect shims. If `/` still
-returns `404` after upgrading, confirm the production build log shows
-`Modern.js Framework v<cohort-version>` for the cohort you migrated to and
-redeploy the Worker.
-
-Strict generated API migration is part of every current cohort: the direct
-`api/index.ts` generator, generated `.mts` checks, the strict Oxlint boundary
-rule set, Effect cohort overrides, and the strict Effect migration command.
-Agents that cannot install the BleedingDev cohort yet should use the local
-Modern.js workspace for migration validation; otherwise pin the target cohort
-with `--ultramodern-package-version`.
-
-Before hand-editing package aliases or generated metadata, run the framework
-migration command from the target workspace:
-
-```bash
-COHORT="$(npm view @bleedingdev/modern-js-ultramodern-create version)"
-pnpm dlx "@bleedingdev/modern-js-ultramodern-create@$COHORT" ultramodern \
-  migrate-strict-effect --version "$COHORT"
-pnpm api:check
-pnpm contract:check
-```
-
-The command updates `.modernjs/ultramodern.json`, root
-`modernjs.packageSource`, generated Modern package aliases, framework-owned
-toolchain pins, direct topology API metadata, strict Effect pnpm
-overrides/trust policy, 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-rc.112`, `@effect/opentelemetry@4.0.0-rc.112`,
-and `@effect/vitest@4.0.0-rc.112`. Do not add app-local direct Effect
+overrides: `effect@4.0.0-rc.117`, `@effect/opentelemetry@4.0.0-rc.117`,
+and `@effect/vitest@4.0.0-rc.117`. Do not add app-local direct Effect
 versions that disagree with those overrides. The strict 24-hour release-age
 gate applies to installed packages; this cohort carries no Effect age
 exemption, and override-only `@effect/vitest` is not an installed approval
-target. Independently, exact `trustPolicyExclude` entries for `effect`
-and `@effect/opentelemetry` cover their trusted-publisher to provenance
-metadata transition; they are not release-age approvals.
+target.
 
 ### Current generated dependency baseline
 
 | Surface | Pin |
 | --- | --- |
-| Effect runtime and test cohort | `effect`, `@effect/opentelemetry`, and `@effect/vitest`: `4.0.0-rc.112` |
-| Effect compiler | `@effect/tsgo@0.41.0` |
-| Oxc and Ultracite | `oxlint@1.81.0`, `oxfmt@0.66.0`, `ultracite@7.11.0` |
-| TanStack Router | `@tanstack/react-router@1.170.33`, `@tanstack/router-core@1.171.28`, `@tanstack/history@1.162.2` |
-| Module Federation | `bridge-react`, `manifest`, `modern-js-v3`, and `rspack`: `2.9.0`; `@module-federation/node@2.7.50` |
+| Effect runtime and test cohort | `effect`, `@effect/opentelemetry`, and `@effect/vitest`: `4.0.0-rc.117` |
+| Effect compiler | `@effect/tsgo@0.45.0` |
+| Oxc and Ultracite | `oxlint@1.85.0`, `oxfmt@0.70.0`, `ultracite@7.12.0` |
+| TanStack Router | `@tanstack/react-router@1.170.39`, `@tanstack/router-core@1.171.32`, `@tanstack/history@1.162.4` |
+| Module Federation | `bridge-react`, `manifest`, `modern-js-v3`, and `rspack`: `2.9.2`; `@module-federation/node@2.7.52` |
 | Tailwind CSS | `tailwindcss@4.3.3` |
-| Node and package tooling | Node `26.7.0`, `@types/node@^26.4.1`, pnpm `11.24.0` |
+| Node and package tooling | Node `26.7.0`, `@types/node@^26.6.2`, pnpm `11.27.1` |
 
 Generated workspaces default to Module Federation bridge-react's router-free
 base entry (`bridge.enableBridgeRouter: false`), with TanStack Router as the
@@ -213,7 +130,7 @@ 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
+`createEffectBffTestHandler` from `@modern-js/bff-effect/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`.

package/docs/en/plugin/server-plugins/api.mdx

@@ -191,6 +191,7 @@ Adds additional logic when the server resets.
       - `'file-change'`: File change event
     - `event.payload`: When `type` is `'file-change'`, contains an array of file change information.
 - **Execution Phase:** When files change or repack is needed.
+- **Repack Order:** On `'repack'` the dev server awaits the handlers in registration order before it purges the previous server bundle from the require cache. A rejecting handler skips the handlers after it. New requests wait until the handlers settle; requests already running keep the modules they loaded. A repack handler must not await a request to the dev server, because that request waits for the handler.
 - **Example:**
 
 ```typescript

package/docs/zh/components/bff-operator-code.mdx

@@ -1,5 +1,5 @@
 import FrameworkCode from '@site/src/components/FrameworkCode';
 
-<FrameworkCode sourcePath="@modern-js/plugin-bff/hono-server">
+<FrameworkCode sourcePath="@modern-js/plugin-bff/server">
   {props.children}
 </FrameworkCode>

package/docs/zh/components/deploy-command.mdx

@@ -8,6 +8,7 @@ Usage: modern deploy [options]
 Options:
   -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
   -s --skip-build       跳过构建阶段
+  --deploy-target <target>  部署目标（node、vercel、netlify、ghPages、cloudflare），优先于 deploy.target 和 MODERNJS_DEPLOY
   -h, --help            显示命令帮助
 ```
 

package/docs/zh/components/hono.mdx

@@ -21,7 +21,7 @@ export const get = async () => {
 在 BFF 函数中获取 Cookie 时，需要通过 `useHonoContext` 获取请求上下文，然后使用 `c.req.header('cookie')` 获取 Cookie 字符串并手动解析：
 
 ```ts title="api/lambda/cookies.ts"
-import { Api, Get } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get } from '@modern-js/plugin-bff/server';
 import { useHonoContext } from '@modern-js/server-runtime';
 
 // 解析 Cookie 字符串的辅助函数
@@ -64,7 +64,7 @@ export const getCookies = Api(Get('/cookies'), async () => {
 使用 Hono 作为运行时框架时，可以通过 [Api 函数](/guides/advanced-features/bff/operators.html) 定义接口：
 
 ```ts title="api/lambda/user.ts"
-import { Api, Get, Query } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const QuerySchema = z.object({
@@ -93,7 +93,7 @@ export const getUser = Api(
 Hono 支持丰富的中间件生态，可以在 BFF 函数中使用中间件：
 
 ```ts title="api/lambda/user.ts"
-import { Api, Get, Middleware } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Middleware } from '@modern-js/plugin-bff/server';
 
 export const getUser = Api(
   Get('/user'),

package/docs/zh/components/prerequisites.mdx

@@ -9,7 +9,7 @@ import NodeVersion from '@site-docs/components/nodeVersion.mdx';
 推荐使用 [pnpm](https://pnpm.io/installation) 来管理依赖：
 
 ```bash
-mise use pnpm@11.24.0
+mise use pnpm@11.27.1
 ```
 
 :::note

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

@@ -46,20 +46,29 @@ import EnableBFFCaution from "@site-docs/components/enable-bff-caution";
 仅当 `bff.runtimeFramework` 设置为 `'effect'` 时，`bff.effect` 才会生效。
 
 :::caution 需要自行安装 Effect peer 依赖
-`effect` 与 `@effect/opentelemetry` 是 `@modern-js/plugin-bff` 的**可选精确 peer
-依赖**，而不是直接依赖。插件不再自带副本——Effect 4 的 `Context` / `Service` 键按模块
-实例生成，自带副本会让应用出现第二份 Effect 身份。在设置 `runtimeFramework: 'effect'`
-或引入 `@modern-js/plugin-bff/effect`、`/effect-server`、`/effect-edge`、
+`effect` 与 `@effect/opentelemetry` 是 `@modern-js/bff-effect` 的**可选精确 peer
+依赖**。应用必须安装这些依赖，让 API 模块与框架使用同一个 Effect 实例。在设置
+`runtimeFramework: 'effect'` 或引入 `@modern-js/bff-effect/effect`、`/effect-edge`、
 `/effect-client` 之前，请安装精确版本的依赖组：
 
 ```bash
-pnpm add effect@4.0.0-rc.112 @effect/opentelemetry@4.0.0-rc.112
+pnpm add effect@4.0.0-rc.117 @effect/opentelemetry@4.0.0-rc.117
 ```
 
 采用精确版本是因为 UltraModern 以锁步依赖组的方式发布 Effect。只使用
-`runtimeFramework: 'hono'` 或 `./data-platform` 通道的应用无需安装这两个包。
+原生 `runtimeFramework: 'hono'` 或 `@modern-js/bff-effect/data-platform` 的应用无需安装这两个包。
 :::
 
+使用 `@modern-js/plugin-bff-build-extensions` 导出的 `bffPlugin` 注册 Effect
+运行时，它会组合原生 BFF 插件。将同一框架版本组中的 `@modern-js/bff-effect` 和
+`@modern-js/plugin-bff-extensions` 安装为应用的生产依赖，保证移除开发依赖后仍能加载
+运行时适配器。构建插件可以作为开发依赖。参见[运行时配置示例](/guides/advanced-features/bff/frameworks)。
+
+原生 `@modern-js/plugin-bff/server` 导出 Hono API。Node Effect API 从
+`@modern-js/bff-effect/effect` 导入 `defineEffectBff` 等框架 helper，命名空间从对应的
+`effect/*` 模块导入。Worker handler 和 Worker 请求上下文使用
+`@modern-js/bff-effect/effect-edge`。
+
 生成的 UltraModern workspace 只把这个运行时作为生成 HTTP API 路径。API 契约固定在
 `shared/api.ts`，服务端运行时固定在 `api/index.ts`，客户端固定在
 `src/api/*-client.ts`。生成检查会拒绝 `api/effect`、`api/lambda`、
@@ -169,7 +178,6 @@ export default defineConfig({
     endpoint: '/_data/batch',
     maxBatchSize: 16,
     maxBatchBytes: 64 * 1024,
-    flushIntervalMs: 8,
     maxConcurrency: 4,
     requestTimeoutMs: 10000,
     allowedMethods: ['GET'],
@@ -203,9 +211,9 @@ export default defineConfig({
 });
 ```
 
-`batch.flushIntervalMs` 用于控制生成的 Effect 客户端微批处理窗口；`maxConcurrency` 与 `requestTimeoutMs` 由服务端批处理网关用于内部请求分发。
+`maxConcurrency` 与 `requestTimeoutMs` 控制服务端批处理网关。原生 `HttpApiClient` 发送独立请求，不会自动批处理。
 
-生成的 `api.client.*` API 只存在于 loader 物化后的 `@api/index` 导入中。直接导入服务端入口（`api/index`）时拿到的是 Effect BFF 定义；其中的 `client` 属性只是占位，并会在访问具体操作时报错。
+导入共享 `HttpApi` 契约并传给 `HttpApiClient.make` 或 `makeEffectHttpApiClient`，即可获得完全类型推导的客户端。`defineEffectBff` 只提供服务端 handler，不包含客户端。
 
 ## Effect 版本组
 
@@ -213,23 +221,16 @@ UltraModern 生成的 workspace 会通过 `pnpm-workspace.yaml` overrides 锁定
 Effect 版本组。当前 UltraModern 版本组使用：
 
 ```yaml
-trustPolicyExclude:
-  - 'effect@4.0.0-rc.112'
-  - '@effect/opentelemetry@4.0.0-rc.112'
-
 overrides:
-  '@effect/opentelemetry': 4.0.0-rc.112
-  '@effect/vitest': 4.0.0-rc.112
-  effect: 4.0.0-rc.112
+  '@effect/opentelemetry': 4.0.0-rc.117
+  '@effect/vitest': 4.0.0-rc.117
+  effect: 4.0.0-rc.117
 ```
 
 不要在应用包里添加不同版本的直接 `effect` 依赖。Effect 预发布版本不一致时，Layer 或 HTTP
 middleware 构建可能因为运行时 service 来自不同包实例而失败。严格的 24 小时发布年龄
 门禁适用于实际安装的包；当前版本组没有 Effect 年龄豁免，且仅用于 override 的
 `@effect/vitest` 不是已安装的审批目标。
-`trustPolicyExclude` 是另一项独立策略：其中精确的 `effect` 与
-`@effect/opentelemetry` 例外用于处理 trusted-publisher metadata 向 provenance
-attestation 的迁移，并不等同于 release-age 审批。
 
 ## 契约测试
 
@@ -237,7 +238,7 @@ attestation 的迁移，并不等同于 release-age 审批。
 Edge 兼容测试可以使用框架 helper：
 
 ```ts
-import { createEffectBffTestHandler } from '@modern-js/plugin-bff/effect-edge';
+import { createEffectBffTestHandler } from '@modern-js/bff-effect/effect-edge';
 import apiModule from '../api/index';
 
 const testApi = await createEffectBffTestHandler({
@@ -252,12 +253,9 @@ const response = await testApi.handler(new Request('http://localhost/api/ping'))
 `HttpServer.layerServices`：
 
 ```ts
-import {
-  HttpApiBuilder,
-  HttpRouter,
-  HttpServer,
-  Layer,
-} from '@modern-js/plugin-bff/effect-server';
+import * as Layer from 'effect/Layer';
+import { HttpRouter, HttpServer } from 'effect/unstable/http';
+import { HttpApiBuilder } from 'effect/unstable/httpapi';
 
 const handler = HttpRouter.toWebHandler(
   HttpApiBuilder.layer(api).pipe(
@@ -275,13 +273,10 @@ const handler = HttpRouter.toWebHandler(
 Effect v4 beta 版本组中，`HttpRouter.middleware(...)` 直接返回 `Layer`：
 
 ```ts
-import {
-  Effect,
-  HttpApiBuilder,
-  HttpMiddleware,
-  HttpRouter,
-  Layer,
-} from '@modern-js/plugin-bff/effect-server';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { HttpMiddleware, HttpRouter } from 'effect/unstable/http';
+import { HttpApiBuilder } from 'effect/unstable/httpapi';
 
 const corsLayer = HttpRouter.middleware(
   Effect.succeed(

package/docs/zh/configure/app/source/react-compiler.mdx

@@ -11,6 +11,8 @@ title: reactCompiler
 
 Modern.js 基于 Rspack `builtin:swc-loader` 内置的 Rust 版 React Compiler 实现该能力（等价于设置 SWC 的 `jsc.transform.reactCompiler`），复用 Rspack 内置的 SWC 转换链，无需额外引入 Babel。
 
+该编译仅作用于浏览器环境（`output.target: 'web'`）。服务端环境（`node`、`web-worker` SSR Worker 以及 BFF 代码）每次请求只渲染一次，无法从自动记忆化中获益，因此不会被编译。
+
 :::tip
 该配置默认关闭，任何 React 版本下都需要显式开启，包括 React 19。
 :::

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

@@ -17,7 +17,7 @@ Modern.js 的 Effect BFF 已支持基于请求信封（request envelope）的数
 
 ## 运行时契约工具
 
-可通过 `@modern-js/plugin-bff/data-platform` 使用以下能力：
+可通过 `@modern-js/bff-effect/data-platform` 使用以下能力：
 
 ```ts
 import {
@@ -30,7 +30,7 @@ import {
   validateHydrationEnvelope,
   createInvalidationEvent,
   shouldApplyInvalidation,
-} from '@modern-js/plugin-bff/data-platform';
+} from '@modern-js/bff-effect/data-platform';
 ```
 
 ## Effect 运行时校验

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

@@ -5,10 +5,10 @@ title: 运行时框架
 
 # 运行时框架
 
-Modern.js 目前支持两种 BFF 运行时框架：
+Modern.js 与 UltraModern BFF 扩展提供两种运行时框架：
 
-- `effect`（默认）：使用 `api/index` 的 [Effect HttpApi](https://effect.website/) 运行时。
-- `hono`：使用 `api/lambda/**` 的文件约定 BFF 处理函数。
+- `hono` 是原生插件的默认运行时，使用 `api/lambda/**` 的文件约定处理函数。
+- `effect` 是 UltraModern 扩展的默认运行时，使用 `api/index` 的 [Effect HttpApi](https://effect.website/) 运行时。
 
 `effect` 与 `hono` 为严格模式，两者之间不会自动回退。
 
@@ -22,12 +22,16 @@ workspace 中加入 Hono/file-convention handler、原始 request parsing 或手
 
 ## 切换到 Effect 运行时
 
+使用下面的 fork 构建插件，它会包含原生 BFF 插件并注册 Effect 适配器。应用需要将
+同一框架版本组中的 `@modern-js/bff-effect` 和 `@modern-js/plugin-bff-extensions`
+安装为生产依赖。Effect 的精确 peer 版本见 [`bff.effect`](/configure/app/bff/effect)。
+
 ```ts title="modern.config.ts"
-import { bffPlugin } from '@modern-js/plugin-bff';
-import { defineConfig } from '@modern-js/app-tools';
+import { bffPlugin } from '@modern-js/plugin-bff-build-extensions';
+import { appTools, defineConfig } from '@modern-js/app-tools';
 
 export default defineConfig({
-  plugins: [bffPlugin()],
+  plugins: [appTools(), bffPlugin()],
   bff: {
     runtimeFramework: 'effect',
     effect: {
@@ -49,7 +53,7 @@ import {
   HttpApiEndpoint,
   HttpApiGroup,
   Schema,
-} from '@modern-js/plugin-bff/effect-client';
+} from '@modern-js/bff-effect/effect-client';
 
 export const bffApi = HttpApi.make('MyApi').add(
   HttpApiGroup.make('hello').add(
@@ -63,14 +67,12 @@ export const bffApi = HttpApi.make('MyApi').add(
 然后在 `api/index.ts` 中实现 Effect BFF 入口：
 
 ```ts title="api/index.ts"
-import {
-  Schema,
-  Effect,
-  HttpApiBuilder,
-  defineEffectBff,
-  Layer,
-  ServiceMap,
-} from '@modern-js/plugin-bff/effect-server';
+import { defineEffectBff } from '@modern-js/bff-effect/effect';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Schema from 'effect/Schema';
+import { HttpApiBuilder } from 'effect/unstable/httpapi';
 import { bffApi } from '../shared/api';
 
 class GreetingUnavailableError extends Schema.TaggedError<GreetingUnavailableError>()(
@@ -80,7 +82,7 @@ class GreetingUnavailableError extends Schema.TaggedError<GreetingUnavailableErr
   },
 ) {}
 
-class GreetingService extends ServiceMap.Service<GreetingService>()('GreetingService', {
+class GreetingService extends Context.Service<GreetingService>()('GreetingService', {
   make: Effect.succeed({
     hello: Effect.fn('GreetingService.hello')(function* () {
       if (Date.now() < 0) {
@@ -115,15 +117,24 @@ const layer = HttpApiBuilder.layer(bffApi).pipe(
 export default defineEffectBff({ api: bffApi, layer });
 ```
 
-在浏览器代码中通过 `@api/index` 调用接口：
+从共享契约创建原生、完全类型推导的客户端：
 
 ```ts title="src/routes/page.tsx"
-import api from '@api/index';
+import { Effect, makeEffectHttpApiClient } from '@modern-js/bff-effect/effect-client';
+import { bffApi } from '../../shared/api';
 
-const response = await api.client.hello.ping({});
+const response = await Effect.runPromise(
+  makeEffectHttpApiClient(bffApi, { baseUrl: '/api' }).pipe(
+    Effect.flatMap(client => client.hello.ping({})),
+  ),
+);
 ```
 
-`api.client.*` 由 BFF loader 针对 `@api/index` 导入物化生成。不要直接导入 `api/index` 并期望在服务端代码、脚本或测试中运行 `client`；直接导入入口时拿到的是服务端运行时定义，其中的 `client` 只是类型占位。
+请求、响应和声明的错误类型均从 `bffApi` 推导，无需生成客户端代码或导入服务端入口。
+
+原生 Hono 应用从 `@modern-js/plugin-bff/server` 导入操作符。生成的 UltraModern
+应用继续使用严格 Effect API。Worker handler 及其请求上下文使用
+`@modern-js/bff-effect/effect-edge`；Node handler 使用上面示例中的 Effect 入口。
 
 import Hono from '@site-docs/components/hono';
 

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

@@ -188,7 +188,7 @@ Dynamic Path 之后的参数是包含 querystring、request body 的对象 `Requ
 在不存在动态路由的普通函数中，可以从第一个入参中获取传入的 `data` 和 `query`，例如：
 
 ```ts title="api/lambda/hello.ts"
-import type { RequestOption } from '@modern-js/plugin-bff/hono-server';
+import type { RequestOption } from '@modern-js/plugin-bff/server';
 
 export async function post({
   query,
@@ -201,7 +201,7 @@ export async function post({
 这里你也可以使用自定义类型：
 
 ```ts title="api/lambda/hello.ts"
-import type { RequestOption } from '@modern-js/plugin-bff/hono-server';
+import type { RequestOption } from '@modern-js/plugin-bff/server';
 
 type IQuery = {
   // some types

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

@@ -36,7 +36,7 @@ import BFFOperatorCode from '@site-docs/components/bff-operator-code';
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Post, Query, Data } from '@modern-js/plugin-bff/hono-server';
+import { Api, Post, Query, Data } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -89,7 +89,7 @@ addUser({
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Get, Query, Data } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query, Data } from '@modern-js/plugin-bff/server';
 
 // 指定接口路由，Modern.js 默认设置 `bff.prefix` 为 `/api`，
 // 因此该接口路由为 `/api/user`，Http Method 为 GET。
@@ -107,7 +107,7 @@ export const getHello = Api(
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Get, Query, Data } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query, Data } from '@modern-js/plugin-bff/server';
 
 // 未指定接口路由，根据文件约定和函数名，该接口为 api/user，Http Method 为 get。
 export const get = Api(Query(UserSchema), async ({ query }) => query);
@@ -144,7 +144,7 @@ Modern.js 推荐基于文件约定去定义接口，保持项目中路由清晰
 
 ```typescript title="api/lambda/user.ts"
 // 服务端代码
-import { Api, Query } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -176,7 +176,7 @@ URL query 参数默认是字符串类型，如果需要数字类型，需要使
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Get, Query } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const QuerySchema = z.object({
@@ -216,7 +216,7 @@ URL query 参数都是字符串类型，如果需要数字类型，需要使用
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Data } from '@modern-js/plugin-bff/hono-server';
+import { Api, Data } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const DataSchema = z.object({
@@ -249,7 +249,7 @@ post({
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Get, Params } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Params } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -274,7 +274,7 @@ export const queryUser = Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Headers } from '@modern-js/plugin-bff/hono-server';
+import { Api, Headers } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const headerSchema = z.object({
@@ -336,7 +336,7 @@ try {
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Middleware } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Middleware } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -376,7 +376,7 @@ export const get = Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Pipe } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Pipe } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -408,7 +408,7 @@ export const get = Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Pipe } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Pipe } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -443,7 +443,7 @@ export const get = Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Pipe } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Pipe } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -487,7 +487,7 @@ export const get = Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Data, HttpCode } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Data, HttpCode } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -523,7 +523,7 @@ export const post = Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Get, SetHeaders } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, SetHeaders } from '@modern-js/plugin-bff/server';
 
 export default Api(
   Get('/hello'),
@@ -543,7 +543,7 @@ export default Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Get, Redirect } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Redirect } from '@modern-js/plugin-bff/server';
 
 export default Api(
   Get('/hello'),
@@ -561,7 +561,7 @@ export default Api(
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Get, Query } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query } from '@modern-js/plugin-bff/server';
 import { useHonoContext } from '@modern-js/server-runtime';
 import { z } from 'zod';
 
@@ -610,7 +610,7 @@ export const queryUser = Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, SetHeaders } from '@modern-js/plugin-bff/hono-server';
+import { Api, SetHeaders } from '@modern-js/plugin-bff/server';
 
 export const get = Api(
   // 缓存使用一体化调用或者 fetch 进行请求才会生效