⚡

TanStackStart全栈开发框架 BunTanStackStart

TanStack Start 是一个基于 Bun 运行时的全栈 React 框架，用于快速构建现代 Web 应用。它支持文件路由、服务器函数、API 路由和错误处理，提高开发效率，适用于 SSR、构建优化和全栈开发场景。关键词：TanStack Start, React, 全栈开发, Bun, 文件路由, 服务器函数, Web 应用开发, SEO 优化。

前端开发 0 次安装 0 次浏览 更新于 3/8/2026

name: Bun TanStack Start description: TanStack Start 全栈 React 框架，使用 Bun 运行时。适用于 TanStack Router、服务器函数、vinxi，或遇到 SSR、构建、预设错误时。

Bun TanStack Start

使用 Bun 运行 TanStack Start（全栈 React 框架）。

快速开始

# 创建新的 TanStack Start 项目
bunx create-tanstack-start@latest my-app
cd my-app

# 安装依赖
bun install

# 开发
bun run dev

# 构建
bun run build

# 预览
bun run start

项目设置

package.json

{
  "scripts": {
    "dev": "vinxi dev",
    "build": "vinxi build",
    "start": "vinxi start"
  },
  "dependencies": {
    "@tanstack/react-router": "^1.139.0",
    "@tanstack/start": "^1.120.0",
    "react": "^19.2.0",
    "react-dom": "^19.2.0",
    "vinxi": "^0.5.10"
  }
}

app.config.ts

import { defineConfig } from "@tanstack/start/config";

export default defineConfig({
  server: {
    preset: "bun",
  },
});

文件路由

app/
├── routes/
│   ├── __root.tsx       # 根布局
│   ├── index.tsx        # /
│   ├── about.tsx        # /about
│   ├── users/
│   │   ├── index.tsx    # /users
│   │   └── $userId.tsx  # /users/:userId
│   └── api/
│       └── users.ts     # /api/users
└── client.tsx

路由组件

基本路由

// app/routes/index.tsx
import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/")({
  component: Home,
});

function Home() {
  return <h1>欢迎回家</h1>;
}

带加载器的路由

// app/routes/users/index.tsx
import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/users/")({
  loader: async () => {
    const response = await fetch("/api/users");
    return response.json();
  },
  component: Users,
});

function Users() {
  const users = Route.useLoaderData();

  return (
    <ul>
      {users.map((user) => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

动态路由

// app/routes/users/$userId.tsx
import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/users/$userId")({
  loader: async ({ params }) => {
    const response = await fetch(`/api/users/${params.userId}`);
    return response.json();
  },
  component: UserDetail,
});

function UserDetail() {
  const user = Route.useLoaderData();
  const { userId } = Route.useParams();

  return (
    <div>
      <h1>{user.name}</h1>
      <p>用户 ID: {userId}</p>
    </div>
  );
}

服务器函数

定义服务器函数

// app/routes/users/index.tsx
import { createFileRoute } from "@tanstack/react-router";
import { createServerFn } from "@tanstack/start";
import { Database } from "bun:sqlite";

const getUsers = createServerFn("GET", async () => {
  const db = new Database("data.sqlite");
  const users = db.query("SELECT * FROM users").all();
  db.close();
  return users;
});

const createUser = createServerFn("POST", async (name: string) => {
  const db = new Database("data.sqlite");
  db.run("INSERT INTO users (name) VALUES (?)", [name]);
  db.close();
  return { success: true };
});

export const Route = createFileRoute("/users/")({
  loader: () => getUsers(),
  component: Users,
});

function Users() {
  const users = Route.useLoaderData();

  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    const name = formData.get("name") as string;
    await createUser(name);
    // 重新获取或更新状态
  };

  return (
    <div>
      <form onSubmit={handleSubmit}>
        <input name="name" placeholder="姓名" />
        <button type="submit">添加用户</button>
      </form>
      <ul>
        {users.map((user) => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
    </div>
  );
}

带上下文的服务器函数

import { createServerFn } from "@tanstack/start";
import { getWebRequest } from "@tanstack/start/server";

const getSession = createServerFn("GET", async () => {
  const request = getWebRequest();
  const cookies = request.headers.get("Cookie");
  // 解析和验证会话
  return { userId: "123", role: "admin" };
});

const protectedAction = createServerFn("POST", async (data: any) => {
  const session = await getSession();

  if (session.role !== "admin") {
    throw new Error("未授权");
  }

  // 执行操作
  return { success: true };
});

API 路由

// app/routes/api/users.ts
import { createAPIFileRoute } from "@tanstack/start/api";
import { Database } from "bun:sqlite";

export const Route = createAPIFileRoute("/api/users")({
  GET: async ({ request }) => {
    const db = new Database("data.sqlite");
    const users = db.query("SELECT * FROM users").all();
    db.close();

    return Response.json(users);
  },

  POST: async ({ request }) => {
    const { name } = await request.json();

    const db = new Database("data.sqlite");
    db.run("INSERT INTO users (name) VALUES (?)", [name]);
    db.close();

    return Response.json({ success: true });
  },
});

根布局

// app/routes/__root.tsx
import { createRootRoute, Link, Outlet } from "@tanstack/react-router";

export const Route = createRootRoute({
  component: Root,
});

function Root() {
  return (
    <html>
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>我的应用</title>
      </head>
      <body>
        <nav>
          <Link to="/">首页</Link>
          <Link to="/users">用户</Link>
          <Link to="/about">关于</Link>
        </nav>
        <main>
          <Outlet />
        </main>
      </body>
    </html>
  );
}

错误处理

// app/routes/users/$userId.tsx
export const Route = createFileRoute("/users/$userId")({
  loader: async ({ params }) => {
    const response = await fetch(`/api/users/${params.userId}`);
    if (!response.ok) {
      throw new Error("用户未找到");
    }
    return response.json();
  },
  errorComponent: ({ error }) => (
    <div>
      <h1>错误</h1>
      <p>{error.message}</p>
    </div>
  ),
  pendingComponent: () => <div>加载中...</div>,
  component: UserDetail,
});

搜索参数

// app/routes/users/index.tsx
import { createFileRoute } from "@tanstack/react-router";
import { z } from "zod";

const searchSchema = z.object({
  page: z.number().default(1),
  limit: z.number().default(10),
  search: z.string().optional(),
});

export const Route = createFileRoute("/users/")({
  validateSearch: searchSchema,
  loader: async ({ search }) => {
    const { page, limit, search: query } = search;
    // 使用分页获取
    return fetchUsers({ page, limit, query });
  },
  component: Users,
});

部署

为 Bun 构建

NITRO_PRESET=bun bun run build
bun .output/server/index.mjs

Docker

FROM oven/bun:1 AS builder

WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile

COPY . .
RUN bun run build

FROM oven/bun:1

WORKDIR /app
COPY --from=builder /app/.output ./output

EXPOSE 3000

CMD ["bun", ".output/server/index.mjs"]

常见错误

错误 原因 修复
Cannot find bun:sqlite 预设错误 设置 server.preset: "bun"
Server function failed 网络错误 检查函数定义
Route not found 文件命名错误 检查路由文件位置
Hydration mismatch 服务器/客户端差异 检查加载器数据

何时加载参考

加载 references/router-api.md 当：

  • 高级路由模式
  • 路由守卫
  • 嵌套布局

加载 references/forms.md 当：

  • 表单处理
  • 突变
  • 乐观更新