# Add Response Caching to a tRPC API

Yes. An agent adds Cache-Control headers to your tRPC API's public queries through responseMeta, keeps mutations and streamed batches uncached, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-response-caching/trpc/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how requests reach the router before it adds a header. In an app laid out like trpc/examples-next-prisma-starter, `src/pages/api/trpc/[trpc].ts` calls `trpcNext.createNextApiHandler` with `router`, `createContext` and an `onError` that logs internal errors, and carries a commented-out `responseMeta()` with a link to the caching docs. `src/server/routers/_app.ts` has a `healthcheck` query and the `post` router from `post.ts`: `list` (a cursor-paged query), `byId` and the `add` mutation. `src/utils/trpc.ts` builds the client with `loggerLink` and `httpBatchStreamLink`, sets `ssr: false`, and keeps `queryClientConfig` with a `staleTime` commented out. `src/pages/index.tsx` runs `post.list` through `useInfiniteQuery` and invalidates it after `add`; `src/pages/post/[id].tsx` runs `post.byId`. The dependencies are the `canary` tRPC packages, `next ^15.5.25` and `@tanstack/react-query ^5.80.3`, and `.github/workflows/main.yml` runs `pnpm build`, the Playwright smoke test and `pnpm tsc` against a Postgres service.

Two properties of this client decide the design. First, batching: one HTTP request can carry `post.list` and `post.byId` together, and a header applies to the whole response, so any cache header must be the strictest of all paths in the batch, and a batch that includes a mutation or `healthcheck` gets none. Second, streaming: `httpBatchStreamLink` asks for a streamed response, and tRPC's `ResponseMetaFn` receives `eagerGeneration: true` when, in its own words, the meta is being generated without knowing the response data, which is the streamed case. Headers go out before any procedure has run, so `errors` is empty whether or not something fails. The agent therefore refuses to cache when `eagerGeneration` is true, and in `trpc.ts` adds a `splitLink` that sends cacheable queries over a plain `httpBatchLink` and everything else over the stream link, so the cacheable requests are the non-streamed ones.

What is cacheable is a short, explicit list, not a keyword. The docs' example checks for `public` in the path name; this router's procedures are all `publicProcedure` without the word in their paths, so the agent writes `src/server/responseMeta.ts` with a map from path to max-age: `post.byId` gets a long `s-maxage` with `stale-while-revalidate`, because the app has no procedure that edits a post, and `post.list` gets none, because `index.tsx` adds a post and immediately refetches the list, and a CDN serving a stale list would make the Playwright `add a post` step flaky behind one. The function takes `info` (the deprecated `paths` is kept out), `type`, `errors` and `eagerGeneration`, returns `{}` unless every path is in the map, `type` is `query`, there are no errors and generation is not eager, and otherwise returns `cache-control: public, s-maxage=<min>, stale-while-revalidate=<min>` over the batch.

The function is pure, so it gets a Vitest file beside it: one batch of `post.byId` gets the header, a batch mixing `post.byId` and `post.list` gets nothing, an eager call gets nothing, a mutation gets nothing, and an error in `errors` gets nothing. For the wire, the agent runs `pnpm build` and `next start` in the sandbox and shows `curl -i` against `/api/trpc/post.byId?input=...` with the header present and `/api/trpc/post.list` and a `post.add` POST without it. It also sets the commented `staleTime` in `trpc.ts` for the browser-side cache of `byId`, runs `pnpm lint`, `pnpm typecheck` and the Playwright smoke test, and documents the list of cached paths in a README section.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add HTTP response caching to the public queries of this tRPC and Next.js app. Read package.json, src/pages/api/trpc/[trpc].ts, src/server/routers/_app.ts, src/server/routers/post.ts, src/server/context.ts, src/utils/trpc.ts, src/pages/index.tsx, src/pages/post/[id].tsx, playwright/smoke.test.ts and .github/workflows/main.yml first. Add src/server/responseMeta.ts with a map from procedure path to max-age, caching post.byId and not post.list, healthcheck or any mutation; return a public s-maxage and stale-while-revalidate header only when every path in the batch is in the map, type is query, errors is empty and eagerGeneration is false, using the minimum max-age across the batch. Wire it as responseMeta in the Next API handler. In src/utils/trpc.ts add a splitLink that sends the cacheable queries over httpBatchLink and everything else over httpBatchStreamLink, and set a staleTime for the React Query client. Add Vitest tests for the function covering a cacheable batch, a mixed batch, an eager call, a mutation and an error. Build and start the app, show curl -i output for a cached and an uncached route, run lint, typecheck and the Playwright smoke test, and open a pull request that quotes the output and lists the cached paths in the README.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request adds `src/server/responseMeta.ts` and its test, and changes `src/pages/api/trpc/[trpc].ts` (the `responseMeta` wiring), `src/utils/trpc.ts` (the `splitLink` and `staleTime`) and `README.md`. Its description quotes the Vitest and Playwright output and the two `curl -i` responses, so a reviewer sees the exact `cache-control` value on `post.byId` and its absence on `post.list` and `post.add`.

