All jobs

Add Health Check Endpoints to a tRPC and Next.js App

Yes. An agent adds liveness and readiness routes to your tRPC app's Next.js API, with the readiness one checking Prisma, plus tests and a CI step, in 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 what the app already answers before adding routes, because a tRPC app usually has a health procedure that looks like a health check and is not one. In an app laid out like trpc/examples-next-prisma-starter, src/server/routers/_app.ts defines healthcheck: publicProcedure.query(() => 'yay!') beside the post router; it is served through src/pages/api/trpc/[trpc].ts, so a probe would have to call /api/trpc/healthcheck and parse a tRPC envelope, and it touches nothing, so it says only that the process is up. src/server/prisma.ts keeps one PrismaClient on globalThis outside production and logs queries in development; src/server/env.ts validates DATABASE_URL and NODE_ENV with Zod at import time, and next.config.ts imports it so a build fails without them. prisma/schema.prisma has one Post model on Postgres. package.json runs Next 15 with React 19, @trpc/server from the canary tag, Prisma 6 and Zod 4, with test-unit as vitest, test-e2e as playwright test, prebuild as prisma generate plus prisma migrate deploy, and typecheck as tsc --noEmit. vitest.config.mts loads dotenv/config and excludes playwright/; src/server/routers/post.test.ts calls the router through createCaller against the real database, and .github/workflows/main.yml gives both its jobs a Postgres service.

The agent adds two Pages Router API routes, src/pages/api/health/live.ts and src/pages/api/health/ready.ts, outside the tRPC handler, so a load balancer or Kubernetes probe gets a plain JSON body and status with no envelope. live answers 200 with {"status": "ok"} and the process uptime and never touches Prisma, because a liveness probe that fails on a database outage restarts a healthy process. ready calls a new checkDatabase in src/server/health.ts, which runs prisma.$queryRaw with SELECT 1 raced against a short timeout, and answers 200 with {"status": "ok", "database": "ok"} or 503 with the failure named, so traffic stops reaching an instance whose database is gone. Both routes set Cache-Control: no-store. The healthcheck procedure stays as it is, since the client may use it.

For tests, src/server/health.test.ts follows post.test.ts: it calls checkDatabase with the real prisma client, which the unit job's Postgres service makes possible in CI, and once more with a stub whose $queryRaw rejects, asserting the first is ok and the second names the error and respects the timeout. playwright/health.test.ts requests both routes from the running app in the e2e job and asserts the status codes and bodies, which also checks that the routes are reachable outside the tRPC path. README.md gets a short section naming the two routes and which one a probe should call.

In its sandbox the agent runs pnpm install, starts Postgres, runs pnpm prebuild with the DATABASE_URL from .env, then pnpm test-unit, pnpm typecheck, pnpm build and pnpm test-e2e, and finally starts the app and requests both routes with curl, once with the database up and once after stopping it, pasting the four responses into the pull request.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add health check endpoints to this tRPC and Next.js app. Read package.json, src/server/routers/_app.ts, src/server/prisma.ts, src/server/env.ts, src/pages/api/trpc/[trpc].ts, src/server/routers/post.test.ts, vitest.config.mts, playwright/smoke.test.ts, prisma/schema.prisma, .env, next.config.ts and .github/workflows/main.yml first. Add two Pages Router API routes under src/pages/api/health: live, which answers 200 and touches nothing, and ready, which runs SELECT 1 through the Prisma client with a timeout and answers 503 when it fails; put the database check in src/server/health.ts and leave the tRPC healthcheck procedure as it is. Write a Vitest test in the style of post.test.ts that runs the check against the real database and against a stub whose $queryRaw rejects, and a Playwright test that requests both routes. Document the routes in README.md. In your sandbox start Postgres, run pnpm prebuild, test-unit, typecheck, build and test-e2e, then start the app and curl both routes with the database up and then down, and open a pull request with the output. Change no router or procedure.",
  "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/pages/api/health/live.ts, src/pages/api/health/ready.ts, src/server/health.ts, src/server/health.test.ts and playwright/health.test.ts, and changes README.md. Its description shows the four curl responses with their status codes, the Vitest and Playwright output, and the typecheck and build results.

Both routes answer plain JSON outside the tRPC handler. The post router, the healthcheck procedure, the Prisma client setup, the environment validation and the two CI jobs in main.yml are unchanged; the jobs run the new tests because they already run test-unit and test-e2e with a Postgres service.

Before merging, a reviewer decides which route the platform's probes call and at what interval, whether readiness should also cover anything the app depends on beyond Postgres, and whether the timeout in checkDatabase fits the database's usual latency.

Run it on every service without a health route

A team with several Next.js and tRPC services sends this body once per repository to POST /o/{org}/sessions, each with its own repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started instead of opening a second pull request. Each run reads its own app: one on the App Router gets route handlers under app/api/health/ instead of Pages Router files, one on Drizzle gets its check written against that client, and one that already answers /api/health gets that route reviewed and the second one added beside it.

A webhook_url on the key reports each run.completed with the pull request in result, and a run.failed names a service whose tests did not pass before the change, which is worth knowing on its own.

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

Why run it on Rush?

Two routes are a small change, but the details decide whether probes help or hurt: a liveness route that queries the database, a readiness route hidden inside the tRPC envelope, a check with no timeout that hangs the probe, a cached 200. The agent reads how the app serves requests and where the Prisma client lives, puts the routes where a probe can reach them, and shows the responses with the database up and down from its own sandbox.

The curl output, the tests and the build stay with the run and are repeated in the pull request, so the review is about what readiness should mean here. Several services can get the same two routes at once, each in its own framework's shape.

Frequently asked questions

Is the existing healthcheck procedure not enough?

It answers yay! through the tRPC handler, so a probe would call /api/trpc/healthcheck and parse the envelope, and it never touches the database. It is fine as a client-side ping and stays. The two new routes are plain HTTP, one for liveness and one that checks Prisma, which is what a load balancer or an orchestrator expects.

Why two routes?

Liveness tells an orchestrator whether to restart the process; readiness tells a load balancer whether to send traffic. If the database check lived in liveness, a database outage would restart every instance and make the outage worse. Keeping them apart keeps those decisions apart.

Does the readiness check load the database?

One SELECT 1 per probe through the client the app already holds, with a timeout so a hung connection answers 503 instead of stalling the probe. At typical probe intervals that is a handful of trivial queries a minute.

Will the tests run in CI without changes to the workflow?

Yes. main.yml already runs pnpm test-unit in the unit job and pnpm test-e2e in the e2e job, both with a Postgres service, so the new Vitest and Playwright files are picked up by the existing commands.

More tRPC jobs

The same job on other stacks

Keep reading