tRPC + Next.js + Prisma Starter 项目实战指南：基于官方示例快速搭建类型安全全栈应用

tRPC Next.js Prisma Starter 项目实战指南基于官方示例快速搭建类型安全全栈应用【免费下载链接】trpc‍♀️ Move Fast and Break Nothing. End-to-end typesafe APIs made easy.项目地址: https://gitcode.com/GitHub_Trending/tr/trpc本文以 tRPC 仓库中 Next.js 示例项目索引文档 starter-projects.md 为主线系统讲解 tRPC 官方提供的三个可快速启动的样板项目——next-prisma-starter、next-prisma-todomvc与 zART-stack。读完本文你将掌握如何借助这些 Starter 在几分钟内拉起一套带数据库、E2E 测试、环境变量校验的全栈类型安全应用并能读懂官方样板背后「Prisma 模型 → tRPC Router → Next.js API Handler → 前端类型化 Hooks」的完整调用链。一、文档定位与仓库对应关系该 Starter Projects 页面是 tRPC v9.x 文档中面向 Next.js 用户群的示例索引它不重复讲解某条 API而是将「可运行、可复制」的完整示例打包成一张表格供使用者快速克隆。索引的examples/目录在 tRPC 主仓库内被长期维护详见 examples/next-prisma-starter 与 examples/next-prisma-todomvc。需要注意一点starter-projects.md属于版本化历史快照而examples/中的同名项目会随 tRPC 主线持续升级。例如当前 next-prisma-starter/package.json 已使用 Next 15、React 19、Prisma 6 与 tRPC 新版trpc/next、trpc/client等均指向npm:trpc/*最新 tag客户端链接也演进为httpBatchStreamLink。因此下文在完整继承文档结论的同时对代码细节均以仓库当前实际源码为准进行解读。二、官方提供的三个 Starter 项目一览下面将文档中的示例索引表完整整理如下在线演示与外部源码托管地址因不在当前仓库内故不展开链接可直接在本仓库对应目录查看实现项目说明技术要点本仓库对应路径Next.js Prisma Starter集成 Prisma、E2E 测试与 ESLint 的 Next.js 样板全栈类型安全、Cursor 分页、CI、环境变量校验examples/next-prisma-starterzART-stackzero-API TypeScript React 的 Monorepo 示例同时包含 React Native、Next.js 与 Prisma独立外部仓库不在本仓库内Next.js TodoMVC基于 SSG 与 Prisma 的 TodoMVC 示例静态生成、经典 Todo 应用examples/next-prisma-todomvc三者的定位差异明显next-prisma-starter 是完整度最高的工程化样板含测试、Lint、CI适合作为真实业务起点next-prisma-todomvc 是聚焦型演示SSG 一个经典交互模型适合学习 Next.js 静态生成与 tRPC 的组合zART-stack则演示多端复用同一套类型化 API 的 Monorepo 拓扑适合 React Native 与 Web 共用后端的场景。三、next-prisma-starter生产级全栈样板的深度拆解这是三个 Starter 中最值得精读的一个。官方 READMEexamples/next-prisma-starter/README.md将其特性概括为E2E 类型安全tRPC、Next.js 全栈 React、Prisma 数据库、ESLint Prettier、基于 GitHub Actions 的 CIPlaywright E2E Lint以及「在构建/启动时校验环境变量」。3.1 运行前提与快速启动该样板对环境的要求只有两点来自其 READMENode.js 18.0.0一个可连接的 PostgreSQL 数据库文档建议通过create-next-app的 example 机制从 tRPC 主仓库的examples/next-prisma-starter路径拉取模板生成新项目。无论以何种方式获得源码在同一目录内完成安装与启动的命令如下pnpm # 安装依赖postinstall 会自动执行 prisma generate pnpm dx # 启动本地 Postgres 迁移 种子数据 开发服务器dx是开发者体验Developer Experience命令通过npm-run-all并行编排可拆解为两条子命令见 package.jsondx:next先migrate-dev再db-seed随后启动next dev与dx:prisma-studio打开 Prisma Studio 可视化查看数据。3.2 常用脚本速查表从 package.json 可以直接获得一套完整的项目脚本语义脚本执行内容pnpm dev等价于dx:next跑迁移、种子后启动 Next.js 开发服务器pnpm dx并行启动 Next.js 开发服务器与 Prisma Studiopnpm buildprebuildprisma generateprisma migrate后执行next buildpnpm startnext start启动生产服务器pnpm db-resetprisma migrate dev reset重置本地数据库pnpm db-seedprisma db seed写入种子数据pnpm migrate-dev/pnpm migrate开发迁移 / 生产部署迁移pnpm lintESLint 检查src目录pnpm test-unitVitest 运行单元测试pnpm test-e2ePlaywright 运行端到端测试pnpm test-start顺序执行全部单元 E2E 测试pnpm typechecktsc --noEmit静态类型检查值得注意的两个细节postinstall会自动执行prisma generate保证新克隆环境首次pnpm后客户端类型即可用prebuild会在每次正式构建前自动完成迁移避免「构建成功但数据库结构过期」的经典事故。3.3 文件结构与关键路径路径职责prisma/schema.prisma数据模型定义Post 表prisma/migrations迁移记录src/server/context.ts请求级 Context 创建src/server/trpc.tstRPC 服务端初始化根配置src/server/env.ts环境变量运行时校验src/server/routers/_app.ts根路由聚合与类型导出src/server/routers/post.ts业务 Router 示例含单元测试src/pages/api/trpc/[trpc].tsNext.js 与 tRPC 的 HTTP 桥接层src/utils/trpc.ts客户端类型化 Hooks 工厂src/utils/transformer.ts数据传输序列化器3.4 数据层Prisma 模型与迁移数据模型 prisma/schema.prisma 定义了数据源为 PostgreSQL、客户端生成器为prisma-client-js业务上仅一个Post模型idUUID 主键、title、text、createdAt与updatedAt。源码注释揭示了两条重要设计意图createdAt具有唯一性价值被用作**游标分页cursor-based pagination**的排序与游标依据为了让Date对象经 API 往返后仍保持类型完整必须引入序列化器superjson这正是transformer配置存在的理由。3.5 环境变量在启动前被强制校验样板在src/server/env.ts用 zod 定义 schemaDATABASE_URL必须为合法 URLNODE_ENV必须属于development | test | production随后用safeParse(process.env)校验——失败即抛错并打印格式化后的错误明细成功则导出解析后的强类型env。源码注释说明该文件被 Next 配置文件引用从而做到构建/启动即失败避免带着错误的数据库地址进入线上。3.6 Context 的内外分层设计context.ts 实现了 tRPC 官方推荐的拆分模式createContextInner(opts)纯数据上下文创建函数不依赖 Next.js 的 request/response 对象因此在单元测试、server-side calls 中可以直接调用createContext(opts: trpcNext.CreateNextContextOptions)HTTP 请求入口内部直接委托createContextInner。从源码结构看这样拆分的好处是让服务端调用caller与 HTTP 请求共享同一套上下文装配逻辑是 tRPC「同一套 Router 可同时服务 HTTP 与进程内调用」能力的基础。3.7 服务端根配置初始化一次、按需导出trpc.ts 是服务端唯一调用initTRPC的位置并刻意只导出会被使用的工厂函数从而约束团队只能使用受控的 procedure 基类。其核心配置包括transformersuperjson与自定义errorFormatter此处原样透传 shape。样板还预先导出了router、publicProcedure、mergeRouters、createCallerFactory——当项目需要新增鉴权中间件时通常就是在此文件扩展出一个protectedProcedure。3.8 业务 Routerzod 校验 Cursor 分页 错误语义根路由 _app.ts 聚合了healthcheck与postRouter两个子路由并导出createCaller基于createCallerFactory与AppRouter类型——后者是前后端类型连接的枢纽。postRouterpost.ts是理解 tRPC 输入输出约定的最佳范本包含三种典型形态分页列表list输入用 zod 声明limit1~100可空与cursor可空字符串。实现上通过take: limit 1多取一条判断是否还有下一页多出的那条被pop()出来作为nextCursor最终返回items内部再reverse()保证按createdAt倒序与nextCursor。这是前端useInfiniteQuery的标准契约格式。详情查询byId输入仅id查询不到时通过throw new TRPCError({ code: NOT_FOUND, ... })返回具有业务语义的错误码而非裸 500——这正是 tRPC 错误体系见 packages/server 的TRPCError的典型用法。创建addmutation中执行prisma.post.create。注意输入校验使用了.string().uuid().optional()处理可选 UUID.min(1).max(32)约束标题从而让非法请求在进入数据库前就被拦截。所有查询都显式传入defaultPostSelect白名单只回传明确声明的字段避免向客户端泄露多余数据。3.9 HTTP 桥接Next.js API Handlersrc/pages/api/trpc/[trpc].ts 是整个应用的唯一 API 路由文件通过createNextApiHandler装配appRouter与createContext并在onError回调中只对INTERNAL_SERVER_ERROR输出日志便于接入错误上报。文件末尾以注释形式预留了responseMeta()——当需要基于请求条件设置缓存响应头时tRPC API Response Caching在此启用即可。3.10 客户端类型化 Hooks 与 baseUrl 解析src/utils/trpc.ts 通过createTRPCNextAppRouter, SSRContext生成强类型 Hooks客户端配置的要点如下getBaseUrl()按运行环境解析服务端地址浏览器内返回空串优先读取VERCEL_URL与RENDER_INTERNAL_HOSTNAME等平台变量最后回落到http://127.0.0.1:PORT兼容多平台部署loggerLink仅在开发环境或「下行响应是 Error」时打印日志避免生产日志噪音httpBatchStreamLink指向${getBaseUrl()}/api/trpc实现请求批量合并其headers()回调在 SSR 场景会把客户端请求头含 Cookie转发给服务端——源码注释特别提醒若运行 Node 18.15 之前版本需剔除connection头顶层ssr: false关闭服务端渲染数据预取同时SSRContext类型扩展了 Next 的NextPageContext允许在需要时通过utils.ssrContext.status 404干预 HTTP 状态码。序列化方面transformer.ts 统一从 superjson 导出transformer并注释鼓励若需支持Decimal.js、Temporal等类型在此扩展后客户端与服务端引用同一实例即可两端生效。3.11 测试体系单元 E2E 双轨样板对测试的重视体现在两个层面。单元测试层面Router 目录内直接放置 post.test.ts配合test-unitvitest独立验证业务逻辑无需启动真实 HTTP 服务。E2E 层面playwright.config.ts 声明testDir: ./playwright、webServer在 CI 下用npm run start、本地用npm run dev并设置 CI 重试 3 次与githubreporter 以生成 Actions 注解smoke.test.ts 给出了两个最小冒烟用例首页加载后等待textStarter出现以及填写表单创建一条随机标题的 Post 并刷新后仍能读到该标题——后一个用例实际上完整验证了「写入数据库 → tRPC 返回 → 页面重新渲染」的闭环。四、next-prisma-todomvcSSG 场景的最小闭环演示第二个可直接在本仓库查看的 Starter 是 TodoMVC 实现examples/next-prisma-todomvc。官方文档将其定位为Next.js SSG Prisma的经典 Todo 应用。相比上一节的全功能样板它的价值在于用最小代码量演示静态生成页面如何消费 tRPC 数据。其运行命令为pnpm create next-app --example 官方仓库 --example-path examples/next-prisma-todomvc trpc-todo cd trpc-todo pnpm pnpm dev获取源码后在本仓库examples/next-prisma-todomvc目录执行pnpm pnpm dev即可本地运行pnpm dx则同时拉起 Prisma Studio。从目录结构看它保留了与上一节一致的分层习惯prisma/schema.prisma与prisma/migrations负责数据层src/server共 6 个 TypeScript 文件承载 Router 与 Contextsrc/utils承载类型化客户端工具页面侧则加入了过滤路由src/pages下的 filter 页面。它同时保留了与 Playwright 的 E2E 测试test/playwright.test.ts与 playwright.config.ts并额外附带vercel.json、next.config.js等部署相关配置便于一键托管到边缘平台。如果你需要理解「SSG 预渲染页面 客户端 hydration 后通过 tRPC 取数」的完整节奏这个 Starter 比全功能样板更易读。五、zART-stack跨端 Monorepo 参考文档索引的第三个示例 zART-stack 是一个独立维护的外部项目未包含在当前仓库中。其名字是 zero-API TypeScript React 的缩写组合核心亮点是用一个 Monorepo 同时编排 React Native 与 Next.js 两个前端并共享同一套基于 Prisma 的 tRPC 后端。对于「API 一次定义、多端复用」的诉求这个示例展示了如何在共享类型边界之上组织 workspace需要提醒的是它不在本仓库examples/目录内若想将其作为业务脚手架应直接以文档所列方式克隆其独立源码仓库使用。六、如何基于 Starter 开启你自己的项目结合三个示例的源码落地一个全新项目时的推荐动作如下决定骨架追求工程完整度选next-prisma-starterexamples/next-prisma-starter想先跑通最小闭环再看 SSG 选next-prisma-todomvcexamples/next-prisma-todomvc需要多端复用再参考 zART-stack 的 Monorepo 拓扑。改造数据层编辑prisma/schema.prisma扩展业务模型然后执行prisma migrate dev生成迁移——两个 Starter 都内置了迁移目录作为起点。扩展 Router仿照 post.ts在src/server/routers下新增业务 Router并在根路由 _app.ts 中聚合同一套代码即可被 HTTP 与createCaller双通道复用。保持客户端同步新增过程后无需手写任何请求层代码——src/utils/trpc.ts中的类型化 Hooks 会随AppRouter类型自动推导出新过程的入参与出参。补测试与校验沿 post.test.ts 的思路补 Router 单测沿 smoke.test.ts 的「表单创建→刷新断言」模式补关键路径的 E2E 用例并在src/server/env.ts中为每个新增环境变量加上 zod 约束。七、小结官方 Starter Projects 索引starter-projects.md提供了三个不同粒度的起点next-prisma-starter把「类型安全、分页、迁移、环境变量校验、单测与 E2E」完整集成到一个 Next.js 应用中是最值得作为生产基座的参考实现next-prisma-todomvc以最小代码量阐释 SSG 与 Prisma 的组合zART-stack 则打开了多端复用的视野。结合 examples/next-prisma-starter 目录下的真实源码逐文件对照阅读你不仅能快速搭建应用更能理解 tRPC 全栈类型安全从模型定义、Router 声明到前端 Hooks 是如何一环扣一环地传递下去的。【免费下载链接】trpc‍♀️ Move Fast and Break Nothing. End-to-end typesafe APIs made easy.项目地址: https://gitcode.com/GitHub_Trending/tr/trpc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考