Vite + TanStack Start 工程栈

为什么选择这一栈

Vite + TanStack Start 聚焦于极致的开发体验与客户端渲染效率，利用 Vite 的快速启动与热更新，以及 TanStack 系列（Router、Query、Start）提供的文件路由、数据管理和执行模型。本指南结合 SSP UI Registry 的能力，快速搭建具备主题、多语言、数据访问层与工程化保障的现代前端栈。

首次出现的缩写会在括号内说明，方便团队成员对齐概念：

• CSR（Client-Side Rendering）：在浏览器执行渲染逻辑，适合高度交互、即时响应的应用。
• TTRPC（TanStack Router Page Component）：TanStack Start 中通过路由文件定义的页面组件，与 Loader/Action 搭配使用。

技术栈速览

🏗️ 核心框架

🎨 样式与 UI

📦 状态与数据

🛠️ 工程化

🌍 国际化与主题

✨ 增强能力

SSP Registry 能力引用

本栈推荐使用以下 Registry 能力：

栈组成概览

项目初始化与依赖

• 按照 TanStack Start 官方 Quick Start 使用 CLI 或示例仓库创建项目。
• Tailwind CSS v4 默认通过 src/App.css 维护主题与 Design Token，无需额外配置文件。
• 包管理工具依团队规范选择（Bun、pnpm、npm 均可），建议通过 Registry CLI 下载 SSP 能力，避免在文档中硬编码包版本。

样式与主题整合（SSP Theme）

1. 在本站点下载 ssp-style.json，执行后将自动增量更新 src/App.css。
2. 多主题（包括暗色模式）参考 shadcn/ui Vite Dark Mode 实现：
   • 创建 src/components/theme-provider.tsx，基于 Context 管理主题状态
   • 通过 document.documentElement.classList 切换 dark class
   • 将 ssp-style.json 中的变量映射到 :root 与 .dark

UI 与 Block 组件实践

• 通过 shadcn/ui CLI 或其他兼容 Registry 下载基础组件，在 src/components/ui 目录维护。
• 从 SSP UI Registry 引入增强组件或 Block（例如 gh-stargazers-button），用于骨架屏、营销组件等场景。
• 建议建立 src/components/registry.ts 聚合导出常用组件，方便在路由页面与可重用模块中引用。

国际化（react-i18next）

• 参考 react-i18next 官方文档 配置语言资源与 Provider。
• 在 TanStack Start 中，可在 src/app.tsx 或 src/routes/__root.tsx 中包裹 I18nextProvider，并使用 useTranslation Hook 提供文案。
• 建议将语言资源存放于 src/locales/<language>.json，并结合 Loader 在路由加载时注入。

数据访问层：make-api-request + use-cancelable-query

这两个 Registry 能力组合与 TanStack Query 的 Loader API 一起构成数据访问层。详细文档参阅 Make API Request Item。

import { makeApiRequest } from "@/registry/ssp/item/make-api-request/base"
import { ProductApi } from "@/registry/ssp/item/make-api-request/example/index.template"

export const fetchProducts = () => makeApiRequest(ProductApi.getProducts)

import { createFileRoute } from "@tanstack/react-router"
import { useQuery } from "@tanstack/react-query"
import { useCancelableQuery } from "@/hook/use-cancelable-query"
import { fetchProducts } from "@/lib/http/product"

export const Route = createFileRoute("/products")({
  component: ProductsPage,
})

function ProductsPage() {
  const [queryOptions, controller] = useCancelableQuery({
    key: ["products"],
    fetcher: fetchProducts,
  })

  const { data, isLoading, error } = useQuery(queryOptions)

  if (isLoading) return <p>Loading…</p>
  if (error) return <p>Failed to load</p>

  return (
    <div>
      <button onClick={() => controller.abort()}>Cancel request</button>
      <pre>{JSON.stringify(data, null, 2)}</pre>
    </div>
  )
}

use-cancelable-query 可统一错误处理、重试策略与缓存键格式，建议在项目中建立标准化的 Query factory。

状态管理与动效

• zustand：参阅 Zustand Item 文档，在 src/stores 中维护轻量状态，与 TanStack Router 结合可实现全局会话、偏好设置等逻辑。
• motion：在 src/components/motion 中封装动画组件，配合 TanStack Router 的 Transition API 实现页面切换效果。

Schema 校验与类型推导

• 使用 zod 定义表单、接口与配置 Schema，与 make-api-request 结合自动推导类型。
• 在 Loader 与 Action 中引入 Schema 校验，可减少客户端与服务端代码重复。

工程化与质量保障

• 使用 @biomejs/biome 统一 Lint 与格式化，参阅 Biome Item 文档。
• 建议在 package.json 中配置 bun run lint、bun run format，并在 Vite pre-commit 或 CI/CD 流程中执行。
• Vite 插件生态可按需引入（如 vite-tsconfig-paths、@tanstack/router-vite-plugin），保持项目结构清晰。

部署与运维建议

1. 托管平台：TanStack Start 支持在 Netlify、Vercel、Cloudflare Workers 等平台部署。参考官方部署指南配置构建命令与输出目录，确保 SSR/Edge 功能与缓存策略正常工作。
2. 容器化（Dockerize）：自托管时可使用多阶段 Dockerfile 打包 Vite/TanStack Start 应用，流程与 Next.js 类似：
   • 使用 Node 18+/Bun 基础镜像；
   • 安装依赖并执行 vite build 或 tanstack dev build；
   • 将输出的 .output（或自定义 SSR 产物）复制到运行镜像；
   • 配置运行脚本为 node .output/server/index.mjs 或 bun .output/server/index.mjs。

   具体 Dockerfile 可结合团队模板或 Registry Item 扩展，本节留作后续补充实际示例。

Checklist

• 已应用 SSP Theme 并验证明暗主题切换。
• 常用 UI、Block、Hook、Item 能力已通过 Registry 引入。
• make-api-request + use-cancelable-query 建立标准数据访问层。
• 国际化策略（如 react-i18next）已完成配置并通过官方示例验证。
• Biome 与 Zod 校验纳入 CI/CD 流程。
• Page Transition、重点交互已使用 motion 定义动效。
• 目标平台部署验证通过，并评估容器化部署方案。

完成以上步骤后，即可获得一套高性能、可扩展、同时具备主题与国际化能力的 Vite + TanStack 工程栈，为各类客户端驱动的业务场景提供扎实基座。