# Run an SEO Audit on a Gatsby Blog

Yes. An agent builds your Gatsby blog in a sandbox, crawls the output for titles, Open Graph tags, feed and robots rules, and maps each issue to its file.

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

## What the agent does

The agent clones the repository into its own sandbox, installs with the lockfile and builds, because an SEO audit of a Gatsby site is an audit of the HTML in `public/`, not of the JSX. In a blog like gatsbyjs/gatsby-starter-blog, `package.json` asks for `gatsby ^5.14.6` with React 18, installs with npm from `package-lock.json`, and its `test` script only prints a reminder to write tests and exits 1, so the build is the only automated check. `gatsby-config.js` sets `siteMetadata` with the title, an `author` object, a `description`, a `siteUrl` that ends in a slash, and `social.twitter`, and loads `gatsby-plugin-image`, two `gatsby-source-filesystem` sources for `content/blog` and `src/images`, `gatsby-transformer-remark` with `gatsby-remark-images` at `maxWidth 630`, `gatsby-remark-responsive-iframe` and `gatsby-remark-prismjs`, the sharp plugins, `gatsby-plugin-feed` writing `/rss.xml`, and `gatsby-plugin-manifest` with `minimal-ui` and `src/images/gatsby-icon.png`. There is no sitemap plugin and no canonical plugin, `gatsby-ssr.js` sets `lang` to `en` on `<html>`, and `static/robots.txt` allows everything and names no sitemap.

The metadata comes from one component. `src/components/seo.js` is a Head component that renders `<title>` as the page title joined to the site title with a pipe, a `description` meta that falls back to the site description, `og:title`, `og:description`, an `og:type` that is always `website`, a `twitter:card` of `summary`, `twitter:creator` from `social.twitter`, and the Twitter title and description, and nothing else: no `og:url`, no `og:image`, no canonical `<link>`. `src/templates/blog-post.js` passes `post.frontmatter.description || post.excerpt` to it, wraps the article in schema.org `Article` microdata with `itemProp` on the headline and body but no `datePublished` or `author` properties and no JSON-LD, and renders previous and next links with `rel="prev"` and `rel="next"`. `src/pages/index.js` titles itself `All posts` and prints each post's description or excerpt, `src/pages/404.js` is titled `404: Not Found`, and `src/pages/using-typescript.tsx` is a page most blogs forget they ship. `gatsby-node.js` creates a page per `allMarkdownRemark` node with the slug from `createFilePath`, which carries a trailing slash, and types the frontmatter as `title`, `description` and `date` in `createSchemaCustomization`.

The crawl is of the build output served locally. The agent runs `npm ci` and `npm run build`, starts `gatsby serve`, and fetches every HTML file under `public/`: the index, each post, the TypeScript page and the 404. For each it checks the title and its length, that a description is present and whether it is an excerpt cut mid-sentence, `html lang`, one `h1` per page (the `Layout` renders the site title as an `h1` only on the root path, and a post renders its headline as `h1`), image `alt` text that `gatsby-remark-images` copies from the Markdown, the `og:type` on posts, the absent `og:url`, `og:image` and canonical, and the microdata against what a rich result needs. It reads `public/rss.xml` and checks each item's `link` and `guid`, which `gatsby-plugin-feed` builds as `site.siteMetadata.siteUrl + node.fields.slug`; with a `siteUrl` ending in a slash and a slug starting with one, the audit reports exactly what that concatenation produced. It reads `public/robots.txt` and `public/manifest.webmanifest`, confirms there is no `sitemap-index.xml`, and checks that the 404 page is not linked from anywhere as a real page.

Every finding points at a line and a fix. The `og:type` goes on a prop that `blog-post.js` sets to `article`; a canonical and `og:url` come from `siteUrl` and the page path, and an `og:image` from a frontmatter field or a default under `src/images`; the microdata gains `datePublished` and `author` or is replaced by JSON-LD built from the same query; the feed URL fix is a `siteUrl` without the trailing slash or a `new URL(slug, siteUrl)` in the serializer; the sitemap is a plugin install with a `Sitemap:` line in `static/robots.txt`. The report groups findings by page type, notes which are plugin installs and which are edits to `seo.js`, and says which pages are affected, with the run leaving the repository unchanged.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Audit this Gatsby blog for technical SEO and write seo-audit.md. Read package.json, gatsby-config.js, gatsby-node.js, gatsby-ssr.js, src/components/seo.js, src/components/layout.js, src/templates/blog-post.js, the files under src/pages and static/robots.txt first. Run npm ci and npm run build, start gatsby serve, and fetch every HTML page under public plus rss.xml, robots.txt and the web manifest, keeping each response. For every page check the title and its length, the meta description and whether it is a truncated excerpt, html lang, one h1, image alt text, canonical, og:url, og:image, og:type, Twitter tags and structured data, and for the feed check that each item link and guid is a well-formed absolute URL as built from siteUrl and the slug. Check robots.txt for a Sitemap line and whether a sitemap was generated. For each finding name the file and line that produces it, the pages affected, and the change you would make, and mark whether the fix is an edit or a plugin install. List what you checked and found correct as well. Do not change any file and do not 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 `seo-audit.md` as an artifact on the session, with a download link good for an hour that reading the session again renews. It opens with how the site was built and crawled: the Gatsby and Node versions, the install and build commands, and the list of pages fetched. Then come the findings grouped by what produces them: the gaps in `src/components/seo.js` with the line each tag would be added at, the `og:type` and structured data on `src/templates/blog-post.js`, the feed URLs as `gatsby-config.js` builds them with the exact strings read from `public/rss.xml`, and the missing sitemap and `robots.txt` line. Each names the pages affected and whether the fix is an edit or a plugin.

