Skip to main content
skill CX Codex

trpc · oakoss — Claude Code skill: features and installation

trpc is a Claude Code skill for building type-safe TypeScript APIs with tRPC v11. It comes into play when working on routers, procedures, React clients, or tests.

MIT 109 installs ★ 29 updated 2026-08-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill trpc -a claude-code
Open on GitHub

What trpc does

The skill covers tRPC v11 routers and procedures, Zod input checks, middleware, request context, subscriptions, and errors handled with TRPCError. Its React section uses @trpc/react-query hooks; server-side calls use createCallerFactory.

It also covers standalone, Express, Fastify, and Hono adapters, client links, and procedure tests. The examples pass types through AppRouter without code generation. This approach does not fit public APIs consumed by non-TypeScript clients; the documented alternatives are REST and GraphQL.

What it helps with

  • Define typed tRPC routers and procedures
  • Validate procedure inputs with Zod
  • Pass request context through middleware
  • Connect a React app to tRPC
  • Test procedures and error handling

Example prompts for the agent

  • Build a tRPC v11 router with a profile query and Zod input validation.
  • Add authorization middleware and expose the user through procedure context.
  • Connect @trpc/react-query hooks to AppRouter and write procedure tests.

How to install trpc

1Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill trpc -a claude-code

2Manually: put the files in place

~/.claude/skills/trpc/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/trpc/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about trpc

How do I install trpc in Claude Code?

Run npx skills add oakoss/agent-skills --skill trpc -a claude-code. The skill file will be at ~/.claude/skills/trpc/SKILL.md.

What does trpc do?

It guides work on type-safe TypeScript APIs with tRPC v11, including routers, validation, React clients, adapters, and tests.

Can trpc be used for a public API with non-TypeScript clients?

The described approach shares TypeScript types between server and client. For public APIs consumed by non-TypeScript clients, the documentation points to REST or GraphQL.

Source text

SKILL.md · MIT
---
name: trpc
description: |
  tRPC v11 end-to-end type-safe APIs for TypeScript. Covers router and procedure definitions, input validation with Zod, middleware and context, subscriptions, error handling with TRPCError, React client hooks via @trpc/react-query, server-side callers with createCallerFactory, adapter setup (standalone, Express, Fastify, Hono), and testing patterns.

  Use when building tRPC routers, defining procedures, setting up middleware, configuring adapters, integrating tRPC with React, handling errors, implementing subscriptions, or testing tRPC procedures.
license: MIT
metadata:
  author: oakoss
  version: '1.0'
  source: 'https://trpc.io/docs'
user-invocable: false
---

# tRPC

## Overview

tRPC enables end-to-end type-safe APIs by sharing TypeScript types between server and client without code generation or schemas. The server defines procedures (queries, mutations, subscriptions) in a router, and the client infers all types from the exported `AppRouter` type.

**When to use:** TypeScript full-stack apps needing type-safe API layers, monorepos sharing types, real-time subscriptions, rapid API iteration without OpenAPI/GraphQL overhead.

**When NOT to use:** Public APIs consumed by non-TypeScript clients (use REST/GraphQL), polyglot backends, projects requiring OpenAPI spec generation as primary output.

## Quick Reference

