tRPC setup: complete developer guide (2026)

tRPC gives a TypeScript client end-to-end types without generating a schema or a client. It is a strong fit when one team owns the frontend and backend; it is a poor fit for public APIs or clients you do not control.

What matters in practice

• Input schemas validate at runtime; the inferred type flows to the client.
• For Next.js App Router, call the server caller on the server and use the client only for interactive leaves.

How to implement it

1. Define the context. Create the request-scoped dependencies once.
2. Create the router. Start with one feature and a small procedure set.
3. Add input schemas. Validate every input with Zod.
4. Protect procedures. Use middleware for authentication and authorisation.
5. Wire the client. Use the recommended Next.js integration and a single provider.
6. Test the procedure. Call it directly with a test context and cover permission failures.

A working example

import { initTRPC, TRPCError } from "@trpc/server";
const t = initTRPC.context<Context>().create();
export const protectedProcedure = t.procedure.use(({ ctx, next }) => {
if (!ctx.session) throw new TRPCError({ code: "UNAUTHORIZED" });
return next({ ctx: { ...ctx, session: ctx.session } });
});
export const postRouter = t.router({
bySlug: protectedProcedure
.input(z.object({ slug: z.string().min(1) }))
.query(({ ctx, input }) => ctx.db.post.findUnique({ where: { slug: input.slug } })),
});

Production checklist

Area	Check
Context	Database, session and request metadata created once
Validation	Zod input on every procedure
Auth	Protected procedures and object-level checks
Errors	Typed TRPC errors, no leaking internals
Caching	Server-side caller and query keys where appropriate
Observability	Logging and tracing around slow procedures

Common mistakes

• Using tRPC for a public API that third parties must call.
• Putting authorisation only in the UI.
• Creating a new database client per procedure call.
• Exposing a procedure that returns more fields than the client needs.

When this is the wrong tool

Every tool has a boundary. If the team is small, the use case is simple and the operational cost is high, a simpler stack may be better. The right choice is the one you can debug, secure and hand over without the original author.

Rollout plan

1. Prove one slice. Use tRPC for one real route or feature, not the whole product.
2. Set the boundary. Write down what stays on the server, what runs on the client and how data crosses the boundary.
3. Add the safety net. Types, validation, tests and error handling around the new slice.
4. Measure. Check bundle size, latency, error rate and the developer experience before expanding.
5. Document and hand over. Record the pattern, the pitfalls and the version constraints.

Testing strategy

Layer	What to test	Why
Types	Strict compile and no unjustified any	Catches contract drift early
Unit	Pure logic, validation and state transitions	Fast feedback
Integration	API, database and auth boundaries	Most production failures live here
End-to-end	The critical user journey	Proves the wiring
Operations	Logs, errors, retries and rollback	A release is not finished at deploy

Operational checklist

• Pin the runtime and dependency versions; test upgrades in a branch.
• Keep secrets on the server and validate every external payload.
• Add structured logs with a request ID, but never log tokens or personal data.
• Set a performance or bundle budget and check it in CI.
• Write a short runbook for the most likely failure.

Sources and further reading

• tRPC documentation (trpc.io)
• Zod documentation (zod.dev)
• Next.js server and client components (nextjs.org)

Related reading

• TypeScript best practices
• Next.js deployment guide
• Web application development