The session read at `GET /o/{org}/sessions/{id}` lists the artifact with its `name`, `mime_type` and `url`, and the transcript at `GET /o/{org}/sessions/{id}/messages` keeps the build output and every fetched page with its headers, so a finding can be checked against the HTML it came from. The repository is unchanged.

A reader picks the findings worth doing, since a three-post blog does not need every rich result, and a follow-up on the same session can apply the `seo.js` edits and the plugin install as one pull request with a rebuilt `public/` to diff.

## Run it on every merge to main

Add an automation to the Project with this prompt and a `github` trigger on `pull_request.closed.merged` with `branch_patterns` set to `main`, so every merge rebuilds the site in a sandbox and audits the output before the deploy settles. The trigger adds the pull request event after the prompt and fills in nothing; only merges by someone who can write to the repository fire it, and the automation's `max_runs_per_hour`, between 1 and 30, caps a busy afternoon of merges.

A `schedule` trigger with `cron` set to one morning a week and your `timezone` does the same on a cadence. From a deploy hook instead, send `POST /o/{org}/sessions` with this body and a `request_id` that is a UUID v5 of the commit SHA, give the key a `webhook_url`, and Rush POSTs `run.completed` with `data.session_url` to read for the artifact.

## Why run it on Rush?

The tags a Gatsby page ships are decided at build time by a Head component, a template and a plugin's serializer, and the only honest way to audit them is to build and read `public/`. That means `npm ci`, a sharp build and a local server, which is slow on a laptop and never happens for a blog nobody is actively developing. The agent builds it in its own sandbox, reads every page it produced, and maps each gap back to the line that caused it.

The report comes with its evidence: the HTML and the feed as fetched, the build log, and the file and line behind each finding, all on the session. Nothing is changed in the repository, several sites can be audited at once in separate sandboxes, and the parked session can apply the chosen fixes as a pull request without a second build.

## Frequently asked questions

### Will it edit seo.js or open a pull request?

No. This run reads, builds and reports. Each finding names the file and line where the fix goes, and a follow-up on the same session can make the edits and the plugin install as one pull request, with the rebuilt output to compare.

### Does it need my production domain?

It reads `siteUrl` from `siteMetadata` in `gatsby-config.js`, which is what the feed and any canonical would use, and reports if it is still the starter's placeholder. The crawl itself runs against `gatsby serve` in the sandbox, so no request reaches your domain.

### Is the feed URL finding real or a guess?

It is read from `public/rss.xml` after the build. The serializer in `gatsby-config.js` joins `siteUrl` and `fields.slug` with a plus sign, and the report quotes the resulting `link` and `guid` strings as produced, so you see the exact URL a reader would get, and the fix is one line in the config.

### Does it check structured data?

Yes. It reads the schema.org `Article` microdata in `blog-post.js` and the properties it sets, compares them with what a rich result needs, and reports the missing `datePublished` and `author` along with the option of JSON-LD built from the same page query.

### Is this a Lighthouse run?

No. This audit is of the HTML, feed, manifest and robots rules the build emits, mapped to source lines. Performance scores and Core Web Vitals are a different measurement; ask for a Lighthouse run against the served build as a follow-up on the session if you want both.

## More Gatsby jobs

- [Upgrade Gatsby and Its Plugins](https://getrush.ai/run/upgrade-gatsby/gatsby/)
- [Write Playwright Tests for a Gatsby Site](https://getrush.ai/run/write-playwright-tests/gatsby/)
- [Write Unit Tests for a Gatsby Blog](https://getrush.ai/run/write-unit-tests/gatsby/)

## The same job on other stacks

- [Run an SEO Audit on a Next.js Site](https://getrush.ai/run/seo-audit/nextjs/)
- [Run an SEO Audit on a Nuxt App](https://getrush.ai/run/seo-audit/nuxt/)
- [Run an SEO Audit on a Starlight Site](https://getrush.ai/run/seo-audit/starlight/)

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