btst-integration

BTST 库集成

快速开始

1. 安装 @btst/stack、@tanstack/react-query 和一个 @btst/adapter-*。
2. 安装并注册每个插件的后端和客户端部分。
3. 创建 lib/stack.ts → 导出 { handler, dbSchema }。
4. 使用框架 API 入口工厂，将 handler 挂载到 /api/data/*。
5. 在全局 CSS 中，按插件添加 @import "@btst/stack/plugins/{plugin}/css"。
6. 创建 lib/stack-client.tsx、lib/query-client.ts，以及使用框架页面入口工厂的 /pages/* 全捕获路由。
7. 创建页面的 layout 文件，包含 QueryClientProvider + StackProvider。
8. 运行 @btst/cli generate（Kysely 还需运行 migrate）。

请参阅 REFERENCE.md，了解每个文件的完整代码结构。

工作流

1) 安装前置条件和软件包

• 前置条件：shadcn/ui（已启用 CSS 变量）、Sonner <Toaster />、Tailwind v4。
• 安装：@btst/stack、@tanstack/react-query 和一个适配器：
  • @btst/adapter-prisma / @btst/adapter-drizzle / @btst/adapter-kysely / @btst/adapter-mongodb
  • @btst/adapter-memory — 仅用于开发/测试，不适用于生产环境
• 在 @btst/stack 旁安装每个插件软件包（它们随 monorepo 软件包一同提供）。

2) 注册插件（后端 + 客户端）

• 后端（lib/stack.ts）：从 @btst/stack/plugins/{plugin}/api 导入 {plugin}BackendPlugin。
  • 在后端插件选项对象中传入钩子和配置（例如 blogBackendPlugin({ hooks })）。
  • 对名称由多个部分组成的插件使用 camelCase 键：aiChat、formBuilder、uiBuilder。
• 客户端（lib/stack-client.tsx）：从 @btst/stack/plugins/{plugin}/client 导入 {plugin}ClientPlugin。
  • 客户端定义仅接收插件专属选项，例如 seo、钩子或页面组件。在 createClientStack() 上配置一次 api、site 和 queryClient；其解析器会将该运行时绑定到每个定义。
  • 通过顶层 createClientStack({ api: { headers } }) 配置传递传入的 SSR 请求标头。
  • 在服务器上解析一个可信的 API/站点来源快照，并将其注入提供程序。托管后端可以使用独立的 BTST_API_URL；水合后切勿根据 window.location 重新构造该地址。

3) 配置后端堆栈

• 在启用应用授权时，调用 createBackendStack({ basePath: "/api/data", plugins: { ... }, adapter: (db) => createXxxAdapter(..., db, {}), auth: serverAuth })。
• 使用 createServerAuth({ authorization, getIdentity }) 创建 serverAuth。省略 auth 会有意保留无授权的宽松兼容性；AI Chat 的 access: "authorized" 等插件标签本身并不构成强制执行边界。
• 导出 handler 和 dbSchema。
• Memory 适配器 + Next.js：固定到 globalThis，以避免同一进程中出现两个实例：

  function createAppStack() {
    return createBackendStack({ ... })
  }
  
  type AppStack = ReturnType<typeof createAppStack>
  const g = globalThis as typeof globalThis & { __btst__?: AppStack }
  export const myStack = g.__btst__ ??= createAppStack()
  export const { handler, dbSchema } = myStack
  

4) CSS — 编辑全局样式表

在 Tailwind 层之前，为每个插件添加一行：

@import "@btst/stack/plugins/blog/css";
@import "@btst/stack/plugins/cms/css";
@import "@btst/stack/plugins/ai-chat/css";
/* …one per selected plugin */

请勿重复添加 — 补丁程序和手动编辑都必须具有幂等性。

5）连接框架路由和客户端运行时

