pb-react-spa

PocketBase React SPA スキル

PocketBase バックエンドと統合された React SPA フロントエンドのセットアップを自動化するスキルです。

技術スタック：

• Vite — ビルドツール／開発サーバー
• React + TypeScript — UI フレームワーク
• TanStack Router — ファイルベースのルーティング
• TanStack Query — サーバー状態の管理
• Tailwind CSS + Shadcn UI — スタイリング／UI コンポーネント
• Biome — リンター／フォーマッター
• PocketBase JS SDK — バックエンドとの通信
• pocketbase-typegen — 型生成

スキルのリソース

• リファレンス：references/ — 統合パターン、認証、型生成、開発・デプロイガイド
• PocketBase バックエンドスキル：pocketbase スキルでバックエンド管理（コレクションの CRUD、API ルールの設計など）を行います。

PocketBase JS SDK の詳細については、PocketBase スキルの references/js-sdk.md も参照してください。

0. 前提条件

• Node.js v18 以上、npm
• PocketBase が起動していること（pocketbase スキルのブートストラップセクションを参照）
• PocketBase のコレクション設計が完了していること（推奨）

1. プロジェクトのスキャフォールディング

1-1. プロジェクト構成

フロントエンドとバックエンドを分離したモノレポ構成を採用します。

project-root/
├── frontend/     ← React SPA (created by this skill)
├── backend/      ← PocketBase (managed by the pocketbase skill)
│   ├── pocketbase
│   ├── pb_data/
│   ├── pb_migrations/
│   └── .env
└── README.md

注： ユーザーの既存のプロジェクト構成を確認し、必要に応じて調整してください。frontend/ ディレクトリ名は、ユーザーの希望に応じて変更できます。

1-2. 基本プロジェクトの生成

npx create-tsrouter-app@latest frontend \
  --toolchain biome \
  --package-manager npm \
  --no-git

注： create-tsrouter-app は TanStack CLI のラッパーです。--router-only（ファイルベースのルーティング）はデフォルトで有効になっています。Tailwind CSS v4 も自動的にセットアップされます。

このコマンドで、以下がセットアップされます。

• Vite + React + TypeScript
• TanStack Router（ファイルベースのルーティング）
• Tailwind CSS v4
• Biome（リンター／フォーマッター）

1-3. Shadcn UI の追加

cd frontend && npx shadcn@latest init -d

-d フラグでは、デフォルト設定（new-york スタイル、neutral カラー）が使用されます。components.json ファイルが作成され、@/components/ui/ にコンポーネントを追加できるようになります。

コンポーネントの追加例：

npx shadcn@latest add button card input label

1-4. TanStack Query の追加

npm install @tanstack/react-query

1-5. PocketBase JS SDK のインストール

npm install pocketbase

1-6. pocketbase-typegen のインストール

npm install -D pocketbase-typegen

1-7. セットアップの確認

npm run build

ビルドが正常に完了することを確認してください。開発サーバーを確認するには、npm run dev を実行します。

2. セットアップ後の設定

スキャフォールディングの完了後、以下の設定を順番に追加します。

2-1. PocketBase クライアント

frontend/src/lib/pocketbase.ts を作成します。

import PocketBase from "pocketbase";
import type { TypedPocketBase } from "../types/pocketbase-types";

export const pb = new PocketBase() as TypedPocketBase;

pb.autoCancellation(false);

TypedPocketBase は pocketbase-typegen によって生成された型です。まだ型が生成されていない場合は、一時的に PocketBase 型を直接使用し、生成後に置き換えてください。

// 型生成前の一時的なバージョン
import PocketBase from "pocketbase";
export const pb = new PocketBase();
pb.autoCancellation(false);

2-2. Vite プロキシの設定

frontend/vite.config.ts を編集して、server.proxy を追加します。

生成された vite.config.ts は、以下の構成になっています。

import { defineConfig } from "vite";
import { devtools } from "@tanstack/devtools-vite";
import tsconfigPaths from "vite-tsconfig-paths";
import { tanstackRouter } from "@tanstack/router-plugin/vite";
import viteReact from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";

const config = defineConfig({
  plugins: [
    devtools(),
    tsconfigPaths({ projects: ["./tsconfig.json"] }),
    tailwindcss(),
    tanstackRouter({ target: "react", autoCodeSplitting: true }),
    viteReact(),
  ],
  // ↓ Add this
  server: {
    proxy: {
      "/api": {
        target: "http://127.0.0.1:8090",
        changeOrigin: true,
      },
      "/_": {
        target: "http://127.0.0.1:8090",
        changeOrigin: true,
      },
    },
  },
});

export default config;

/api は PocketBase REST API、/_ は PocketBase の内部エンドポイント（リアルタイム SSE など）用です。

PocketBase クライアントに URL が不要なのはなぜですか？ プロキシによって、開発中のすべての PocketBase API リクエストが同一オリジンになります（ブラウザーには localhost:5173/api/... と表示されます）。本番環境では PocketBase が pb_public/ から SPA を配信し、こちらも同一オリジンになります。どちらの環境でも同一オリジンのため、new PocketBase()（引数なし）をどこでも使用でき、環境変数は不要です。