A reviewer checks the max-age for `post.byId` against how posts are actually edited in their deployment (the starter has no edit procedure; an app that gains one should shorten it or invalidate), that no cached procedure reads a cookie or an `Authorization` header, since a shared cache would serve one user's answer to another, and that the `splitLink` condition names the same paths as the server map, since the two must agree for the client to get non-streamed responses on exactly those calls.

Mutations, `healthcheck` and `post.list` behave as before. A deployment with no CDN in front sees the header and ignores it; one behind Vercel, Cloudflare or CloudFront, which the tRPC docs name as honouring standard cache headers, starts serving `post.byId` from the edge.

## Run it on every new public query

The list of cached paths goes stale the moment someone adds a query, so the useful check is on the pull request that adds one. An automation on the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` runs read-only with a prompt that compares the procedures in `src/server/routers` with the map in `responseMeta.ts` and the `splitLink` condition, and comments when a new query is in neither, or in one but not the other. The event the trigger adds names the pull request; the prompt itself has no placeholder.

A handler on your own server that reads that comment can send this body to `POST /o/{org}/sessions` with the new procedure's path appended to the prompt and the pull request's branch in `resources` as `https://github.com/your-org/your-app/tree/<branch>`, with a `request_id` that is a UUID v5 of the head SHA so a redelivery returns the run it already started. That run pushes a commit to the branch, and the key's `webhook_url` gets `run.completed`.

## Why run it on Rush?

A cache header is invisible in the test suite and only shows up as the wrong answer in production, which is why the agent builds the app, starts it and reads the headers off the wire in its own sandbox. The `curl -i` output and the Playwright run stay in the run's record, so a reviewer checks the header value rather than the intent.

The streaming and batching rules are the same for every tRPC service, and so is the mistake of caching a batch that includes a private query. One run per repository reads that service's links and routers, writes its own path map, and opens one pull request each, so a team's APIs end up with the same conservative rules rather than one service caching a session-bound query by accident.

## Frequently asked questions

### Why not cache post.list too?

The index page adds a post and refetches the list straight away, and the Playwright smoke test reloads and expects the new post. A CDN holding the list for even a short `s-maxage` would show a stale page after a write. Lists that change on user action are better invalidated than cached; `post.byId` has no writer in this app, so it is safe.

### What does eagerGeneration change?

With a streamed response the headers are written before any procedure runs, so `responseMeta` cannot know whether a call failed. The agent returns no cache header when the flag is true and routes the cacheable queries over a non-streaming link, so for them the meta is computed with the results known.

### Does batching break it?

It would if the header ignored it. One HTTP response carries every procedure in the batch, so the function caches only when all of them are in the map and uses the shortest max-age among them. The `splitLink` keeps cacheable and uncacheable calls in separate requests, so mixed batches are rare in practice.

### Is this safe with a logged-in user?

Only for procedures that read no user state. The starter's context is empty and its procedures are all public, so the map is safe as written. An app that adds sessions must keep every session-bound query out of the map, and the README section the agent writes says so.

### Does it work without a CDN?

The header is still set, and the browser honours `s-maxage` only through a shared cache, so a direct `next start` behaves as before. The `staleTime` the agent sets on the React Query client is what cuts repeat fetches in the browser itself.

## More tRPC jobs

- [Add Soft Delete to a tRPC and Prisma App](https://getrush.ai/run/add-soft-delete/trpc/)
- [Prefetch tRPC Queries on the Server in a Next.js Pages Router App](https://getrush.ai/run/add-ssr-prefetching/trpc/)
- [Add Structured Logging to a tRPC API](https://getrush.ai/run/add-structured-logging/trpc/)

## The same job on other stacks

- [Add Response Caching to a Fiber App](https://getrush.ai/run/add-response-caching/fiber/)
- [Add Response Caching to a Litestar App](https://getrush.ai/run/add-response-caching/litestar/)
- [Add HTTP Response Caching to a Slim 4 App](https://getrush.ai/run/add-response-caching/slim/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
