用途
bun-react-ssr 用于在 Bun 运行时中构建自定义的服务端渲染（SSR）React 应用，不依赖 Next.js 等框架。它适合需要完全掌控渲染流程、希望利用 Bun 内置能力（如 Bun.serve、Bun.build、bun:sqlite）来搭建轻量 SSR 服务的场景。
主要能力
- 基础 SSR：使用 react-dom/server 的 renderToString 在服务端渲染 React 组件，返回完整 HTML 文档。
- 客户端水合：使用 react-dom/client 的 hydrateRoot 在浏览器端接管服务端生成的 HTML。
- 流式 SSR：使用 renderToReadableStream 配合 bootstrapScripts 和 onError，实现流式响应，并通过 stream.allReady 等待 Suspense 边界就绪。
- Suspense 支持：在组件树中使用 Suspense 与 fallback，实现渐进式加载。
- 服务端数据获取：在服务端查询数据（示例使用 bun:sqlite 的 Database），将初始数据通过 props 传入组件，并注入到 window.INITIAL_DATA 供客户端水合使用。
- 简单路由：提供基于 useState、useEffect 和 popstate 事件的客户端路由示例，以及 Link 组件。
- CSS 处理：支持将 CSS 内联到 HTML 的 style 标签，或通过 Bun.build 构建外部样式表并在 HTML 中引用。
- 开发与构建：提供基于 fs.watch 与 Bun.spawn 的热重载开发脚本，以及分别构建客户端（target: browser）和服务端（target: bun）的生产构建脚本。
使用方式
快速开始：
mkdir my-ssr-app && cd my-ssr-app
bun init
bun add react react-dom
bun add -D @types/react @types/react-dom
基础 SSR 需要三个文件：服务端入口 src/server.tsx（使用 Bun.serve 与 renderToString）、客户端入口 src/client.tsx（使用 hydrateRoot）、以及 React 应用 src/App.tsx。客户端 bundle 通过 Bun.build 构建，指定 entrypoints、outdir、target: "browser"、minify 和 splitting。
流式 SSR 使用 renderToReadableStream，并在选项中传入 bootstrapScripts 与 onError 回调。
数据获取示例中，服务端使用 bun:sqlite 查询数据，将结果作为 initialData 传入组件，并在 HTML 中通过内联 script 写入 window.INITIAL_DATA，客户端读取该全局变量后传给 hydrateRoot。
路由示例通过 useState 保存当前路径，监听 popstate 事件更新路径，Link 组件使用 history.pushState 并手动派发 PopStateEvent。
CSS 可以内联（读取 CSS 文件文本放入 style 标签），也可以构建为外部样式表并通过 link 标签引用。
开发热重载脚本使用 fs.watch 监听 src 目录，变更时通过 Bun.spawn 重启服务端进程。
生产构建分别构建客户端（输出到 dist/public/static，target: browser，minify，splitting，sourcemap: external）和服务端（输出到 dist，target: bun，minify）。
适用场景
- 希望用 Bun 搭建无框架、可完全自定义的 React SSR 应用。
- 需要流式 SSR 与 Suspense 渐进加载以优化首字节时间（TTFB）。
- 需要在服务端直接访问数据库（如 bun:sqlite）并将数据注入客户端水合。
- 需要轻量级客户端路由与 CSS 处理方案。
- 需要自定义开发热重载与生产构建流程。
限制与注意事项
- 该技能不依赖框架，路由、数据获取、缓存等均需自行实现，示例仅提供基础模式。
- 常见错误包括：水合不匹配（服务端与客户端 HTML 不一致，需检查初始状态）、document is not defined（SSR 中访问 DOM，需用 typeof window 守卫）、hooks 使用位置错误、未样式化内容闪烁（CSS 未加载，可内联关键 CSS）。
- 性能建议包括：使用流式 SSR 提升 TTFB、内联首屏关键 CSS、对客户端 bundle 做代码分割、缓存静态页面渲染结果、使用 Suspense 实现渐进加载。
- 参考资料 references/streaming-patterns.md 涉及复杂 Suspense 边界、选择性水合、渐进增强；references/caching.md 涉及 HTML 缓存策略、CDN 集成、边缘渲染。
- 关于收费、价格、平台支持范围等具体信息，资料中暂未提供。