@bleedingdev/modern-js-main-doc 3.9.0-ultramodern.1 → 3.9.0-ultramodern.11

package/docs/en/components/hono.mdx

@@ -21,7 +21,7 @@ For more details, refer to [useHonoContext](/apis/app/runtime/bff/use-backend-co
 When getting cookies in BFF functions, you need to get the request context through `useHonoContext`, then use `c.req.header('cookie')` to get the Cookie string and parse it manually:
 
 ```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';
 
 // Helper function to parse Cookie string
@@ -64,7 +64,7 @@ The `c.req.cookie()` method does not exist in the current version. You need to u
 When using Hono as the runtime framework, you can define interfaces through [Api functions](/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 @@ For more details about Api functions and operators, refer to [Creating Extensibl
 Hono supports a rich middleware ecosystem, and you can use middleware in BFF functions:
 
 ```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/en/components/init-app.mdx

@@ -71,11 +71,7 @@ Now, the project structure is as follows:
 ```
 
 The default workspace starts shell-only and installs the published BleedingDev
-package aliases:
-
-```bash
-pnpm dlx @bleedingdev/modern-js-ultramodern-create my-super-app
-```
+package aliases.
 
 From a generated SuperApp workspace, add a business MicroVertical in place:
 

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

@@ -47,21 +47,33 @@ import EnableBFFCaution from "@site-docs-en/components/enable-bff-caution";
 
 :::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:
+`@modern-js/bff-effect`. Install them in the application so its API modules and
+the framework use the same Effect instance. Before setting
+`runtimeFramework: 'effect'` or importing `@modern-js/bff-effect/effect`,
+`/effect-edge` or `/effect-client`, install the exact cohort:
 
 ```bash
 pnpm add effect@4.0.0-rc.112 @effect/opentelemetry@4.0.0-rc.112
 ```
 
 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.
+using only native `runtimeFramework: 'hono'` or
+`@modern-js/bff-effect/data-platform` need neither package.
 :::
 
+Use `bffPlugin` from `@modern-js/plugin-bff-build-extensions` to register the
+Effect runtime. It composes the native BFF plugin. Install
+`@modern-js/bff-effect` and `@modern-js/plugin-bff-extensions` from the same
+framework cohort as application production dependencies, so the adapter remains
+available after development dependencies are removed. The build plugin can be a
+development dependency. See the [runtime configuration example](/guides/advanced-features/bff/frameworks).
+
+Native `@modern-js/plugin-bff/server` exports Hono APIs. For Node Effect APIs,
+import framework helpers such as `defineEffectBff` from
+`@modern-js/bff-effect/effect` and namespaces from the corresponding `effect/*`
+modules. Worker handlers and worker request context use
+`@modern-js/bff-effect/effect-edge`.
+
 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
@@ -173,7 +185,6 @@ export default defineConfig({
     endpoint: '/_data/batch',
     maxBatchSize: 16,
     maxBatchBytes: 64 * 1024,
-    flushIntervalMs: 8,
     maxConcurrency: 4,
     requestTimeoutMs: 10000,
     allowedMethods: ['GET'],
@@ -207,9 +218,9 @@ export default defineConfig({
 });
 ```
 
-`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.
+`maxConcurrency` and `requestTimeoutMs` control the server batch gateway. Native `HttpApiClient` calls send individual requests; they do not automatically batch requests.
 
-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.
+Import a shared `HttpApi` contract and pass it to `HttpApiClient.make` or `makeEffectHttpApiClient`. The client is fully type-inferred; `defineEffectBff` exposes server handlers and does not contain a client.
 
 ## Effect cohort
 
@@ -244,7 +255,7 @@ 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 { createEffectBffTestHandler } from '@modern-js/bff-effect/effect-edge';
 import apiModule from '../api/index';
 
 const testApi = await createEffectBffTestHandler({
@@ -259,12 +270,9 @@ 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';
+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(
@@ -284,13 +292,10 @@ 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';
+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/en/guides/advanced-features/bff/data-platform.mdx

@@ -17,7 +17,7 @@ Modern.js Effect API runtime now supports a request-envelope based data platform
 
 ## Runtime contract helpers
 
-Use `@modern-js/plugin-bff/data-platform` helpers to build and validate contracts:
+Use `@modern-js/bff-effect/data-platform` helpers to build and validate contracts:
 
 ```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 runtime validation

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

@@ -5,10 +5,10 @@ title: Runtime Framework
 
 # Runtime Framework
 
-Modern.js supports two BFF runtime frameworks:
+Modern.js and the UltraModern BFF extension provide two runtime frameworks:
 
-- `effect` (default): use [Effect HttpApi](https://effect.website/) runtime from `api/index`.
-- `hono`: use file-convention BFF handlers from `api/lambda/**`.
+- `hono` is the native plugin default and uses file-convention handlers from `api/lambda/**`.
+- `effect` is the UltraModern extension default and uses [Effect HttpApi](https://effect.website/) from `api/index`.
 
 `effect` and `hono` are strict runtime modes. There is no automatic fallback between them.
 
@@ -19,12 +19,18 @@ Generated UltraModern workspaces use strict Effect APIs: author HTTP APIs in
 
 ## Switch to Effect runtime
 
+Use the fork build plugin below. It includes the native BFF plugin and registers
+the Effect adapter. The application needs `@modern-js/bff-effect` and
+`@modern-js/plugin-bff-extensions` as production dependencies from the same
+framework cohort. Install the exact Effect peers described in
+[`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: {
@@ -46,7 +52,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(
@@ -60,14 +66,12 @@ export const bffApi = HttpApi.make('MyApi').add(
 Implement your Effect API entry at `api/index.ts`:
 
 ```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>()(
@@ -77,7 +81,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) {
@@ -112,19 +116,27 @@ const layer = HttpApiBuilder.layer(bffApi).pipe(
 export default defineEffectBff({ api: bffApi, layer });
 ```
 
-Call Effect endpoints from browser code via `@api/index`:
+Create a native, fully inferred client from the shared contract:
 
 ```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({})),
+  ),
+);
 ```
 
-The `api.client.*` surface is materialized by the BFF loader for `@api/index` imports. Do not import `api/index` directly and expect `client` to run in server code, scripts, or tests; direct entry imports expose the server runtime definition, and `client` is only a typed placeholder there.
+Requests, responses, and declared errors are inferred from `bffApi`. No client generation or server-entry import is needed.
 
 For UltraModern, Effect `HttpApi` plus Effect BFF is the single blessed authored HTTP path. Use `HttpApi` endpoints with `query`, `params`, `payload`, `success`, and declared errors such as `HttpApiSchema.status(...)`; implement them with `HttpApiBuilder.group(...).handle(...)` and `HttpApiBuilder.layer(...).pipe(Layer.provide(...))`, then default-export the entry as `defineEffectBff({ api, layer })`. See `packages/server/bff-effect/tests/effect-edge-runtime.test.ts` for the live runtime shape.
 
-Hono and `api/lambda/**` are internal compatibility only and feature-frozen.
+Native Hono applications import operators from `@modern-js/plugin-bff/server`.
+UltraModern-generated applications keep their strict Effect API model. Worker
+handlers use `@modern-js/bff-effect/effect-edge`, including its worker request
+context exports; Node handlers use the Effect entry shown above.
 
 import Hono from '@site-docs-en/components/hono';
 

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

@@ -191,7 +191,7 @@ Parameters following the dynamic path are an object called `RequestOption`, whic
 In a standard function without dynamic routes, `RequestOption` can be obtained from the first parameter, for example:
 
 ```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,
@@ -204,7 +204,7 @@ export async function post({
 Custom types can also be used here:
 
 ```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/en/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 @@ As shown in the example below, you can specify the route and HTTP Method through
 <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';
 
 // Specify the interface route, Modern.js sets `bff.prefix` to `/api` by default,
 // so the interface route is `/api/user`, and the HTTP Method is GET.
@@ -107,7 +107,7 @@ When the route is not specified, the interface route is defined according to the
 <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';
 
 // No interface route specified, according to file convention and function name, the interface is api/user, HTTP Method is get.
 export const get = Api(Query(UserSchema), async ({ query }) => query);
@@ -144,7 +144,7 @@ Using the `Query` function, you can define the type of query. After using the `Q
 
 ```typescript title="api/lambda/user.ts"
 // Server-side code
-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 parameters are strings by default. If you need numeric types, you need
 <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 @@ If you use the Data function, you must follow the HTTP protocol. When the HTTP M
 <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 @@ Route parameters can implement dynamic routes and get parameters from the path.
 <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 @@ You can define the request headers required by the interface through the `Header
 <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 @@ The `Middleware` operator can be configured multiple times, and the execution or
 <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 @@ The `Pipe` operator can be configured multiple times. The execution order of fun
 <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 @@ Also,
 <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 @@ If you need to do more custom operations on the response, you can pass a functio
 <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 @@ You can specify the status code returned by the interface through the `HttpCode(
 <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 @@ Supports setting response headers through the `SetHeaders(headers: Record<string
 <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 @@ Supports redirecting the interface through `Redirect(url: string)`:
 <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 @@ As mentioned above, through operators, you can get `query`, `data`, `params`, et
 <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 @@ In frontend development, some server interfaces (such as some configuration inte
 <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(
   // Cache will only take effect when using integrated calls or fetch for requests

package/docs/en/guides/basic-features/render/ssr-cache.mdx

@@ -35,7 +35,7 @@ export interface CacheControl {
 }
 ```
 
-Here, `customKey` is the custom cache key. By default, Modern.js uses the request `pathname` as the cache key, but developers can define it when necessary.
+Here, `customKey` is the custom cache key. By default, the cache key is derived from the request's origin, normalized pathname (trailing slash removed), and query string. When `customKey` is set, it fully replaces the default key: the `customKey` callback receives the normalized pathname (not the `CacheOptionProvider`'s `req`) and is responsible for the whole partition (e.g. by tenant, host, or query) — it must not embed raw cookies or other credentials into the returned key.
 
 **Function Type**
 
@@ -106,6 +106,19 @@ export const cacheOption: CacheOption = {
 
 The above `/home` and `/about` are patterns, meaning `/home/abc` will also match. You can use regex in these patterns, such as `/home/.+`.
 
+### Cache Policy
+
+The following policy is enforced automatically and cannot be overridden by the returned `CacheControl`:
+
+- Only `GET` requests are cached.
+- A request carrying a `Cookie` or `Authorization` header skips the cache unless `customKey` is set, since a custom key is treated as an explicit partitioning contract.
+- A request with `Cache-Control: private`, `no-cache`, or `no-store` skips the cache.
+- A response is only stored when it is `200`, has no `private`/`no-cache`/`no-store` in `Cache-Control`, has no `Set-Cookie`, and has no nonempty `Vary` header; otherwise any existing cache entry for that key is deleted instead of being written.
+- If a `stale` revalidation produces a response that is no longer cacheable (for example, it became per-user), that already-served stale response is unaffected, but the cache entry is evicted so subsequent requests no longer hit it.
+- A `CacheOptionProvider` returning `false` still disables caching entirely for that request, independent of the policy above.
+
+Cache keys are namespaced (`__ssr__cache:v2:...`). Older un-namespaced entries — including ones already stored in a custom `Container` — are never read back; they simply age out under the container's own eviction/TTL. There is no global cache flush.
+
 ### Cache Container
 
 By default, the server uses memory for caching. Typically, services are deployed in a Serverless container, creating a new process for each access, making it impossible to use the previous cache.

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,73 +58,12 @@ 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
@@ -160,12 +79,12 @@ metadata transition; they are not release-age approvals.
 | Surface | Pin |
 | --- | --- |
 | Effect runtime and test cohort | `effect`, `@effect/opentelemetry`, and `@effect/vitest`: `4.0.0-rc.112` |
-| Effect compiler | `@effect/tsgo@0.37.0` |
-| Oxc and Ultracite | `oxlint@1.80.0`, `oxfmt@0.65.0`, `ultracite@7.10.6` |
-| TanStack Router | `@tanstack/react-router@1.170.32`, `@tanstack/router-core@1.171.27`, `@tanstack/history@1.162.1` |
+| 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` |
 | Tailwind CSS | `tailwindcss@4.3.3` |
-| Node and package tooling | Node `26.7.0`, `@types/node@^26.2.0`, pnpm `11.24.0` |
+| Node and package tooling | Node `26.7.0`, `@types/node@^26.4.1`, pnpm `11.24.0` |
 
 Generated workspaces default to Module Federation bridge-react's router-free
 base entry (`bridge.enableBridgeRouter: false`), with TanStack Router as the
@@ -213,7 +132,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/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/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'),