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.