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
npx skills add oakoss/agent-skills --skill trpc -a claude-codeWhat 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-queryhooks toAppRouterand write procedure tests.
How to install trpc
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill trpc -a claude-code2Manually: put the files in place
~/.claude/skills/trpc/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/trpc/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill trpc -a codex2Manually: put the files in place
.agents/skills/trpc/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill trpc -a cursor2Manually: put the files in place
.cursor/skills/trpc/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install oakoss/agent-skills skills/trpc2Manually: put the files in place
.github/skills/trpc/SKILL.md1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill trpc -a gemini-cli2Platform CLI
gemini skills install https://github.com/oakoss/agent-skills --path skills/trpcManually: put the files in place
.devin/skills/trpc/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill trpc -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.