# 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 Rush](https://cloud.getrush.ai/run/add-health-checks/trpc/). Opens 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`

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

## 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

- [Add ESLint and Prettier Checks to CI for a tRPC App](https://getrush.ai/run/add-lint-to-ci/trpc/)
- [Generate OpenAPI Docs from a tRPC Router](https://getrush.ai/run/add-openapi-docs/trpc/)
- [Add Optimistic Updates to a tRPC and Next.js App](https://getrush.ai/run/add-optimistic-ui/trpc/)

## The same job on other stacks

- [Add Health Checks to a Vapor App](https://getrush.ai/run/add-health-checks/vapor/)
- [Add Health Checks to a Wagtail Site](https://getrush.ai/run/add-health-checks/wagtail/)
- [Add Health Checks to an Actix Web Server](https://getrush.ai/run/add-health-checks/actix/)

## 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/)
