All jobs

Add Lighthouse CI to a Gatsby Blog

Yes. An agent reads your Gatsby build, adds a Lighthouse CI workflow with performance and accessibility budgets, and fixes it until it passes on its pull request.

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 how the site builds before it audits it. In a blog like gatsbyjs/gatsby-starter-blog it opens package.json and finds gatsby 5, gatsby-plugin-image, gatsby-plugin-sharp, gatsby-plugin-feed, gatsby-plugin-manifest and gatsby-remark-prismjs, scripts build, develop, serve and format, a test script that only prints a reminder and exits 1, prettier as the only dev dependency and package-lock.json as the lockfile. There is no .github directory, no .nvmrc and no engines field, so the workflow pins a Node major the agent confirms gatsby build runs on in its sandbox.

Then it reads gatsby-config.js and gatsby-node.js to know which pages exist to audit. siteMetadata.siteUrl is set, gatsby-source-filesystem reads content/blog, and createPages in gatsby-node.js builds one page per Markdown post from src/templates/blog-post.js. With hello-world, my-second-post and new-beginnings under content/blog, plus src/pages/index.js, 404.js and using-typescript.tsx, the agent picks the home page, one post and the TypeScript page as the URLs to audit, so the budget covers the list template, the post template and a plain page.

In its sandbox it runs npm ci and npm run build, then npx gatsby serve and npx lhci autorun against it to get a first set of scores. From that run it writes lighthouserc.js with ci.collect.staticDistDir pointing at public/, the three URLs, numberOfRuns set to reduce noise, and ci.assert.assertions with categories:performance and categories:accessibility as error at a minimum score a little below what it measured, categories:best-practices and categories:seo as warn, and ci.upload.target set to temporary-public-storage so each run has a report link without a Lighthouse server.

It adds .github/workflows/lighthouse.yml on pull_request and pushes to main: checkout, actions/setup-node with cache: npm, npm ci, npm run build, then npx @lhci/cli autorun, caching .cache and public keyed on the lockfile so repeat builds are quicker. Because gatsby build needs sharp's native binaries, it keeps the job on ubuntu-latest and lets npm ci build them. It pushes the branch, opens the pull request, reads the workflow run on it and, when an assertion fails on the runner where scores differ from its sandbox, lowers that threshold or raises numberOfRuns and pushes again until the run is green.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Add Lighthouse CI to this Gatsby site. Read package.json, gatsby-config.js and gatsby-node.js first, build the site in your sandbox, serve the public directory and run lhci autorun against the home page, one blog post and one plain page to measure baseline scores. Add lighthouserc.js with those URLs, performance and accessibility asserted as errors at minimum scores a little under what you measured, best-practices and SEO as warnings, and temporary public storage for reports. Add .github/workflows/lighthouse.yml that installs with npm ci, builds, and runs lhci autorun on pull requests and pushes to main, caching the Gatsby .cache and public directories. Do not add any other workflow and do not change the site's plugins. Open a pull request and make sure the workflow passes on it; if an assertion fails on the runner, adjust and push again.",
  "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 a new branch adding two files: lighthouserc.js with the audited URLs and the assertions, and .github/workflows/lighthouse.yml. In a site shaped like gatsby-starter-blog nothing else changes; gatsby-config.js, the plugins and the content are untouched. The pull request description lists the baseline scores the agent measured for each URL in its sandbox, the thresholds it set from them, and the Node version the workflow pins.

The proof is the Lighthouse workflow running on the pull request itself: its log shows each category score per URL against the assertion, and the temporary public storage link in the log opens the full report for that run. The session's trajectory keeps the sandbox gatsby build and lhci autorun output the thresholds were chosen from, so the numbers in the description can be checked against what the agent saw.

Before merging, a reviewer checks that the thresholds are floors the team is happy to hold, that the three URLs cover the templates they care about, and whether they want a Lighthouse CI server or a GitHub App token instead of temporary storage. Once merged, a pull request that adds a heavy embed or an unlabelled control fails this step and names the audit that dropped.

Run it on every pull request to the site

Once merged, the workflow runs on every pull request on its own. To have an agent explain a failing audit rather than leaving a red check, add an automation in the Project with a github trigger on pull_request.opened and pull_request.synchronize and a prompt asking it to read the Lighthouse log, open the report link, and post one review comment naming the audit and the file that caused it. The trigger adds the pull request event after the prompt, so no placeholder is needed.

To add the workflow to other Gatsby or static sites, have a script send this same request once per repository with its URL in resources and a fresh UUID as request_id, so a retry returns the run already started. Each run has its own sandbox and its own pull request, and Rush POSTs run.completed or run.failed to the webhook URL set on the key when each one's turn finishes.

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

Why run it on Rush?

Setting Lighthouse thresholds from a laptop means scores that depend on your machine and your network, then a CI runner that disagrees and fails the first pull request. On Rush the agent builds and serves the site in its own sandbox, measures a baseline there, pushes, and then reads the scores the real runner produced on its own pull request and adjusts, so the thresholds that land are ones that passed where they will run. Your machine never installs Chrome or builds the site.

The result is checkable rather than claimed. The workflow and its report link on the agent's pull request are the evidence the budget holds, and the trajectory keeps every build and audit command with its output, so a reviewer can see why a threshold sits where it does. Because each run is independent, the same request can add Lighthouse CI to every marketing and docs site in the organization at once, each behind a pull request a person reviews.

Frequently asked questions

Will it change my Gatsby plugins or content?

No. The prompt tells it not to, so gatsby-config.js, gatsby-node.js and content/blog stay as they are. The only additions are lighthouserc.js and the workflow file. If the baseline audit shows an easy fix, such as a missing image alt, the agent mentions it in the pull request description rather than changing the site in the same change.

Which pages does it audit?

It reads gatsby-node.js to see which templates produce pages and picks one URL per template: in gatsby-starter-blog the home page from src/pages/index.js, one post built from src/templates/blog-post.js, and using-typescript as a plain page. Name other paths in the prompt and it audits those instead.

Where do the reports go?

To Lighthouse CI's temporary public storage by default, which gives each run a report link in the job log with no server to run. If you have a Lighthouse CI server or want the Lighthouse GitHub App's status checks, say so in the prompt and the agent sets ci.upload.target and the token secret accordingly, naming the secret in the pull request.

What if the scores on the GitHub runner differ from the sandbox?

That is expected, and it is why the agent reads the workflow run on its own pull request before finishing. When an assertion fails on the runner, it lowers that threshold or raises numberOfRuns to average out variance and pushes again. The thresholds that land in the merged file are ones that passed on the runner.

My site has no test script. Does that matter?

No. Lighthouse CI audits the built site, not the code, so the test script that only prints a reminder in gatsby-starter-blog is left alone. The workflow builds with npm run build, serves public/ and audits it, which is independent of whether unit tests exist.

More Gatsby jobs

The same job on other stacks

Keep reading