# Add Pagination to a Gatsby Blog Index

Yes. An agent turns your Gatsby blog's single post list into numbered pages created in gatsby-node.js, keeps the header and feed intact, builds it and opens a PR.

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

## What the agent does

The agent reads how the index is built today before it touches it. In a Gatsby 5 blog shaped like gatsbyjs/gatsby-starter-blog, src/pages/index.js is a page component whose pageQuery asks allMarkdownRemark for every post sorted by frontmatter date descending and renders them all as one list of post-list-item articles with Bio at the top. gatsby-node.js already runs createPages for the posts themselves, looping over the nodes to call createPage with src/templates/blog-post.js and a context of id, previousPostId and nextPostId, and onCreateNode sets the slug field with createFilePath. Pagination means the index has to move into that same createPages call, because a static page under src/pages cannot take a per-page skip and limit.

So the agent adds src/templates/blog-list.js, a copy of the index component whose query takes $limit and $skip variables, and extends createPages to compute the page count from the posts it already fetched and call createPage once for the root path and once for each /page/N path, with limit, skip, numPages and currentPage in the context. src/pages/index.js is removed, because a file page and a created page at the same path would collide. The posts-per-page number lives in one constant at the top of gatsby-node.js. The template renders a nav after the list with Link elements marked rel prev and rel next, the page numbers, and the Head export that already wraps Seo gets the page number in its title so two pages do not share one.

Two details in this repository are easy to get wrong. src/components/layout.js decides between the large main-heading and the small header-link-home by comparing location.pathname to the root path, and sets data-is-root-path, which src/style.css uses to show the bio differently on the front page; a /page/2 route would otherwise render the small header and shift the layout. The agent extends that check so every list page counts as root, or passes an explicit prop, and says which in the pull request. The RSS feed in gatsby-config.js runs its own allMarkdownRemark query inside gatsby-plugin-feed, so it is unaffected and the agent leaves it alone, and the same goes for gatsby-plugin-manifest.

It proves the change with the repo's own tools. package-lock.json makes it npm, so it runs npm ci, then npm run build, which here includes gatsby-plugin-sharp image processing for the salty_egg.jpg post image, then gatsby serve, and requests /, /page/2 and the last page to check the lists are disjoint, cover every post and link to each other. package.json has a format script that runs prettier 2.8.8 over js, jsx, ts, tsx, json and md, and the agent runs it over the files it touched; the test script exits 1 by design and is not a check. With three posts under content/blog the agent picks a page size that produces more than one page, and the description says what to change to adjust it.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add pagination to this Gatsby blog's post index. Read package.json, gatsby-config.js, gatsby-node.js, src/pages/index.js, src/templates/blog-post.js, src/components/layout.js, src/components/seo.js and src/style.css first. Move the list into src/templates/blog-list.js with a query that takes limit and skip, create the root page and /page/N pages from createPages in gatsby-node.js with limit, skip, numPages and currentPage in the context, remove src/pages/index.js, and add a previous and next nav with rel attributes plus page numbers. Keep the large header and the bio treatment that layout.js applies on the root path for every list page. Do not change the RSS feed or the manifest plugin. Put the posts-per-page value in one named constant. Run npm ci, npm run build, serve the build and request each list page to confirm the pages are disjoint and cover every post, run the format script over the files you changed, and open a pull request that explains the page count, the layout.js change and quotes the build output.",
  "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 on its own branch that adds src/templates/blog-list.js, edits gatsby-node.js to create the root and /page/N pages, deletes src/pages/index.js and adjusts src/components/layout.js so list pages keep the front-page header. The description names the page size constant and where it lives, lists the paths the build produced, and quotes the gatsby build output and the curl checks from the sandbox.

The session read names the repository and the pull request URL, and the transcript at GET /o/{org}/sessions/{id}/messages keeps each step: the files read, the build, the served requests to each page, and the prettier run. A reviewer does not have to rebuild to see that /page/2 existed and that the last page linked back.

Before merging, a reviewer checks that the created root page did not leave a stale src/pages/index.js behind, that rel prev and rel next point the right way given the descending sort, that the Head title differs per page, and that the feed at /rss.xml still lists every post, since the feed query is independent of the paginated one.

## Run it on every Linear issue labelled agent

Add an automation to the Project with this prompt and a linear trigger on linear.issue.labeled, with the label you reserve for the agent. Labelling the issue starts one run with the issue added after the prompt; the agent reads the requested page size from it if the issue names one. Changes made by an app integration never fire the trigger, so a bot relabelling in bulk starts nothing. The automation's own max_runs_per_hour cap bounds how many runs it starts.

From your own server, the same run starts with this request when your Linear webhook handler sees the label, with the issue URL in resources as https://linear.app/your-workspace/issue/ENG-42 beside the repository and a request_id that is a UUID v5 of the delivery id so a retried webhook returns the run already started. A webhook URL on the key reports run.completed with data.session_url for the runs that key starts.

## Why run it on Rush?

Pagination in Gatsby is a build-time change, and the only way to know the created pages are right is to build. A full build here runs Sharp over every image and the GraphQL queries for each created page, and then someone has to serve it and click through. The agent does that in its own sandbox with its own node_modules and leaves the built public directory parked with the session, so a follow-up that changes the page size rebuilds without a cold install.

The evidence is the transcript, not a claim. The gatsby build log, the list of pages it created, and the requests against the served site are kept on the session beside the diff, and the pull request quotes them. Several blogs on the same starter can be paginated at once, each in its own sandbox with its own branch.

## Frequently asked questions

### Why does src/pages/index.js get deleted?

A page file under src/pages and a page created in createPages at the same path would collide, and the created one is the only way to pass skip and limit into the query. The component moves to src/templates/blog-list.js and the root path is created from gatsby-node.js like every other list page.

### Will the RSS feed still include every post?

Yes. gatsby-plugin-feed runs its own allMarkdownRemark query, configured in gatsby-config.js, that has nothing to do with the paginated index. The agent does not touch it and the reviewer can confirm /rss.xml on the served build.

### How do I change how many posts show per page?

One named constant at the top of gatsby-node.js. The pull request description names it, and the page count follows from it at build time. A follow-up on the same session can change it and rebuild in the parked sandbox.

### What about the large header and the bio on the front page?

src/components/layout.js keys both on the root path, so without care /page/2 would render the small header. The agent extends that check so every list page is treated as root, or passes a prop from the template, and says which it chose in the pull request.

## More Gatsby jobs

- [Add PWA Support to a Gatsby Blog](https://getrush.ai/run/add-pwa-support/gatsby/)
- [Add Reading Time to Posts in a Gatsby Blog](https://getrush.ai/run/add-reading-time/gatsby/)
- [Add Related Posts to a Gatsby Blog](https://getrush.ai/run/add-related-posts/gatsby/)

## The same job on other stacks

- [Add Pagination to a Jekyll Blog](https://getrush.ai/run/add-pagination/jekyll/)
- [Add Pagination to a Koa REST API](https://getrush.ai/run/add-pagination/koa/)
- [Add Pagination to a Prisma Query](https://getrush.ai/run/add-pagination/prisma/)

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