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 技能中的 Bootstrap 部分）
• 已完成 PocketBase 集合设计（推荐）

1. 项目脚手架

1-1. 项目结构

采用前后端分离的 monorepo 结构：

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()（不带参数）在任何环境下都能正常工作，无需环境变量。

重要： 不要修改生成的 plugins 数组。只需添加 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"
  }
}

向用户确认超级用户的电子邮件和密码。调整 --url，使其与 PocketBase 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. Auth 上下文 — 在 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 重新生成类型
• 可直接通过 http://127.0.0.1:8090/_/ 访问管理 UI

详情： Read references/dev-and-deploy.md

4. 部署

SPA 构建 → 放置到 PocketBase pb_public

在生产环境中，PocketBase 会直接提供 SPA 服务（无需单独的 Web 服务器）：

# 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