@trpc/server/skills/trpc-router/SKILL.md

The tRPC server library

---
name: trpc-router
description: "Entry point for all tRPC skills. Decision tree routing by task: initTRPC.create(), t.router(), t.procedure, createTRPCClient, adapters, subscriptions, React Query, Next.js, links, middleware, validators, error handling, caching, FormData, OpenAPI, multiple services. Includes a minimal working server and client."
sources:
  - www/v11/docs/skills.md
  - www/v11/docs/quickstart.md
metadata:
  type: core
  library: trpc
  library_version: 11.23.0
---

<!-- Generated from www/v11/docs/skills.md by www/build/skills.ts. Edit the docs instead. -->

# Agent Skills

> Set up and use TanStack Intent to provide AI agent skills for tRPC

From https://trpc.io/docs/skills

tRPC ships [TanStack Intent](https://tanstack.com/intent/latest/docs/getting-started/quick-start-consumers) skills to help AI coding agents work with tRPC. When your agent works on a task that matches a skill, it loads the skill's `SKILL.md` into context.

The skills ship inside `@trpc/server`, `@trpc/client`, `@trpc/tanstack-react-query`, `@trpc/next` and `@trpc/openapi`, so they're already in your `node_modules`.

## Setup

### 1. Run install

The `install` command adds skill-loading guidance to your agent's config file (`AGENTS.md`, `CLAUDE.md`, etc.):

```bash
npx @tanstack/intent@latest install
```

It covers the skills shipped in tRPC and your other installed packages.

### 2. Use skills in your workflow

When your agent works on a task that matches a skill, it loads the corresponding `SKILL.md` into context to guide implementation.

To see which skills are available:

```bash
npx @tanstack/intent@latest list
```

To load one yourself, for example the server auth skill:

```bash
npx @tanstack/intent@latest load @trpc/server#auth
```

### 3. Keep skills up-to-date

Skills version with library releases. When you update tRPC (e.g. `npm update @trpc/server`), you get the skills that match your installed version.

## Skills by task

Each skill is generated from a page of these docs. Load one with `npx @tanstack/intent@latest load <skill>`, for example `npx @tanstack/intent@latest load @trpc/server#server-setup`.

### Build the API

| Task | Skill |
| --- | --- |
| Initialize tRPC, define routers, procedures and context, export `AppRouter` | [`@trpc/server#server-setup`](https://trpc.io/docs/server/overview) |
| Add middleware and reusable base procedures | [`@trpc/server#middlewares`](https://trpc.io/docs/server/middlewares) |
| Validate inputs and outputs with Zod or another library | [`@trpc/server#validators`](https://trpc.io/docs/server/validators) |
| Throw, format and handle errors | [`@trpc/server#error-handling`](https://trpc.io/docs/server/error-handling) |
| Authenticate users and protect procedures | [`@trpc/server#auth`](https://trpc.io/docs/server/authorization) |
| Call procedures from server code or tests | [`@trpc/server#server-side-calls`](https://trpc.io/docs/server/server-side-calls) |
| Set HTTP cache headers on responses | [`@trpc/server#caching`](https://trpc.io/docs/server/caching) |
| Accept `FormData`, files and binary inputs | [`@trpc/server#non-json-content-types`](https://trpc.io/docs/server/non-json-content-types) |
| Stream real-time updates over SSE or WebSockets | [`@trpc/server#subscriptions`](https://trpc.io/docs/server/subscriptions) |
| Send `Date`, `Map`, `Set` and other rich types with superjson | [`@trpc/client#superjson`](https://trpc.io/docs/server/data-transformers) |
| Split the API across several services | [`@trpc/server#service-oriented-architecture`](https://trpc.io/docs/server/service-oriented-architecture) |

### Serve the API

| Task | Skill |
| --- | --- |
| Node.js HTTP server, the simplest setup | [`@trpc/server#adapter-standalone`](https://trpc.io/docs/server/adapters/standalone) |
| Express | [`@trpc/server#adapter-express`](https://trpc.io/docs/server/adapters/express) |
| Fastify | [`@trpc/server#adapter-fastify`](https://trpc.io/docs/server/adapters/fastify) |
| AWS Lambda behind API Gateway or a Function URL | [`@trpc/server#adapter-aws-lambda`](https://trpc.io/docs/server/adapters/aws-lambda) |
| Fetch API and edge runtimes: Cloudflare Workers, Deno, Vercel Edge, Astro, Remix | [`@trpc/server#adapter-fetch`](https://trpc.io/docs/server/adapters/fetch) |

### Call the API

| Task | Skill |
| --- | --- |
| Create a TypeScript client, infer types, handle errors | [`@trpc/client#client-setup`](https://trpc.io/docs/client/vanilla/setup) |
| Configure links: batching, streaming, splitting, WebSockets, SSE, retries | [`@trpc/client#links`](https://trpc.io/docs/client/links) |
| Use tRPC with TanStack React Query | [`@trpc/tanstack-react-query#react-query-setup`](https://trpc.io/docs/client/tanstack-react-query/setup) |
| Migrate from the classic `@trpc/react-query` client | [`@trpc/tanstack-react-query#react-query-classic-migration`](https://trpc.io/docs/client/tanstack-react-query/migrating) |
| Next.js App Router, including server components | [`@trpc/next#nextjs-app-router`](https://trpc.io/docs/client/nextjs/app-router-setup) |
| Next.js Pages Router, SSR and SSG | [`@trpc/next#nextjs-pages-router`](https://trpc.io/docs/client/nextjs/pages-router/setup) |
| Generate an OpenAPI spec and a REST client | [`@trpc/openapi#openapi`](https://trpc.io/docs/openapi) |

## Learn more

For full documentation on TanStack Intent, see the [Quick Start for Consumers](https://tanstack.com/intent/latest/docs/getting-started/quick-start-consumers) guide.

## Serving the API

Now that we have defined our router, we can serve it. tRPC has first-class [adapters](https://trpc.io/docs/server/adapters) for many popular web servers. To keep it simple, we'll use the [`standalone`](https://trpc.io/docs/server/adapters/standalone) Node.js adapter here.

```ts no-check title="server/index.ts"
import { createHTTPServer } from '@trpc/server/adapters/standalone';
import { appRouter } from './appRouter';

const server = createHTTPServer({
  router: appRouter,
});

server.listen(3000);
```

<details>
<summary>See the full backend code</summary>

```ts no-check title="server/trpc.ts"
import { initTRPC } from '@trpc/server';

const t = initTRPC.create();

export const router = t.router;
export const publicProcedure = t.procedure;
```

<br/>

```ts no-check title="server/appRouter.ts"
import { z } from "zod";
import { publicProcedure, router } from "./trpc";

type User = { id: string; name: string };

export const appRouter = router({
  userList: publicProcedure
    .query(async () => {
      const users: User[] = [{ id: '1', name: 'Katt' }];
      return users;
    }),
  userById: publicProcedure
    .input(z.string())
    .query(async (opts) => {
      const { input } = opts;
      const user: User = { id: input, name: 'Katt' };
      return user;
    }),
  userCreate: publicProcedure
    .input(z.object({ name: z.string() }))
    .mutation(async (opts) => {
      const { input } = opts;
      const user: User = { id: '1', ...input };
      return user;
    }),
});

export type AppRouter = typeof appRouter;
```

<br/>

```ts no-check title="server/index.ts"
import { createHTTPServer } from "@trpc/server/adapters/standalone";
import { appRouter } from "./appRouter";

const server = createHTTPServer({
  router: appRouter,
});

server.listen(3000);
```

</details>

From https://trpc.io/docs/quickstart#serving-the-api

## Using your new backend on the client

Let's now move to the client-side code and embrace the power of end-to-end typesafety. When we import the `AppRouter` type for the client to use, we have achieved full typesafety for our system without leaking any implementation details to the client.

### 1. Setup the tRPC Client

```ts no-check title="client/index.ts"
import { createTRPCClient, httpBatchLink } from '@trpc/client';
import type { AppRouter } from '../server/appRouter';
//     👆 **type-only** imports are stripped at build time

// Pass AppRouter as a type parameter. 👇 This lets `trpc` know
// what procedures are available on the server and their input/output types.
const trpc = createTRPCClient<AppRouter>({
  links: [
    httpBatchLink({
      url: 'http://localhost:3000',
    }),
  ],
});
```

Links in tRPC are similar to links in GraphQL, they let us control the data flow to the server. In the example above, we use the [httpBatchLink](https://trpc.io/docs/client/links/httpBatchLink), which automatically batches up multiple calls into a single HTTP request. For more in-depth usage of links, see the [links documentation](https://trpc.io/docs/client/links).

### 2. Type Inference & Autocomplete

You now have access to your API procedures on the `trpc` object. Try it out!

```ts no-check title="client/index.ts"
// Inferred types
const user = await trpc.userById.query('1');

const createdUser = await trpc.userCreate.mutate({ name: 'Katt' });
```

You can also use your autocomplete to explore the API on your client

```ts no-check title="client/index.ts"
trpc.u;
```

From https://trpc.io/docs/quickstart#using-your-new-backend-on-the-client