All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading