Back to Details

trpc-tanstack-nextjs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

tRPC + TanStack Query + Next.js App Router

tRPC + TanStack Query + Next.js App Router

End-to-end typesafe APIs for Next.js using tRPC v11 with 
@trpc/tanstack-react-query
adapter.
使用tRPC v11和
@trpc/tanstack-react-query
适配器，为Next.js打造端到端类型安全的API。

Core Setup

核心配置

  • setup
    - Full setup from scratch with all modules
  • routers
    - Creating routers, procedures, middleware
  • client-usage
    - Queries, mutations, useUtils in client components
  • server-usage
    - Prefetching, hydration, getCaller in server components
  • setup
    - 从零开始完整配置所有模块
  • routers
    - 创建路由、过程、中间件
  • client-usage
    - 在客户端组件中使用查询、变更、useUtils
  • server-usage
    - 在服务器组件中进行预获取、水合、getCaller调用

Optional Integrations

可选集成

  • better-auth-integration
    - Add session/user to tRPC context with Better Auth
  • optimistic-updates
    - Update UI before server confirms
  • infinite-queries
    - Cursor-based pagination
  • subscriptions
    - WebSocket real-time updates
  • better-auth-integration
    - 通过Better Auth将会话/用户信息添加到tRPC上下文
  • optimistic-updates
    - 在服务器确认前更新UI
  • infinite-queries
    - 基于游标分页
  • subscriptions
    - WebSocket实时更新

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:
references/setup.md
references/routers.md
references/client-usage.md
Each reference file contains:
  • Code examples with imports
  • Usage patterns
  • Common variations
阅读各个参考文件获取详细说明和代码示例：
references/setup.md
references/routers.md
references/client-usage.md
每个参考文件包含：
  • 带导入语句的代码示例
  • 使用模式
  • 常见变体

Common Gotchas

常见问题

  1. Cookies not sent - Add 
    credentials: "include"
    to httpBatchLink fetch
  2. Hydration mismatch - Ensure superjson transformer on both client and server
  3. staleTime: 0 - Causes refetch on every mount; use 30s+ for most cases
  4. Missing HydrateClient - Prefetched data won't transfer to client
  5. cache() not used - getCaller/getQueryClient must be wrapped in React cache()
  1. Cookie未发送 - 在httpBatchLink的fetch配置中添加
    credentials: "include"
  2. 水合不匹配 - 确保客户端和服务器端都使用superjson转换器
  3. staleTime: 0 - 会导致每次挂载时重新获取数据；大多数场景建议设置为30秒以上
  4. 缺少HydrateClient - 预获取的数据无法传递到客户端
  5. 未使用cache() - getCaller/getQueryClient必须包裹在React的cache()中

Resources

资源