| Pattern               | API                                        | Key Points                                              |
| --------------------- | ------------------------------------------ | ------------------------------------------------------- |
| Initialize            | `initTRPC.context<Ctx>().create()`         | Single entry point, configure once                      |
| Router                | `t.router({ ... })`                        | Nest routers with `t.mergeRouters()`                    |
| Query                 | `t.procedure.input(schema).query(fn)`      | Read operations, cached by clients                      |
| Mutation              | `t.procedure.input(schema).mutation(fn)`   | Write operations                                        |
| Subscription          | `t.procedure.subscription(fn)`             | Real-time via WebSocket or SSE                          |
| Middleware            | `t.middleware(fn)`                         | Chain with `.use()`, extend context via `next({ ctx })` |
| Standalone middleware | `experimental_standaloneMiddleware<{}>()`  | Reusable with explicit type constraints                 |
| Context               | `createContext({ req, res })`              | Per-request, passed to all procedures                   |
| Server caller         | `t.createCallerFactory(router)`            | Type-safe server-side procedure calls                   |
| Error                 | `throw new TRPCError({ code, message })`   | Mapped to HTTP status codes                             |
| Error formatter       | `initTRPC.create({ errorFormatter })`      | Customize error shape, expose Zod errors                |
| Input validation      | `.input(zodSchema)`                        | Multiple `.input()` calls merge (intersection)          |
| Output validation     | `.output(zodSchema)`                       | Strip extra fields from responses                       |
| React hooks           | `trpc.useQuery()` / `trpc.useMutation()`   | Built on @tanstack/react-query                          |
| React utils           | `trpc.useUtils()`                          | Invalidate, prefetch, setData on cache                  |
| Suspense query        | `trpc.useSuspenseQuery()`                  | Suspense-compatible data fetching                       |
| React subscription    | `trpc.useSubscription(input, opts)`        | `onData` callback for real-time events                  |
| Vanilla client        | `createTRPCClient<AppRouter>({ links })`   | No React dependency                                     |
| Batch link            | `httpBatchLink({ url })`                   | Batches requests in single HTTP call                    |
| Stream link           | `httpBatchStreamLink({ url })`             | Streams responses as they resolve                       |
| WS link               | `wsLink({ client: wsClient })`             | WebSocket transport for subscriptions                   |
| Split link            | `splitLink({ condition, true, false })`    | Route operations to different transports                |
| Logger link           | `loggerLink()`                             | Debug request/response in development                   |
| Data transformer      | `initTRPC.create({ transformer })`         | Serialize Dates, Maps, Sets (superjson)                 |
| Fetch adapter         | `fetchRequestHandler({ endpoint, req })`   | Cloudflare Workers, Deno, Bun, Next.js                  |
| Procedure chaining    | `publicProcedure.use(auth).use(rateLimit)` | Build reusable procedure bases                          |

## Common Mistakes

| Mistake                                             | Correct Pattern                                                                |
| --------------------------------------------------- | ------------------------------------------------------------------------------ |
| Exporting the full `t` object                       | Export only `t.router`, `t.procedure`, `t.middleware`, `t.createCallerFactory` |
| Creating context inside procedure                   | Create context in adapter setup, flows through automatically                   |
| Using `any` for context type                        | Define context type with `initTRPC.context<MyContext>().create()`              |
| Catching errors in procedures                       | Let errors propagate; use `onError` in adapter or error formatter              |
| Importing server code on client                     | Import only `type AppRouter`, never runtime server code                        |
| Using `createCaller` in production request handlers | Use `createCallerFactory` for type-safe reusable callers                       |
| Defining input without validation                   | Always validate with Zod, Valibot, or ArkType schemas                          |
| Nesting routers incorrectly                         | Use dot notation in keys or `t.mergeRouters()`, not deep nesting               |
| Different transformers on client/server             | Both sides must use the same transformer (e.g., superjson)                     |
| Creating QueryClient inside component render        | Create once outside component or use useState initializer                      |
| Manual TypeScript generics on hooks                 | Type the router procedures; let inference propagate to client                  |
| Not passing `signal` to fetch in queryFn            | tRPC React handles abort signals automatically                                 |

## Installation

```bash
pnpm add @trpc/server @trpc/client @trpc/react-query @tanstack/react-query zod
```

For subscriptions, add `ws` (server) and configure `wsLink` (client). For SSE-based subscriptions, use `httpBatchStreamLink` instead.

## Delegation

- **Procedure discovery**: Use `Explore` agent
- **Router architecture review**: Use `Task` agent
- **Code review**: Delegate to `code-reviewer` agent