• API 路由：使用框架入口点中的 toNextRouteHandlers、 toReactRouterHandlers 或 toTanStackHandlers。
• Pages 路由：使用 createNextPage、 createReactRouterPage 或 createTanStackPageOptions。工厂负责路由匹配、加载器排序、水合、元数据和 404 处理。
• Pages 布局（Next.js 中的 "use client"）：先封装 QueryClientProvider，再封装 StackProvider：
  • 通过 stack={clientStack} 传入解析后的客户端 stack。其顶层 site.basePath 必须与 Pages 的 catch-all 前缀匹配。
  • 使用 router={nextRouter()} / reactRouter() / tanstackRouter()，为整个框架提供链接、图片、导航和刷新功能。
  • 当插件需要身份信息或权限展示门控时，使用 auth={createClientAuth({ authorization, getIdentity, loginPath })}。
  • 仅在需要针对特定插件进行自定义时使用 overrides={{ pluginKey: { uploadImage?, ...pluginSpecificValues } }}。
  • 让解析后的插件映射推断覆盖项的键和值；不要重复创建手动 provider 映射。
  • 有关 provider 连接和各插件的覆盖项结构，请参阅 REFERENCE.md。
• 仅适用于 ai-chat 插件：在 StackProvider 上方的根布局中封装 PageAIContextProvider：

  import { PageAIContextProvider } from "@btst/stack/plugins/ai-chat/client/context"
  // root layout.tsx (not the pages layout)
  export default function RootLayout({ children }) {
    return <PageAIContextProvider>{children}</PageAIContextProvider>
  }
  

  然后，Pages 调用 useRegisterPageAIContext(...) 注册其 AI 上下文 — 请参阅 btst-ai-context 技能。

6）生成架构并运行迁移

• 将 @btst/cli 安装为开发依赖。
• Prisma：npx @btst/cli generate --config=lib/stack.ts --orm=prisma --output=schema.prisma
• Drizzle：npx @btst/cli generate --config=lib/stack.ts --orm=drizzle --output=src/db/schema.ts
• Kysely：npx @btst/cli generate --config=lib/stack.ts --orm=kysely --output=migrations/schema.sql --database-url=...
• Kysely 迁移：npx @btst/cli migrate --config=lib/stack.ts --database-url=...
• Prisma/Drizzle：生成后使用原生迁移工具。

验证清单

• stack.ts 同时导出 handler 和 dbSchema。
• 受保护的应用将 createServerAuth(...) 传入 createBackendStack({ auth })；省略 auth 会有意采用宽松策略。
• 每个插件都在后端和客户端两侧注册。
• API basePath 与 createBackendStack({ basePath }) 完全匹配。
• API 和页面 catch-all 路由都使用框架入口工厂。
• Pages 布局使用 "use client"，并依次封装 QueryClientProvider 和 StackProvider。
• 解析后的客户端 stack 的 site.basePath 与 /pages catch-all 路由前缀匹配。
• 全局 CSS 为每个选定插件各包含一行 @import。
• /pages/* 路由会渲染预期的插件页面。
• CLI 命令运行时，所需的环境变量均已生效。

注意事项

• Pages 布局缺少 "use client" — StackProvider 使用 hooks，必须在客户端运行。
• 键的大小写错误 — 后端和客户端插件映射的键必须匹配；复合名称使用 camelCase（aiChat，而不是 ai-chat）。
• 缺少 CSS 导入 — 即使数据加载正常，插件 UI 也会在无提示的情况下失效。
• 插件仅在一侧注册 — 仅注册后端时，路由不存在；仅注册客户端时，数据调用会返回 404。
• Memory 适配器 + Next.js — 始终绑定到 globalThis，以便在 API 和页面 bundle 之间共享同一个内存存储。
• CLI 中的路径别名 — @btst/cli 会直接执行你的配置文件；在 lib/stack.ts 及其依赖项中使用相对导入。
• Kysely 生成需要数据库 — 传入 DATABASE_URL 或 --database-url；对于 .env.local，请使用 dotenv-cli。
• 将 provider 服务复制到插件覆盖项中 — 切勿将 Link、 Image、导航、刷新、API 路径、身份或登录值添加到内置插件覆盖项中。请使用顶层的 router、api 和 auth。