基于 TanStack Start 的极简全栈启动模板，前后端一体

方案简介

cove 是一个面向 TanStack Start 的极简启动模板（starter stack），目标是让开发者快速搭建一个现代 React 全栈应用。前端采用 React + TanStack Start/Router/Query，样式与组件层为 Tailwind CSS + shadcn/ui + Base UI，数据层为 Drizzle ORM + PostgreSQL，部署层通过 Vite Plus + Nitro 支持 Netlify、Vercel、Node.js 等多种部署预设。适合想以 TanStack Start 为骨架启动新项目的全栈开发者。

亮点与能力

• 完整的 React + TanStack Start 全栈起点，内置 Router 与 Query
• Tailwind CSS + shadcn/ui + Base UI 组件与样式体系，可用 shadcn CLI 添加组件（如 vpr ui add button）
• Drizzle ORM + PostgreSQL 数据层，drizzle-kit 生成并应用迁移
• Varlock 管理环境变量契约并生成类型
• evlog 通过 Nitro 输出每请求一条结构化日志
• Better Auth 认证及服务端函数/API 路由鉴权中间件示例
• Vitest 单元/集成测试与 Playwright 端到端测试
• 明暗主题切换组件

组成与分工

• React：UI 框架
• TanStack Start：全栈框架骨架
• TanStack Router / Query：类型安全路由与服务端状态管理
• Tailwind CSS + shadcn/ui + Base UI：样式与组件层
• Drizzle ORM：PostgreSQL 数据访问与迁移
• Vite Plus + Nitro：构建工具链与部署适配
• Varlock：环境变量契约与类型生成
• evlog：结构化请求日志
• Better Auth：认证方案

前置要求

• Node.js >= 24
• pnpm >= 12
• Vite Plus (vp)
• PostgreSQL 数据库

实施步骤

1. 创建项目

使用 GitHub 模板或 CLI 创建：
bash
pnpm create cove

2. 配置环境变量

根据 .env.schema 创建 .env.local 并填入你的值，然后校验：
sh
vpr env:load

3. 生成并应用数据库迁移

sh
vpr db generate
vpr db migrate

4. 启动开发服务器

bash
vpr dev

开发服务器将运行在 http://localhost:3000。

使用与配置要点

• 环境变量：代码中用 import { ENV } from "varlock/env" 而非直接读 process.env；本地密钥放在不提交的 .env.local。
• 日志：evlog 每请求输出一条结构化事件，生产需要时可添加 drain 接入日志服务商。
• 认证：修改 Better Auth 配置后运行 auth:generate 重新生成 auth db schema。
• 升级依赖：版本被锁定，可用 vpr deps 或 vpx taze@latest -Ilw --maturity-period 3 选择性升级。
• 检查代码：vpr check 同时运行 Oxfmt 与 Oxlint。
• 测试：vpr test、vpr test watch、vpr test:e2e。

注意事项与常见问题

• TanStack Start 处于 RC，TanStack Devtools 处于 alpha 且可能有破坏性变更。
• 模板默认配置为 Nitro v3 beta。
• Drizzle ORM v1 处于 RC（relations v2），Vite+ 处于 beta。
• 依赖版本被锁定，创建项目时可能略旧。
• 测试基础较轻量，短期原型可安全忽略或移除。

优缺点

• ✓ 开箱即用的极简全栈栈
• ✓ Vite Plus 统一脚本工具链
• ✕ 多个依赖处于 RC/alpha/beta

出处

本方案挖掘自开源项目 mugnavo/cove，方案内容与实施命令均来自其 README 原文。