# Add Server-Side Pagination to a TanStack Router Page

Yes. An agent puts the page number in the URL with validateSearch, fetches one page at a time, wires the table to the API's real count and opens a PR.

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

## What the agent does

The agent starts by reading how the list is fetched today. In a Vite and React app laid out like fastapi/full-stack-fastapi-template, `frontend/src/routes/_layout/items.tsx` builds its query with `ItemsService.readItems({ query: { skip: 0, limit: 100 } })` under the key `["items"]`, and `frontend/src/components/Common/DataTable.tsx` pages through whatever arrived with `rowPaginationFeature` from `@tanstack/react-table`, offering page sizes of 5, 10, 25 and 50 and printing `data.length` as the number of entries. So the hundred-and-first item never reaches the browser, the entry count is the fetch size rather than the table size, and a reload lands on page one. The backend already does the right thing: `read_items` in `backend/app/api/routes/items.py` takes `skip` and `limit`, orders by `created_at` descending, and answers `ItemsPublic` with `data` and a `count` from a separate `select(func.count())`.

The route gets a search schema. `zod` is already a dependency in `frontend/package.json`, so the agent adds `validateSearch` to `createFileRoute("/_layout/items")` with a `page` and a `pageSize` that are integers with a lower bound and a `.catch()` to the first page and the table's smallest page size, so a hand-edited URL never throws. `loaderDeps` names those two values, and the query options take them: the key becomes `["items", page, pageSize]` and the function sends `skip: (page - 1) * pageSize` and `limit: pageSize`. `useSuspenseQuery` keeps `placeholderData` set to the previous page so the table does not fall back to `PendingItems` on every click. `Route.useSearch()` reads the current page and `useNavigate` writes the next one with `search: (prev) => ({ ...prev, page })`, which is what makes the browser's back button and a shared link work.

`DataTable` learns that the rows it holds are one page already. The agent adds `manualPagination`, a `rowCount` from the API's `count`, a controlled `pagination` state and an `onPaginationChange` callback, keeping the existing buttons, the rows-per-page select and the `Showing x to y of n entries` line, which now reads the server count. The empty state in `ItemsTableContent` is kept for a first page with no rows, and a page past the end, reachable after a deletion, navigates back to the last page rather than showing `No results found`. The admin page in `frontend/src/routes/_layout/admin.tsx` fetches users the same way with the same `skip` and `limit` on `read_users` in `backend/app/api/routes/users.py`, so it gets the same treatment, and `routeTree.gen.ts` is regenerated by the `tanstackRouter` Vite plugin on the next build.

For proof the agent runs `bun run build`, which type-checks with `tsc -p tsconfig.build.json` before `vite build`, and `bun run lint`, which is Biome with the rules in `frontend/biome.json`. Then it extends `frontend/tests/items.spec.ts`: the `Items management` block already creates a user through `createUser` in `tests/utils/privateApi.ts` and logs in with `logInUser`, so a new test creates more items than one page through the generated client, opens `/items?page=2`, checks the entries line and the active page, and reloads to confirm the page survives. The Playwright suite runs through `docker compose run --rm playwright` in `.github/workflows/playwright.yml`, so the agent installs Docker in its sandbox with `sudo apt-get install -y docker.io` and the Compose v2 plugin, which that package does not include, starts `dockerd`, runs `bash scripts/prestart.sh` against the compose database and runs the spec the same way CI does.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Move the Items and Users tables from client-side to server-side pagination. Read frontend/src/routes/_layout/items.tsx, frontend/src/routes/_layout/admin.tsx, frontend/src/components/Common/DataTable.tsx, backend/app/api/routes/items.py and backend/app/api/routes/users.py first. Add validateSearch with zod for page and pageSize to both routes with safe defaults, put them in loaderDeps and the query key, send skip and limit to the API, and make DataTable use manual pagination with the API's count. Keep the existing buttons and the rows-per-page select. Add a Playwright test in frontend/tests/items.spec.ts that creates more items than one page, opens page 2 by URL and reloads. Run bun run build, bun run lint and the Playwright suite the way .github/workflows/playwright.yml does, quote the results and open a pull request.",
  "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

