本技能介绍如何将 actor-kit 状态机接入 TanStack Start 应用，实现服务端渲染、JWT 认证与实时 WebSocket 同步，并运行在 Cloudflare Workers 上。
架构概览
浏览器侧由 TanStack Router 负责，包含路由 Loader（通过 createServerFn 发起 HTTP GET）、React 组件（Provider、useSelector、useSend，通过 WebSocket 通信）。Cloudflare Worker 侧由 Nitro Server 负责，包含中间件、Actor Router、健康检查与 Durable Object（XState 状态机），状态变更以 JSON Patch（diff）形式下发。
适用场景
- 新建带实时 actor-kit 状态的 TanStack Start 应用
- 为已有 TanStack Start 项目添加 actor-kit
- 搭建 actor-kit 的 SSR → WebSocket 水合
- 配置带 Durable Objects 的 Cloudflare Workers 部署
- 编写 actor-kit + TanStack Start 的端到端测试
设置步骤
-
定义 Actor：使用标准 actor-kit 配置，包含 schemas、types、machine、server 四部分。示例中定义了待办事项的客户端事件 schema（ADD_TODO、TOGGLE_TODO、DELETE_TODO）、服务端事件 schema（SYNC_TODOS）与输入属性 schema（ownerId），并通过 setup/createMachine 定义 XState 状态机，包含 isOwner 守卫和基于 immer 的 assign 操作。最后用 createMachineServer 与 createActorKitRouter 创建服务端。
-
创建 React Context：使用 createActorKitContext 生成上下文，并导出别名 Provider 以便 JSX 更简洁。
-
服务端环境：getServerEnv 同时处理 Cloudflare 运行时（检查 globalThis.env.TODO 绑定）与开发模式（读取 ACTOR_KIT_HOST、ACTOR_KIT_SECRET 环境变量）。
-
服务端中间件：拦截请求，提供 /health 健康检查端点，并将 /api/* 路径路由到 actor-kit router。
-
路由 Loader（SSR）：使用 createServerFn 在服务端获取初始快照。通过 createAccessToken 为指定 caller 与 actor 签发 JWT，再用 createActorFetch 向 Durable Object 发起 HTTP GET 获取 { snapshot, checksum }，返回 accessToken、host、listId、payload、userId。
-
路由组件（水合）：将服务端获取的快照接入 Provider，传入 host、actorId、accessToken、checksum、initialSnapshot。Provider 内部创建客户端并携带初始快照，挂载时调用 client.connect() 打开 WebSocket，服务端校验 JWT 后以 JSON Patch diff 同步状态变更。
-
组件使用：通过 useSelector 订阅状态（如 todos、isOwner），通过 useSend 发送事件。
水合流程
用户访问路由 → TanStack Router 调用服务端 Loader → Loader 签发 token 并获取快照 → 组件带初始快照渲染 → useEffect 打开 WebSocket → 服务端比对 checksum（匹配则无需初始负载）→ 服务端持续发送 JSON Patch diff，客户端用 Immer 应用 → 组件通过 useSyncExternalStore 订阅重新渲染。
Cloudflare 部署
Nitro 配置使用 cloudflare_module 预设，scanDirs 指向 ./server，开启 deployConfig 与 nodeCompat。通过 exports.cloudflare.ts 重新导出 Durable Object 类。wrangler.toml 中配置 name、main、compatibility_date、nodejs_compat 标志，以及 durable_objects 绑定（TODO → Todo）和 migrations。
端到端测试（Playwright）
配置 webServer 命令为构建加 wrangler dev，url 指向 /health 端点以等待服务器就绪。测试模式覆盖创建与管理待办事项，以及多标签页实时同步：两个浏览器上下文打开同一列表，一个页面添加事项，另一页面通过 WebSocket 在超时时间内看到更新。
检查清单
- Actor 已定义：schemas + types + machine + server
- React context 已用 createActorKitContext 创建
- 服务端环境同时处理 Cloudflare 运行时与开发模式
- 中间件将 /api/* 路由到 actor-kit router
- /health 健康检查端点存在
- 路由 loader 通过 createServerFn 获取快照
- 路由组件用 Provider 包裹子组件并传入快照与 token
- exports.cloudflare.ts 重新导出 Durable Object 类
- Wrangler 配置包含 DO 绑定与 migrations
- E2E 测试验证完整流程（导航 → 交互 → 验证）