tRPC v11

The decisions tRPC forces and how to settle them, written so an agent applies them while writing or reviewing code. Every rule names the wrong default it corrects; there is no rule for what the model already gets right.

Pinned to tRPC v11, verified against 11.18.0 (2026-06-17). There is no v12 — but several APIs here carry @deprecated … will be removed in v12 and still ship today. Peers: typescript >=5.7.2, @tanstack/react-query ^5.80.3, react >=18.2.0.

When to Apply

Use this skill when:

• Code imports initTRPC, createTRPCContext, createTRPCOptionsProxy, createTRPCReact, createTRPCClient, httpBatchLink, httpSubscriptionLink, splitLink, fetchRequestHandler, createCallerFactory, or TRPCError — or defines procedures with .input() / .output() / .use() / .query() / .mutation() / .subscription()
• The user says "everything types as any", "invalidation isn't working", "contextMap[utilName] is not a function", "the transformer property moved", "414 / 413 on the dashboard", "subscriptions won't connect", "the prefetch isn't hydrating", or "it 404s every procedure"
• Migrating a codebase from tRPC v10, or reviewing tRPC code written against v10-era examples — the highest-yield moment, because the recommended React client changed and stale code often still compiles
• Adding the first subscription, the first file upload, or the first RSC prefetch to an existing router — each crosses into a surface where v11 replaced the v10 approach outright
• Reviewing a batched client as the app grows, where the uncapped defaults turn into intermittent production failures

This skill is NOT for:

• General TanStack Query semantics — cache lifetimes, retry, useMutation ergonomics (→ tanstack-query)
• Authoring or migrating the Zod schemas used as validators (→ zod)
• Next.js App Router routing, streaming, or caching beyond the tRPC handler (→ nextjs)
• General TypeScript narrowing and generics (→ typescript)

Rule Categories

Quick Reference

1. React Client Surface

• client-tanstack-integration — Build React data fetching on @trpc/tanstack-react-query; createTRPCReact is now the classic path
• client-invalidate-with-query-filters — useUtils() does not exist on the new proxy; invalidate via queryClient + pathFilter() / queryFilter()
• client-derive-query-keys — getQueryKey() is not on the new proxy; keys come off it as queryKey() / pathKey() / infiniteQueryKey()
• client-subscription-options — .useSubscription() is not on the new proxy; feed subscriptionOptions() to useSubscription from @trpc/tanstack-react-query

2. v10 → v11 Drift

• mig-formdata-is-native — All six experimental_* upload APIs were removed; FormData is a native input behind a splitLink
• mig-renamed-type-exports — AnyRouter → AnyTRPCRouter and friends; inferRouterInputs/Outputs did not change
• mig-await-get-raw-input — rawInput is undefined; inputs are lazy, so await getRawInput()
• mig-typescript-version-floor — TS >=5.7.2, and an editor on a different TS silently types everything as any

3. Router & Procedure Construction

• proc-narrow-ctx-in-middleware — Bare next() leaves ctx.user nullable, so the guard gets cast away with !
• proc-input-before-use — .use() before .input() runs middleware against unvalidated input
• proc-single-trpc-instance — One initTRPC.create() per app; mismatched instances make mergeRouters throw at runtime
• proc-merge-only-object-inputs — Only object schemas merge; anything else silently replaces the earlier parser
• proc-concat-over-standalone-middleware — experimental_standaloneMiddleware is deprecated and cannot declare .input(); use .concat()

4. Error & Validation Semantics

• err-format-standard-schema-issues — Parser dispatch is ordered, so a Zod-only errorFormatter returns null for Valibot / Effect (StandardSchemaV1Error) and for ArkType (ArkErrors)
• err-output-strips-fields — .output() returns the parsed value, so it strips unknown keys; its failure is a 500, not a 4xx
• err-nullish-cursor — .optional() cursors 400 only after an invalidate; use .nullish()
• err-set-isdev-explicitly — Without an explicit isDev, edge runtimes ship error.data.stack to every client

5. Links, Transport & Serialization

• link-transformer-on-terminating-links — The transformer moved into the link; deleting it to clear the branded type error breaks Date at runtime
• link-route-subscriptions-separately — httpBatchLink rejects subscription operations outright
• link-cap-batch-size — maxItems and maxURLLength default to Infinity; pair them with the server's maxBatchSize
• link-gate-cache-headers — Batching plus blanket responseMeta caching lets a CDN serve one user's data to another
• link-default-to-httpbatchlink — httpBatchStreamLink cannot set response headers once streaming; it is not the default
• link-read-batch-headers-from-oplist — Batch links pass { opList }, not { op }; destructuring wrong makes every request 401
• link-scope-body-parsers — A global express.json() drains the stream before tRPC reads it
• link-endpoint-matches-mount-path — endpoint is the prefix tRPC strips; a mismatch 404s every procedure

6. SSR, RSC & Server-Side Calls

• rsc-query-client-per-request — A module-scope QueryClient serves one user's cache to the next request
• rsc-dehydrate-pending-queries — Without the pending override, void prefetchQuery never reaches the client
• rsc-prefetch-through-options-proxy — Caller results never enter the cache, so the client fetches it all again
• rsc-share-logic-not-callers — A nested caller re-creates context and re-runs the whole middleware chain

7. Subscriptions & Streaming

• sub-write-async-generators — observable() is deprecated for removal, and only generators get tracked() reconnect-and-resume
• sub-keep-credentials-out-of-urls — connectionParams serializes tokens into the query string, and into every log that sees it
• sub-enable-sse-keepalive — ping.enabled is false by default, so idle SSE streams get reaped by proxies and read as a flaky network
• sub-attach-listener-before-backlog — Fetching history before attaching the listener drops events only under production load

How to Use

Read a reference file when its decision comes up. Each rule names the wrong default it corrects, then shows the canonical way — with an incorrect/correct contrast only where the wrong way is a real trap.

Two shortcuts worth taking first:

• Reviewing or migrating existing tRPC code? Start with client- and mig-. Stale code frequently still compiles, so nothing points you at these; they are what everything else inherits.

• Hardening something already working? The security-shaped rules are link-gate-cache-headers, rsc-query-client-per-request, err-set-isdev-explicitly, proc-input-before-use, and sub-keep-credentials-out-of-urls.

• Section definitions — category structure and ordering rationale

• Rule template — for adding new rules

• AGENTS.md — auto-built table of contents across all rules

Related Skills

• tanstack-query — The query layer tRPC's React client now delegates to; owns cache semantics this skill assumes
• zod — Validator authoring and Zod 4 drift, including the .flatten() → z.treeifyError() change this skill only points at
• typescript — General type-level work beyond tRPC's inference surface