What comes back is a pull request that changes `frontend/src/routes/_layout/items.tsx`, `frontend/src/routes/_layout/admin.tsx` and `frontend/src/components/Common/DataTable.tsx`, regenerates `frontend/src/routeTree.gen.ts`, and adds one test to `frontend/tests/items.spec.ts`. No backend file changes, because `read_items` and `read_users` already take `skip` and `limit` and return `count`.

The description shows the `bun run build` and `bun run lint` output, the Playwright summary for the items spec, and a short table of URLs the agent opened by hand in the sandbox browser: page one, a page number past the end, a non-numeric `page`, and a reload on page two, each with what rendered. The repository's `Playwright Tests` workflow then runs its four shards on the branch, and `pre-commit` runs Biome through `prek`.

Before merging, a reviewer decides whether `pageSize` belongs in the URL at all or should stay a local preference, and whether the admin page should keep its `isCurrentUser` highlight when the signed-in user is on another page. The agent keeps both in the URL and says so.

## Run it on every GitHub issue labelled pagination

In the Project that holds the repository, create an automation with a general form of this page's prompt and a `github` trigger on `issues.labeled` with `pagination` in its `labels`. The trigger adds the issue text after the prompt, so the prompt says to read the issue that follows, find the route it names, move that route's list to server-side pagination with the pattern already used on `/items`, add the test and open a pull request that links the issue.

A support engineer who hears that the admin table stops at a hundred users files the issue, and the run opens the pull request with the build, lint and test output in it. A later issue for a new list route, say an audit log, starts its own run on its own branch, and the automation's `max_runs_per_hour` keeps a burst of labels from starting more runs than the team can review.

## Why run it on Rush?

Proving pagination means a database with more rows than one page, the generated client rebuilt against the running API, a browser that follows `?page=2` and a reload, and the compose-based Playwright setup the repository's CI uses, which is a lot of local setup for a change to three files. The sandbox has its own Docker, database and browser, and the pull request opens with the build, lint and test output already in it.

The run's record keeps every command and its output, and the screenshots of the pages the agent opened, so a reviewer reads what the table showed on page two rather than a claim that it paginates. A team with several admin apps on this template starts one run each, and each pull request changes that app's own routes.

## Frequently asked questions

### Will the table still work with fewer rows than one page?

Yes. With `manualPagination` the table shows the rows it is given and the pager stays hidden while `getPageCount()` is one, which is the same condition `DataTable` uses today. The empty-state block in `ItemsTableContent` is unchanged.

### What happens to a link with a bad page number?

`validateSearch` runs the zod schema with `.catch()`, so `?page=abc` or `?page=0` reads as the first page instead of throwing into the route's `errorComponent`. A page past the last one is detected from the API's `count` and the route navigates to the last page.

### Does this change the backend or the generated client?

No. The `skip` and `limit` parameters and the `count` field already exist on `read_items` and `read_users`, and `frontend/src/client` is generated from the backend's OpenAPI document by `scripts/generate-client.sh`, so nothing in it moves.

### Why keep the page in the URL rather than in React state?

A page in the URL survives a reload, can be shared, and works with the back button, which is what `validateSearch` and `loaderDeps` exist for in TanStack Router. The query key includes the page, so TanStack Query caches each page separately and `placeholderData` keeps the previous one on screen while the next loads.

## More jobs like this: Turn a Linear label into a PR

- [Add Prometheus ServiceMonitors to a Kustomize App](https://getrush.ai/run/add-service-monitors/kustomize/)
- [Add Shell Completion to a Go CLI from a Linear Issue](https://getrush.ai/run/add-shell-completion/go-cli/)
- [Add Shell Completion to a Textual App's CLI](https://getrush.ai/run/add-shell-completion/textual/)
- [Add a Single-Instance Lock to a Tauri App](https://getrush.ai/run/add-single-instance-lock/tauri/)
- [Add a Sitemap to a Gatsby Blog](https://getrush.ai/run/add-sitemap/gatsby/)
- [Add an XML Sitemap to a Symfony App](https://getrush.ai/run/add-sitemap/symfony/)

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