tRPC in Production: Deploy Skew, CSRF and OpenAPI
On this page
The type safety gap: deploy skew
Everything so far assumed the client and server were built from the same code. In production that's only true most of the time. A user opens TaskBoard at 9:00 and leaves the tab open. You deploy at 10:00. Until they reload, their browser runs yesterday's client against today's server. Mobile apps are worse: old versions stay installed for months.
This is deploy skew, and tRPC's types can't see it, because the old client was compiled against the old router. Here's what an old client experienced against a changed server in testing:
server added a required input field -> BAD_REQUEST 400
server removed a procedure -> NOT_FOUND 404 No procedure found on path "legacyStats"
server renamed output field done -> done = undefined (still typed boolean on the old client)The first two fail loudly. The third is the dangerous one: no error, just wrong data, and the old code believes its types.
Evolve procedures safely
Treat a deployed procedure's shape as a contract with every client version still running. These changes are safe:
- adding a new procedure,
- adding an *optional* input field, or one with a
.default(), - adding a new field to the output,
- making a required input field optional.
These are breaking and need a plan:
- removing or renaming a procedure,
- adding a required input field,
- removing or renaming an output field,
- changing a field's type or meaning.
For breaking changes, use the expand and contract approach. First add the new shape alongside the old one, for example a new task.createInProject procedure, or an output that returns both done and completed. Deploy, wait until old clients have aged out, then remove the old shape. For web apps that wait is usually short. You can shorten it by having the client reload when it sees a newer build: send a build id in a response header and compare it in a custom link.
For native mobile clients, which can lag for months, tRPC's lack of versioning becomes a real cost. Many teams give mobile apps a separate versioned API, or keep old procedures alive much longer.
Expose OpenAPI for outside callers
Partners, other teams' services in other languages, and mobile apps outside your repo don't benefit from tRPC's types. Two options turn procedures into an OpenAPI description:
@trpc/openapi, from the tRPC team, generates an OpenAPI document from a router. As of November 2026 it's still published as an alpha, so check its status before you depend on it.trpc-to-openapi, a maintained community package, adds REST-style routes (likeGET /tasks/{id}) to chosen procedures and generates the matching document. The oldertrpc-openapipackage hasn't been updated since 2024 and doesn't support tRPC 11.
Whichever you use, treat the public surface as a separate, versioned API with its own review rules, even if it shares service code with your tRPC procedures.
A production security checklist
Most of these came up earlier in the course. Together they make a short review checklist:
- Validate every input with a schema, with maximum lengths and page sizes (Day 3).
- Default to
protectedProcedure, and check object ownership inside procedures, including subscriptions (Days 4 and 11). - Mask internal error messages in the error formatter, and log the real ones with
onError(Day 5). - Limit request size and batch size on the server, and match the batch size on the client (Day 7).
- Set CORS to your own origin only, or avoid CORS entirely by serving the API from the app's origin (Day 7).
- Rate limit expensive procedures, for example with a middleware that throws
TOO_MANY_REQUESTS. - Keep secrets out of URLs. Query inputs and
connectionParamstravel in the URL and show up in logs.
What about CSRF, if you use cookie sessions? A plain cross-site HTML form can send three content types without a CORS preflight: text/plain, application/x-www-form-urlencoded and multipart/form-data. Here's what tRPC 11.23 did with each in testing:
text/plain -> 415, rejected before any procedure runs
application/x-www-form-urlencoded -> 415, rejected
multipart/form-data, JSON procedure -> 400, the form data fails the Zod object schema
multipart/form-data, FormData procedure (input: z.instanceof(FormData)) -> 200, it ranA JSON request from another site needs a preflight, which a strict CORS policy refuses. So JSON-only procedures are well protected. But a procedure that accepts FormData, typically for file uploads, can be called by a forged form on any website, and the user's cookie goes along with it. For those, and as a second layer everywhere, add a real CSRF defense: require a custom header (such as x-trpc-source) in a middleware, which a plain form can't set, check the Origin header, and use SameSite cookies. Keep queries free of side effects, since they're GET requests. The BFF course goes deeper on cookie security.
Keep types fast as the router grows
Every client file that touches AppRouter asks TypeScript to infer the whole router. With hundreds of procedures and complex Zod schemas, editors can slow down. A few habits keep it fast:
- Give procedures explicit output schemas or return types where inference is deep.
- Avoid huge inline schemas built from many
.merge()and.extend()calls. Name and reuse schemas. - Use TypeScript project references in a monorepo, so the client checks against built
.d.tsfiles rather than re-checking server code. - Measure before guessing:
tsc --extendedDiagnosticsreports check time and type counts.
TypeScript 7's native compiler, which tRPC's own packages now build with, also makes large projects much faster to check.
Capstone: ship TaskBoard
Put the course together by building TaskBoard end to end, then review it against this list:
- A Fastify server with
/healthz, tRPC at/trpc, CORS locked to the app's origin, andmaxBatchSizeset. createContextthat reads the user from a session or token, pluspublicProcedure,protectedProcedureandadminProcedure.- A
taskrouter withlist(cursor pagination),byId,create,toggleandonCreated, each with input schemas and ownership checks. - An error formatter that masks internal errors and returns
fieldErrors, plusonErrorlogging. - Caller-based tests for validation, permissions and the "user A can't see user B's task" rule.
- A React client with the TanStack Query integration, an optimistic toggle with rollback, an infinite list and live updates over SSE.
- A note in the README listing which procedures are safe to change and how breaking changes are rolled out.
If each item works and each test passes, you have a production-shaped tRPC app. The combined course later in this series builds on exactly this setup, adding a BFF and micro-frontends.
AppRouter type from the previous release tag and type-checks it against the current server's router. It catches most breaking changes at review time instead of in production.Check yourself
The old client was compiled against the old router type. At run time it sends old-shaped requests to the new server, and nothing re-checks them against the new types.
Expand and contract: first add it as optional or with a default, deploy, update clients to send it, wait until old clients age out, then make it required.
No. A plain HTML form can post multipart/form-data without a preflight, and the procedure accepts it. Add a CSRF defense such as a required custom header, an Origin check and SameSite cookies.
Adding an optional input field and adding a new procedure are safe, because old clients keep working unchanged. Renaming an output field is breaking: old clients read the old name and get undefined, with no error, while their types still claim the field exists. Add the new field alongside the old one first, and remove the old one later.
Measure first with tsc --extendedDiagnostics to see check time and type counts. Then reduce what TypeScript must infer: give heavy procedures explicit output schemas or return types, name and reuse schemas instead of long chains of .extend(), and use project references so clients check against built declaration files.