tRPC v11 with Next.js 15: full-stack type safety guide

Both provide typed API layers, but their approaches differ fundamentally. GraphQL defines a schema using its own type language (SDL), requires code generation to produce TypeScript types from the schema, and is designed for flexibility in client queries — clients can request exactly the fields they need. tRPC has no schema language — TypeScript types are inferred directly from procedure definitions — requires no code generation, and uses fixed input/output shapes per procedure. GraphQL is better for multi-client APIs (multiple frontend apps, mobile apps, third-party integrations) and scenarios where clients need flexible query composition. tRPC is better for single-client full-stack TypeScript applications where the simplicity of direct type inference outweighs GraphQL's flexibility benefits.

Yes — tRPC is framework-agnostic on both server and client. Server-side adapters exist for Express, Fastify, Hono, AWS Lambda, and any fetch-compatible runtime. Client-side, the vanilla tRPC client works without React Query and can be used with any framework including Vue, Svelte, and React without Next.js. The Next.js integration provides conveniences (App Router compatibility, SSR helpers) but is not required. The most common non-Next.js pairing is Express backend with React (non-Next.js) frontend in a monorepo, or Hono on Cloudflare Workers with a React SPA client.

tRPC is not designed for file uploads — its JSON serialisation layer doesn't handle multipart form data. The recommended pattern is to use tRPC to generate a pre-signed upload URL (for S3 or similar object storage) which the client then uses to upload the file directly to storage via a separate fetch call, bypassing tRPC entirely. This pattern is actually superior to uploading through an API server for large files — it avoids buffering file data through your application server and provides direct client-to-storage transfer performance. Implement a getUploadUrl tRPC procedure that generates and returns the pre-signed URL, and handle the actual file upload outside of tRPC.

tRPC client overhead is minimal — approximately 12KB gzipped for the client package, with procedure calls making standard HTTP requests indistinguishable from REST API calls at the network level. Request batching (combining multiple concurrent calls into one HTTP request) can improve performance versus un-batched REST. The primary performance consideration is that tRPC uses POST for queries by default, which prevents HTTP caching; tRPC v11 adds support for GET requests for query procedures, enabling CDN and browser caching for appropriate endpoints. For RSC usage with the server caller, there is zero network overhead — it's a direct function call.

NextAuth v5 (Auth.js) integrates with tRPC through the context creation function. In your tRPC context creator, call auth() from NextAuth to retrieve the current session and include it in the returned context object. Protected procedures access ctx.session and throw UNAUTHORIZED if absent. For Next.js App Router, use the NextAuth v5 auth() export directly in both the tRPC context creator and RSC components — both use the same session source. This pattern provides consistent authentication across both client-side tRPC calls (via context) and RSC-rendered server caller invocations.

Server Actions are designed for form mutations — they integrate natively with HTML forms, work without JavaScript, and have excellent progressive enhancement properties. tRPC is better for complex client-side data fetching, real-time features via subscriptions, non-form mutations requiring optimistic updates, and any scenario requiring explicit loading and error state management via React Query. The two approaches complement each other in the same Next.js application: use Server Actions for simple form submissions and tRPC for complex data interactions. Choosing exclusively one or the other often results in using the wrong tool for some use cases — most mature Next.js 15 applications use both where appropriate.

tRPC procedures are ordinary TypeScript functions and can be tested directly using the server-side caller without HTTP infrastructure. Use createCallerFactory(appRouter)(mockContext) to create a test caller with a mocked context (mock session, test database client), then call procedures directly as async functions. This approach tests procedure logic including middleware and validation without network overhead. For integration testing with HTTP, use tRPC's createHTTPServer with a test HTTP client (supertest or native fetch) to test the full HTTP layer. Type safety from the TypeScript compiler catches many bugs before tests run, reducing the number of tests needed compared to dynamically typed API implementations.

The T3 Stack is an opinionated full-stack TypeScript setup combining Next.js, tRPC, TypeScript, Prisma (ORM), Tailwind CSS, and NextAuth, scaffolded by the create-t3-app CLI. It is the most widely adopted starting point for tRPC-based applications and reflects community consensus on how these technologies work well together. For teams new to tRPC or building a standard CRUD application, T3 is an excellent starting point — it handles boilerplate configuration and demonstrates best practices for the technology combination. Teams with specific requirements that diverge from T3 defaults (different ORM, different auth library, non-Next.js framework) should use T3 as reference architecture rather than the scaffolded output, adapting the patterns to their stack rather than fighting T3's assumptions.