重要： 生成されたプラグイン配列は変更しないでください。server.proxy のみを追加します。

2-3. TypeScript 型の生成

PocketBase の起動中に型を生成します。

npx pocketbase-typegen --url http://127.0.0.1:8090 --email [email protected] --password yourpassword --out frontend/src/types/pocketbase-types.ts

frontend/package.json に npm スクリプトを追加します。

{
  "scripts": {
    "typegen": "pocketbase-typegen --url http://127.0.0.1:8090 --email [email protected] --password yourpassword --out src/types/pocketbase-types.ts"
  }
}

スーパーユーザーのメールアドレスとパスワードをユーザーに確認してください。PocketBase の URL に合わせて --url を調整します。

詳細： Read references/typegen.md

2-4. TanStack Query の設定

QueryClient を作成し、ルートコンポーネントで Provider を設定します。

frontend/src/routes/__root.tsx を編集します。

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { Outlet, createRootRouteWithContext } from "@tanstack/react-router";

export interface RouterContext {
  queryClient: QueryClient;
}

export const Route = createRootRouteWithContext<RouterContext>()({
  component: RootComponent,
});

function RootComponent() {
  return <Outlet />;
}

frontend/src/router.tsx（または main.tsx）で QueryClient を作成し、ルーターのコンテキストに渡します。

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { createRouter as createTanStackRouter } from "@tanstack/react-router";
import { routeTree } from "./routeTree.gen";

const queryClient = new QueryClient();

export function getRouter() {
  const router = createTanStackRouter({
    routeTree,
    scrollRestoration: true,
    defaultPreload: "intent",
    defaultPreloadStaleTime: 0,
    context: { queryClient },
  });
  return router;
}

重要： 既存の router.tsx／main.tsx の内容を確認し、既存の設定を維持しながら QueryClient を統合してください。上記はパターンの例です。生成されたファイルのコードに合わせて編集してください。

詳細： Read references/react-query-pocketbase.md

2-5. 認証の統合

認証が必要な場合は、以下を設定してください。

1. 認証コンテキスト — frontend/src/lib/auth.tsx に AuthProvider を作成します
2. 保護されたルート — TanStack Router の beforeLoad を使用して認証を確認します
3. ログインページ — frontend/src/routes/login.tsx

詳細： Read references/auth-patterns.md

3. 開発ワークフロー

PocketBase と Vite を同時に実行する

ターミナル 1（PocketBase）：

cd backend && ./pocketbase serve --http=127.0.0.1:8090

ターミナル 2（Vite 開発サーバー）：

cd frontend && npm run dev

Claude Code のセッションでは、PocketBase をバックグラウンドで起動します。

cd backend && nohup ./pocketbase serve --http=127.0.0.1:8090 > pb.log 2>&1 &

開発のヒント

• Vite のプロキシにより CORS の問題が解消されます（同一オリジンとして動作します）
• フロントエンドの変更は HMR によりすぐに反映されます
• PocketBase のコレクションを変更した後は、npm run typegen で型を再生成します
• Admin UI は http://127.0.0.1:8090/_/ から直接アクセスできます

詳細： Read references/dev-and-deploy.md

4. デプロイ

SPA のビルド → PocketBase の pb_public への配置

本番環境では、PocketBase が SPA を直接配信します（別途ウェブサーバーは不要です）。

# Build
cd frontend && npm run build

# Place in PocketBase's pb_public
cp -r frontend/dist/* backend/pb_public/

PocketBase は pb_public/ のファイルを自動的に配信し、SPA のクライアントサイドルーティングをサポートします（存在しないパスは index.html にフォールバックします）。

Docker／Docker Compose／リバースプロキシ

Dockerfile（バイナリモードと Go パッケージモード）、Docker Compose、Caddy／Nginx リバースプロキシ、実行可能ファイルの配布を含む本番環境へのデプロイについては、以下を参照してください。

詳細： Read references/deployment.md

5. セットアップチェックリスト

スキャフォールディング完了後の確認項目：

• npm run build が成功する
• src/lib/pocketbase.ts が作成されている
• vite.config.ts にプロキシ設定が追加されている
• components.json が存在する（Shadcn UI が初期化されている）
• QueryClient が設定されている（__root.tsx／router.tsx）
• PocketBase JS SDK をインポートできる（import PocketBase from "pocketbase"）
• npm run typegen で型が生成される（PocketBase の実行中）
• 認証が必要な場合：AuthProvider と保護されたルートが設定されている

6. リファレンス一覧

トピック	リファレンス
TanStack Query と PB の統合	Read references/react-query-pocketbase.md
認証パターン	Read references/auth-patterns.md
TypeScript の型生成	Read references/typegen.md
開発ワークフロー	Read references/dev-and-deploy.md
本番環境へのデプロイ（Docker、バイナリ、プロキシ）	Read references/deployment.md
JS SDK の詳細	PocketBase スキル内の Read references/js-sdk.md