trpc-tanstack-nextjs

Set up tRPC with TanStack Query in Next.js App Router projects.

Updated Aug 15, 2025
One-click install
npx skills add https://github.com/yehezkieldio/topaz --skill trpc-tanstack-nextjs-yehezkieldio
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: trpc-tanstack-nextjs
Source: https://github.com/yehezkieldio/topaz/tree/main/.agents/skills/trpc-tanstack-nextjs
Command: npx skills add https://github.com/yehezkieldio/topaz --skill trpc-tanstack-nextjs-yehezkieldio

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @trpc/server, @trpc/client, @trpc/tanstack-react-query, @tanstack/react-query, superjson, zod, ws, and includes references (resource) components.

What problem does it solve? Building end-to-end typesafe APIs in Next.js requires wiring together tRPC, TanStack Query, React Server Components, and authentication, which involves many error-prone configuration steps and subtle pitfalls like hydration mismatches and missing cookie credentials. ## Core Features & Use Cases - Full Setup Guidance: Covers context creation, QueryClient factory, client provider, server helpers, root router, and the API route handler for tRPC v11 with the @trpc/tanstack-react-query adapter. - Router and Procedure Patterns: Shows how to create routers, queries, mutations, protected and admin procedures, Zod input/output validation, and nested routers. - Advanced Data Patterns: Includes prefetching and hydration in Server Components, optimistic updates, infinite cursor-based queries, WebSocket subscriptions, and Better Auth session integration. - Use Case: When adding a new feature to a Next.js app, use this Skill to scaffold a typesafe tRPC router with a protected mutation, then consume it in a client component with automatic cache invalidation. ## Quick Start Ask the AI to set up tRPC with TanStack Query in your Next.js App Router project from scratch, including the provider, server helpers, and a sample router.

Frequently Asked Questions about trpc-tanstack-nextjs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I set up tRPC with TanStack Query in Next.js App Router?▼

Install @trpc/server, @trpc/client, @trpc/tanstack-react-query, @tanstack/react-query, superjson, and zod, then create the context, QueryClient factory, client provider, server helpers, root router, and a fetch adapter route handler at /api/trpc.

How do I prefetch tRPC queries in React Server Components?▼

Use the prefetch helper with trpc queryOptions inside an async server component, then wrap client children in HydrateClient so the dehydrated QueryClient state transfers to the browser without a loading flash.

Why are cookies not sent with tRPC requests from the client?▼

The default httpBatchLink fetch does not include credentials. Pass a custom fetch to httpBatchLink that spreads the options and sets credentials to "include" so session cookies reach the API route.

Can I use Better Auth sessions inside tRPC procedures?▼

Yes. Call auth.api.getSession with the request headers inside createTRPCContext, then build a protectedProcedure middleware that throws UNAUTHORIZED when no session user exists and narrows the context type.

Why does my tRPC hydration mismatch or lose prefetched data?▼

Hydration fails when the superjson transformer is missing on either client or server, when HydrateClient is omitted, or when getQueryClient is not wrapped in React cache(), causing a fresh empty cache per request.

How do I add real-time subscriptions to a tRPC Next.js app?▼

Define subscription procedures returning observables, run a separate ws server with applyWSSHandler, and configure the client with splitLink so subscription operations use wsLink while queries and mutations use httpBatchLink.