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

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

@@ -39,7 +39,7 @@ export interface CacheControl {
 }
 ```
 
-其中 `customKey` 为自定义缓存 key。默认情况下 Modern.js 将会把请求 `pathname` 作为 key 进行缓存，但在某些情况下这不能满足你的需求，开发者可以进行自定义。
+其中 `customKey` 为自定义缓存 key。默认情况下，缓存 key 由请求的 origin、归一化后的 pathname（去除末尾斜杠）以及 query 组成。当设置了 `customKey` 后，它会完全替代默认 key：`customKey` 回调函数接收的是归一化后的 pathname（而非 `CacheOptionProvider` 的 `req`），并需要自行负责整个分区（例如按租户、host 或 query 区分）——不能将原始 cookie 或其他凭证嵌入返回的 key 中。
 
 **Function 类型**
 
@@ -111,6 +111,19 @@ export const cacheOption: CacheOption = {
 
 上述 `/home` 和 `/about` 将会作为模式进行匹配，这意味着 `/home/abc` 也会匹配上该规则。同时，你也可以在其中编写正则语法：`/home/.+`
 
+### 缓存策略
+
+以下策略由框架自动执行，返回的 `CacheControl` 无法覆盖：
+
+- 只有 `GET` 请求会被缓存。
+- 请求携带 `Cookie` 或 `Authorization` 请求头时会跳过缓存，除非设置了 `customKey`（自定义 key 被视为一份明确的分区约定）。
+- 请求的 `Cache-Control` 为 `private`、`no-cache` 或 `no-store` 时会跳过缓存。
+- 只有当响应为 `200`、`Cache-Control` 中不含 `private`/`no-cache`/`no-store`、不含 `Set-Cookie`、也不含非空的 `Vary` 头时才会被写入缓存；否则会删除该 key 已有的缓存条目，而不是写入新的。
+- 当 `stale` 状态触发的重新渲染结果不再可缓存时（例如变为按用户区分），本次已返回的 stale 响应不受影响，但缓存条目会被清除，后续请求将不再命中该缓存。
+- `CacheOptionProvider` 返回 `false` 依然会完全禁用该请求的缓存，不受上述策略影响。
+
+缓存 key 带有命名空间（`__ssr__cache:v2:...`）。旧版本未加命名空间的缓存条目（包括自定义 `Container` 中已存储的条目）不会再被读取，只会依据容器自身的淘汰/TTL 机制自然过期；不存在全局缓存清空操作。
+
 ### 缓存容器
 
 默认情况下，Server 将会使用内存进行缓存。但通常情况下服务将会部署在 Serverless 容器上。每一次的服务访问可能都是一个新的进程，这样每次访问都不能应用缓存。

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

@@ -16,15 +16,11 @@ UltraModern.js 3.0 是我们从 Modern.js 分叉出来的 SuperApp 框架。它
 - 仅在跨团队稳定性场景增加平台契约。
 - 保留显式 escape hatch，但它们必须位于生成 HTTP API 模块之外。
 
-## 兼容性承诺
+## 当前 Workspace 契约
 
-UltraModern.js 3.0 保持以下不变：
-
-- Modern.js 的应用/配置/插件心智模型。
-- 既有项目结构与命令使用方式。
-- 渐进式接入路径（应用无需大规模重构）。
-
-UltraModern.js 的增强能力是新 SuperApp 的默认产品面。框架方向是 Effect + TanStack + SSR + Micro Verticals，生成的 HTTP API 只走严格 Effect HttpApi surface。既有 Modern.js 应用可以渐进迁移；一旦某个 API surface 被生成为或迁移为 UltraModern HTTP API，就必须使用严格 Effect HttpApi 路径。
+UltraModern.js 使用 Effect HttpApi、TanStack Router、SSR 和可独立部署的 Micro Verticals。
+生成的 workspace 使用 `api/index.ts`、`shared/api.ts`、`src/api/*` 和具体的 Effect schema。
+CLI 按当前契约创建、扩展和验证 workspace。
 
 ## 有意引入的差异（3.0 线）
 
@@ -50,20 +46,9 @@ UltraModern.js 的增强能力是新 SuperApp 的默认产品面。框架方向
 - 生成的 UltraModern HTTP API 只走严格 Effect HttpApi surface；原始 request handler 和 Hono/file-function API 不属于生成架构。
 - 除非稳定性硬需求，否则避免引入破坏性 API 变更。
 
-## 迁移指南
-
-对于已经在使用 Modern.js 3.0 或旧版 BleedingDev UltraModern scaffold 的团队，迁移路径是把 API 工作迁到严格 Effect HttpApi surface，而不是保留旧的原始 handler 布局。
-
-1. 既有 Modern.js 应用在尚未进入生成 UltraModern surface 前可以继续按现状运行。TanStack Router 是新脚手架与增量迁移的优先路径，团队可以按自己的节奏迁移路由层。
-2. 新建或迁移中的 BFF 能力使用 `bff.runtimeFramework: 'effect'`、`bff.effect.entry: './api/index'` 和 `bff.effect.strictEffectApproach: true`。接口先改 `shared/api.ts` 的 `HttpApi` 契约，再在 `api/index.ts` 用 `defineEffectBff(...)` / `HttpApiBuilder` 实现。
-3. 在生成或已迁移的 UltraModern workspace 中，把 raw handler、`api/lambda/**`、手写 `Response` 和手写 request parsing 视为迁移缺陷。
-4. 这套公开预设现在已经附带显式的发布 / 认证 gate。生成 workspace 会自带 `.github/workflows/ultramodern-workspace-gates.yml`，因此 `pnpm check` 与 `pnpm build` 从第一天开始就是本地接入契约的一部分；CI 会以并行矩阵运行这些基础 gate。
-
-旧版生成 workspace 迁移时，以已发布的包 cohort 作为事实来源：
+## 创建并验证 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
@@ -71,82 +56,31 @@ mise exec -- pnpm check
 mise exec -- pnpm build
 ```
 
-### 迁移本地化 Cloudflare SSR workspace
-
-当前 cohort 均支持本地化 Cloudflare SSR workspace。框架将裸 locale root 重定向移动到框架拥有的 Cloudflare Worker entry 和 i18n
-server runtime 中。请求 `/` 时，框架会按语言协商在服务端返回 `302`，例如
-`Accept-Language: cs-CZ` 会跳转到 `/cs`，英语或 fallback 流量会跳转到 `/en`。
-
-既有生成 workspace 应整体升级同一个 BleedingDev Modern package cohort。
-先解析当前 cohort 版本，再运行同版本迁移命令：
-
-```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
-```
-
-Cloudflare Workers 已部署环境需要在 cohort 更新后重新部署，并在接受迁移前验证 root
-响应：
+本地化 Cloudflare SSR workspace 在服务端将 `/` 重定向到协商的语言路径。
+`Accept-Language: cs-CZ` 返回 `302`、`Location: /cs`、
+`Cache-Control: private, no-store`，以及覆盖语言检测 Header 的 `Vary`。
 
 ```bash
 curl -I -H 'Accept-Language: cs-CZ,cs;q=0.9,en;q=0.1' https://<worker-host>/
 ```
 
-期望响应是 `302`，并带有 `Location: /cs` 或匹配的 locale、
-`Cache-Control: private, no-store`，以及覆盖语言检测 Header 的 `Vary`。继续跟随该
-redirect 后，应返回匹配语言的 SSR 页面，文档语言和 i18n SSR 数据也应一致。
-
-不要通过 app 自有 root route、客户端 redirect、自定义导航 wrapper、Cloudflare Worker
-postprocess、生成产物编辑或本地 redirect shim 来修复旧版本的 root `404`。如果升级后
-`/` 仍然返回 `404`，先确认生产构建日志显示的
-`Modern.js Framework v<cohort-version>` 就是迁移目标 cohort，然后重新部署 Worker。
-
-严格生成 API 迁移是当前每个 cohort 的组成部分：直接 `api/index.ts` 生成器、生成的
-`.mts` 检查、严格 Oxlint 边界规则、Effect 版本组 overrides 和严格 Effect 迁移命令。
-还不能安装 BleedingDev cohort 的 agent 应使用本地 Modern.js workspace 做迁移校验；
-否则用 `--ultramodern-package-version` 固定目标 cohort。
-
-手写 package alias 或生成 metadata 之前，先在目标 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
-```
-
-该命令会更新 `.modernjs/ultramodern.json`、根 `modernjs.packageSource`、生成的
-Modern package alias、框架拥有的 toolchain pin、直接 topology API metadata、严格 Effect
-pnpm overrides/trust policy 和 pnpm lockfile。剩余失败就是源码迁移：把代码移到
-`shared/api.ts`、`api/index.ts` 和 `src/api/*-client.ts`，再删除 `api/effect`、
-`api/lambda`、`shared/effect` 和 `src/effect`。
-
 严格 Effect 生成 workspace 会通过 pnpm overrides 固定兼容版本组：
-`effect@4.0.0-rc.112`、`@effect/opentelemetry@4.0.0-rc.112` 和
-`@effect/vitest@4.0.0-rc.112`。不要添加与这些 overrides 冲突的 app 本地直接
+`effect@4.0.0-rc.117`、`@effect/opentelemetry@4.0.0-rc.117` 和
+`@effect/vitest@4.0.0-rc.117`。不要添加与这些 overrides 冲突的 app 本地直接
 Effect 版本。严格的 24 小时发布年龄门禁适用于实际安装的包；当前版本组不包含 Effect
 年龄豁免，仅用于 override 的 `@effect/vitest` 也不是已安装的审批目标。
-`trustPolicyExclude` 是独立策略，仅为 `effect` 和
-`@effect/opentelemetry` 保留精确例外，以处理 trusted-publisher metadata 向
-provenance attestation 的迁移；它不属于 release-age 审批。
 
 ### 当前生成依赖基线
 
 | 范围 | 固定版本 |
 | --- | --- |
-| Effect runtime 与测试版本组 | `effect`、`@effect/opentelemetry`、`@effect/vitest`：`4.0.0-rc.112` |
-| Effect compiler | `@effect/tsgo@0.41.0` |
-| Oxc 与 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`、`rspack`：`2.9.0`；`@module-federation/node@2.7.50` |
+| Effect runtime 与测试版本组 | `effect`、`@effect/opentelemetry`、`@effect/vitest`：`4.0.0-rc.117` |
+| Effect compiler | `@effect/tsgo@0.45.0` |
+| Oxc 与 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`、`rspack`：`2.9.2`；`@module-federation/node@2.7.52` |
 | Tailwind CSS | `tailwindcss@4.3.3` |
-| Node 与包管理工具 | Node `26.7.0`、`@types/node@^26.4.1`、pnpm `11.24.0` |
+| Node 与包管理工具 | Node `26.7.0`、`@types/node@^26.6.2`、pnpm `11.27.1` |
 
 生成的 workspace 默认使用 `@module-federation/bridge-react` 的
 router-free base entry（`bridge.enableBridgeRouter: false`），应用路由由
@@ -190,7 +124,7 @@ Effect RPC、WebSockets 和其他传输方式应在需要时作为显式 transpo
 它们不能作为在生成 HTTP API 模块中重新引入原始 request handler 的理由。
 
 严格 API 测试应执行 `HttpApi` 契约。Edge 兼容 proof 测试使用
-`@modern-js/plugin-bff/effect-edge` 的 `createEffectBffTestHandler`；如果必须手动组合
+`@modern-js/bff-effect/effect-edge` 的 `createEffectBffTestHandler`；如果必须手动组合
 web handler，在调用 `HttpRouter.toWebHandler` 前要把 `HttpServer.layerServices` 和
 API group layer 一起提供。
 

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

@@ -191,6 +191,7 @@ api.onPrepare(async () => {
       - `'file-change'`： 文件变化事件
     - `event.payload`： 当 `type` 为 `'file-change'` 时，包含文件变化信息数组。
 - **执行阶段：** 当文件发生变化或需要重新打包时。
+- **重新打包顺序：** 对于 `'repack'`，开发服务器会按注册顺序等待处理函数完成，再从 require 缓存中清除上一代服务端产物。某个处理函数抛出错误时，其后的处理函数不再执行。新请求会等待处理函数完成；已在执行的请求继续使用已加载的模块。重新打包处理函数不能等待发往开发服务器的请求，因为该请求会等待处理函数完成。
 - **示例：**
 
 ```typescript

package/package.json

@@ -19,29 +19,29 @@
     "modern.js",
     "ultramodern.js"
   ],
-  "version": "3.9.0-ultramodern.2",
+  "version": "3.9.0-ultramodern.21",
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.9.0-ultramodern.2",
-    "@modern-js/ultramodern-sandpack-profile": "npm:@bleedingdev/modern-js-ultramodern-sandpack-profile@3.9.0-ultramodern.2",
+    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.9.0-ultramodern.21",
+    "@modern-js/ultramodern-sandpack-profile": "npm:@bleedingdev/modern-js-ultramodern-sandpack-profile@3.9.0-ultramodern.21",
     "mermaid": "^11.17.2"
   },
   "devDependencies": {
     "@rsbuild/plugin-sass": "2.0.1",
-    "@rspress/core": "2.0.21",
-    "@rspress/plugin-llms": "2.0.21",
-    "@rspress/shared": "2.0.21",
+    "@rspress/core": "2.0.22",
+    "@rspress/plugin-llms": "2.0.22",
+    "@rspress/shared": "2.0.22",
     "@shikijs/transformers": "^4.4.3",
     "@types/fs-extra": "11.0.4",
-    "@types/node": "^26.4.1",
+    "@types/node": "^26.6.2",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "classnames": "^2.5.1",
     "clsx": "^2.1.1",
-    "fs-extra": "^11.4.0",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
+    "fs-extra": "^11.4.1",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
     "rsbuild-plugin-open-graph": "1.1.3",
     "ts-node": "^10.9.2",
     "typescript": "^7.0.2"

package/src/sandbox/csr-auth/src/routes/Auth-tsx.txt

@@ -1,6 +1,6 @@
 import {
   Navigate,
-  useLocation,
+  useMatch,
   useNavigate,
 } from '@modern-js/plugin-tanstack/runtime';
 import React from 'react';
@@ -52,8 +52,9 @@ export function AuthStatus() {
       Welcome {auth.user}!{' '}
       <button
         type="button"
-        onClick={() => {
-          auth.signout(() => void navigate({ to: '/' }));
+        onClick={async () => {
+          await navigate({ to: '/' });
+          auth.signout(() => {});
         }}
       >
         Sign out
@@ -62,9 +63,12 @@ export function AuthStatus() {
   );
 }
 
-export function RequireAuth({ children }: { children: JSX.Element }) {
+export function RequireAuth({ children }: { children: React.JSX.Element }) {
   const auth = useAuth();
-  const location = useLocation();
+  const pathname = useMatch({
+    strict: false,
+    select: match => match.pathname,
+  });
 
   if (!auth.user) {
     // Redirect them to the /login page, but save the current location they were
@@ -74,7 +78,7 @@ export function RequireAuth({ children }: { children: JSX.Element }) {
     return (
       <Navigate
         replace
-        search={{ redirect: location.pathname }}
+        search={{ redirect: pathname }}
         to="/login"
       />
     );

package/src/sandbox/csr-auth/src/routes/page-tsx.txt

@@ -1,4 +1,5 @@
 import { Helmet } from '@modern-js/runtime/head';
+import type { JSX } from 'react';
 import './index.css';
 
 const PublicPage = (): JSX.Element => (

package/ultramodern-preset/package.json

@@ -13,7 +13,7 @@
     "rsbuild-plugin-open-graph": "1.1.3"
   },
   "devDependencies": {
-    "@rspress/core": "2.0.21",
-    "@types/node": "^26.4.1"
+    "@rspress/core": "2.0.22",
+    "@types/node": "^26.6.2"
   }
 }