> If the `tanstack-query` skill is available, delegate query/mutation caching, invalidation, and optimistic update patterns to it.
> If the `zod-validation` skill is available, delegate input schema design and validation patterns to it.
> If the `drizzle-orm` skill is available, delegate database query patterns within procedures to it.
> If the `vitest-testing` skill is available, delegate test runner configuration and assertion patterns to it.
> If the `hono` skill is available, delegate Hono framework routing and middleware patterns to it.

## References

- [Router and procedure definitions](references/router-procedures.md)
- [Middleware and context patterns](references/middleware-context.md)
- [Error handling and formatting](references/error-handling.md)
- [React client integration with @trpc/react-query](references/react-integration.md)
- [Server-side callers and vanilla client](references/server-callers.md)
- [Adapter setup for standalone, Express, Fastify, and Hono](references/adapter-setup.md)
- [Subscriptions and real-time patterns](references/subscriptions.md)
- [Testing tRPC procedures](references/testing-patterns.md)

© oakoss · MIT · oakoss/agent-skills

Similar skills

All skills for Backend and APIs →

trpc by other authors comes first.

trpc Mindrally trpc is a Claude Code skill for building Next.js apps with end-to-end typesafe APIs in tRPC v11. It guides work on routers, procedures, and client-server setup. CX Codex +1 911installs trpc bobmatnyc trpc is a Claude Code skill for building end-to-end type-safe TypeScript APIs with React Query. It activates for tRPC work and related implementation tasks. CX Codex +1 259installs trpc-expert 0xfurai trpc-expert — a Claude subagent that builds tRPC backends: routers, shared types, middleware. Useful when server and client drift apart on types. CX Codex ★ 1,029repo stars nodejs-backend bobmatnyc The nodejs-backend skill guides TypeScript backend work with Express or Fastify. Use it for REST APIs, routing, middleware, validation, and database integration. CX Codex +1 307installs orval pproenca 42 prioritized rules for generating type-safe TypeScript clients from OpenAPI specs with Orval. Helps configure hooks, custom mutators, and MSW mocks. CX Codex +1 347installs deno-typescript Mindrally deno-typescript is a Claude Code skill with development guidelines for Deno and TypeScript, covering project structure, built-in tools, permissions, and Deno KV or Hono setups. CX Codex +1 801installs bun-hono-integration secondsky bun-hono-integration — a skill that tells the agent how to build Hono APIs on Bun: routes, middleware, Zod validation, RPC client. Useful when your project already runs on Bun. CX Codex +1 473installs hono-validation bobmatnyc hono-validation — a skill for validating Hono requests: JSON bodies, forms, query params, headers and cookies. Useful when you want schema types inside the handler. CX Codex +1 427installs

From the same set106

The whole set →
hono Guides coding agents in building lightweight APIs, middleware pipelines, and RPC servers using the Hono framework. CX Codex +1 112installs astro Feeds the agent Astro patterns: content collections, island hydration, view transitions, rendering modes. Useful when most pages are static with a few interactive parts. CX Codex +1 111installs db-enforcer db-enforcer is a Claude Code skill that checks PostgreSQL integrity and alignment with Prisma. It activates for schema design, migration work, and RLS policy setup. CX Codex +1 109installs electricsql Briefs your coding agent on ElectricSQL: streaming slices of Postgres to the client through Shapes, plus the proxy and write patterns around it. CX Codex +1 109installs tauri This Claude Code skill covers Tauri v2 apps with web frontends and Rust backends. It activates for project setup, IPC, permissions, or app releases. CX Codex +1 108installs turborepo This Claude Code skill helps configure Turborepo in JavaScript and TypeScript monorepos. Use it to set up task pipelines, caching, package filters, and CI workflows. CX Codex +1 108installs realtime-sync realtime-sync guides agents through designing low-latency sync using WebTransport, CRDT conflict resolution, and batched AI token streaming. CX Codex +1 108installs plan-first-development The plan-first-development Claude Code skill structures project planning and tracks progress across sessions. It activates for new projects, major features, and work split into phases. CX Codex +1 107installs

Project sponsors

Companies that keep this analytics open