btst-integration

BTST ライブラリの統合

クイックスタート

1. @btst/stack、@tanstack/react-query、およびいずれか1つの @btst/adapter-* をインストールします。
2. 各プラグインのバックエンド側とクライアント側をインストールして登録します。
3. lib/stack.ts を作成し、{ handler, dbSchema } をエクスポートします。
4. フレームワークの API エントリーファクトリーを使って、/api/data/* に handler をマウントします。
5. グローバル CSS で、プラグインごとに @import "@btst/stack/plugins/{plugin}/css" を追加します。
6. lib/stack-client.tsx、lib/query-client.ts、およびフレームワークのページエントリーファクトリーを使った /pages/* のキャッチオールルートを作成します。
7. QueryClientProvider と StackProvider を含むページの レイアウト ファイルを作成します。
8. @btst/cli generate を実行します（Kysely の場合は migrate も実行します）。

各ファイルのコード構成については、REFERENCE.md をご覧ください。

ワークフロー

1) 前提条件とパッケージのインストール

• 前提条件：shadcn/ui（CSS 変数を有効化）、Sonner の <Toaster />、Tailwind v4。
• インストールするもの：@btst/stack、@tanstack/react-query、およびいずれか1つのアダプター：
  • @btst/adapter-prisma / @btst/adapter-drizzle / @btst/adapter-kysely / @btst/adapter-mongodb
  • @btst/adapter-memory — 開発・テスト専用で、本番環境では使用しないでください
• 各プラグインパッケージは @btst/stack と一緒にインストールします（これらはモノレポパッケージ内に含まれています）。

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、フック、ページコンポーネントなど、プラグイン固有のオプションのみです。api、site、queryClient は createClientStack() で一度だけ設定します。リゾルバーが、そのランタイムを各定義にバインドします。
  • 受信した SSR リクエストヘッダーは、トップレベルの createClientStack({ api: { headers } }) 設定を通じて渡します。
  • サーバー上で信頼できる API／サイトオリジンのスナップショットを1つ解決し、プロバイダーにハイドレートします。管理されたバックエンドでは、異なる 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：同一プロセス内で2つのインスタンスが作成されるのを防ぐため、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 レイヤーの前に、プラグインごとに1行追加します：

@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 を使用します。
• ページルート：createNextPage、 createReactRouterPage、または createTanStackPageOptions を使用します。このファクトリーが、ルートのマッチング、ローダーの実行順序、ハイドレーション、メタデータ、404 の処理を担います。
• ページレイアウト（Next.js の "use client"）：QueryClientProvider、続けて StackProvider でラップします。
  • 解決済みのクライアントスタックを stack={clientStack} で渡します。そのトップレベルの site.basePath は、ページのキャッチオールプレフィックスと一致する必要があります。
  • フレームワーク全体でリンク、画像、ナビゲーション、更新を行うには、router={nextRouter()}／reactRouter()／tanstackRouter() を指定します。
  • プラグインで ID または権限の表示制御が必要な場合は、auth={createClientAuth({ authorization, getIdentity, loginPath })} を指定します。
  • overrides={{ pluginKey: { uploadImage?, ...pluginSpecificValues } }} は、プラグイン固有のカスタマイズにのみ使用します。
  • 解決済みのプラグインマップにオーバーライドのキーと値を推論させ、手動のプロバイダーマップを重複して作成しないでください。
  • プロバイダーの接続方法と、プラグインごとのオーバーライドの形式については、REFERENCE.md を参照してください。
• ai-chat プラグインのみ：PageAIContextProvider で ルートレイアウト（StackProvider の上位）をラップします。

  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>
  }
  

  ページでは 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：generate の実行後、ネイティブのマイグレーションツールを使用します。

検証チェックリスト

• stack.ts が handler と dbSchema の両方をエクスポートしている。
• 保護されたアプリケーションでは、createBackendStack({ auth }) に createServerAuth(...) を渡している。auth を省略すると、意図的に制限のない状態になります。
• すべてのプラグインが、バックエンド側とクライアント側の両方に登録されている。
• API の basePath と createBackendStack({ basePath }) が完全に一致している。
• API とページのキャッチオールルートで、フレームワークのエントリーファクトリーを使用している。
• ページレイアウトが "use client" であり、QueryClientProvider、続けて StackProvider でラップされている。
• 解決済みのクライアントスタックの site.basePath が、/pages のキャッチオールルートプレフィックスと一致している。
• グローバル CSS に、選択したプラグインごとに 1 行の @import がある。
• /pages/* ルートで、想定どおりのプラグインページがレンダリングされる。
• CLI コマンドの実行時に、必要な環境変数が有効になっている。

注意点

• ページレイアウトに "use client" がない — StackProvider はフックを使用するため、クライアント側で動作させる必要があります。
• キーの大文字・小文字が誤っている — バックエンドとクライアントのプラグインマップのキーは一致させる必要があります。複合名はキャメルケースを使用します（ai-chat ではなく aiChat）。
• CSS インポートがない — データが正しく読み込まれていても、プラグインの UI が何も表示されないまま動作しなくなります。
• プラグインの登録が片側だけ — バックエンド側のみの場合はルートが存在せず、クライアント側のみの場合はデータ呼び出しが 404 になります。
• Next.js でのメモリーアダプター — API とページのバンドル間で 1 つのインメモリストアを共有できるよう、必ず globalThis に固定します。
• CLI でのパスエイリアス — @btst/cli は設定ファイルを直接実行します。lib/stack.ts とその依存ファイルでは相対インポートを使用してください。
• Kysely の generate には DB が必要 — DATABASE_URL または --database-url を渡します。.env.local には dotenv-cli を使用します。
• プロバイダーサービスをプラグインのオーバーライドにコピーしている — 組み込みプラグインのオーバーライドには、Link、Image、ナビゲーション、更新、API パス、ID、ログインの値を追加しないでください。トップレベルの router、api、auth を使用します。