# Add Lighthouse CI to an Eleventy Site

Yes. An agent builds your Eleventy site, measures its pages with Lighthouse CI, sets assertions from those numbers, and adds a pull request workflow, in a PR.

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

## What the agent does

The agent reads the site before it measures it. In a site like 11ty/eleventy-base-blog, `package.json` builds with `npx @11ty/eleventy` on `@11ty/eleventy` 3.1, has a separate `build-ghpages` script that adds `--pathprefix=/eleventy-base-blog/`, declares `"type": "module"` and `engines.node >=18`, and `.nvmrc` says 22. There is no test script and no workflow: `.github/workflows/` holds only `gh-pages.yml.sample`, a deploy workflow waiting to be renamed, which pins its actions by commit SHA and builds with the pathprefix script. `.github/dependabot.yml` already watches npm monthly. The README claims four 100 Lighthouse scores, zero Cumulative Layout Shift and zero Total Blocking Time, and nothing in the repository checks that claim after a change.

`eleventy.config.js` is what makes those scores: the CSS from `css/index.css` is inlined into every page through the bundle plugin (`<style>{% getBundle "css" %}</style>` in `_includes/layouts/base.njk`), the only script is the `heading-anchors` web component inlined as a module, `eleventyImageTransformPlugin` writes AVIF, WebP and the original format for every image with `loading="lazy"` and `decoding="async"` and width and height attributes, and the drafts preprocessor drops `draft: true` pages when `ELEVENTY_RUN_MODE` is `build`. The output is `_site/`, with the home page listing three latest posts, `/blog/` as the archive, `/about/`, tag pages, a 404 page, the Atom feed at `/feed/feed.xml` and `/sitemap.xml`. Five posts live under `content/blog/`, one of them, `fourthpost`, with a `possum.png` beside it that exercises the image pipeline.

The agent adds `@lhci/cli` as a devDependency, runs `npm run build` and `npx lhci collect` against `_site/` in its sandbox, installing Chromium there if the sandbox browser is not already one Lighthouse can drive, and reads the real numbers for `/`, `/blog/`, `/about/`, `/tags/` and the URL the build gives the post under `content/blog/fourthpost/`, the one with the image. From those it writes `lighthouserc.json`: `ci.collect.staticDistDir` set to `_site`, those five `url` paths, three runs per page so a flaky metric is a median, `ci.assert` starting from the `lighthouse:no-pwa` preset with category minimums set a little under what it measured, `cumulative-layout-shift` held at the zero the README promises, and `ci.upload.target` set to `temporary-public-storage` so each run leaves a report link in the job log. It does not write thresholds it did not measure.

Then it writes `.github/workflows/lighthouse.yml` on `pull_request`: checkout and `setup-node` pinned by SHA the way the sample workflow does, Node from `.nvmrc` with the npm cache, `npm ci`, `npm run build` rather than `build-ghpages` so the URLs match the static directory, and `npx lhci autorun`. `.lighthouseci/` goes into `.gitignore` next to `_site/` and `.cache`. A `lighthouse` script in `package.json` runs the same `lhci autorun` locally. The agent runs the finished `autorun` once more in the sandbox to see every assertion pass against the build it just made before it opens the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add Lighthouse CI to this Eleventy site. Read package.json, .nvmrc, eleventy.config.js, _data/metadata.js, _includes/layouts/base.njk, the content directory and anything under .github first. Add @lhci/cli as a devDependency, build the site with npm run build, and run lhci collect against _site for the home page, the blog archive, the about page, one blog post with an image and the tags page, reading the measured scores and metrics. Write lighthouserc.json with staticDistDir set to _site, those URLs, three runs per page, assertions based on the lighthouse:no-pwa preset with category minimums set just under the measured values and cumulative-layout-shift held at zero, and upload to temporary public storage. Write .github/workflows/lighthouse.yml on pull_request that sets up Node from .nvmrc with the npm cache, runs npm ci, npm run build and npx lhci autorun, pinning actions by commit SHA as the sample workflow does. Add .lighthouseci to .gitignore and a lighthouse script to package.json. Run lhci autorun in the sandbox and confirm every assertion passes before opening a pull request, and put the measured scores per page in its description.",
  "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 `lighthouserc.json`, `.github/workflows/lighthouse.yml`, one `@lhci/cli` line in `package.json` with the matching `package-lock.json` change, a `lighthouse` script, and one `.gitignore` line. No template, layout, content or Eleventy configuration changes, so the site builds exactly as before.

Its description holds a table of the five pages with the performance, accessibility, best-practices and SEO scores and the layout-shift and blocking-time values the agent measured in the sandbox, and under it the thresholds it chose and why each sits where it does. The build and `lhci autorun` output are in the session transcript at `GET /o/{org}/sessions/{id}/messages`, and the pull request's own Lighthouse check is the first run of the new workflow.

Before merging, a reviewer reads the thresholds against the measured numbers to decide whether the headroom is right, checks that the URL list covers the page types that matter to them, and opens the temporary report link the job prints to see the audits behind one score. A follow-up message to the same session can switch `upload.target` to a Lighthouse CI server once the team has one, or add a budget file for total byte weight.

## Run it on every terminal hand-off

A developer who has been checking Lighthouse by hand in a browser tab starts this from the terminal with this body and goes back to writing. The run builds the actual site and measures the actual pages, so the thresholds in the pull request come from the site's own numbers rather than from a round figure.

Send a `request_id`, a UUID, with the body so a retried start returns the run it already began. The pull request is on the run's `GET /o/{org}/sessions/{id}` answer once it is open.

## Why run it on Rush?

Thresholds set without measuring either fail on the first pull request or never fail at all. The agent builds the site in its own sandbox, drives a real browser over the real output, and sets each assertion from the number it saw, with the headroom stated. That measuring loop, build, collect, read, adjust, is tedious on a laptop and usually skipped.

Every build and every Lighthouse run the agent made is kept with its output in the session record, so the scores in the pull request can be checked against the audits that produced them. A team with several Eleventy sites can send the same request for each at once and get one pull request per site, each with thresholds from that site's own pages.

## Frequently asked questions

### Why build with npm run build and not build-ghpages?

The pathprefix script writes every URL under `/eleventy-base-blog/`, which is right for GitHub Pages but wrong for a static directory served from its root, so Lighthouse would audit 404 pages. The plain build matches `staticDistDir`. A site deployed under a prefix can set `ci.collect.staticDistDir` and the URL list to match, which the pull request notes.

### Will drafts affect the scores?

No. `npm run build` runs with `ELEVENTY_RUN_MODE` set to `build`, and the drafts preprocessor in `eleventy.config.js` drops any page with `draft: true` in that mode, so Lighthouse sees only what a visitor would.

### Does this need a Lighthouse CI server or a token?

No. `temporary-public-storage` uploads each report to a public link that expires, with no account. If the team later runs an LHCI server or wants the GitHub status check from the Lighthouse CI GitHub App, the upload target and a token are the only changes.

### What happens when a pull request makes a page slower?

The assertion that drops under its minimum fails the `lighthouse` job, and the log names the page, the audit and the measured value next to the threshold. Three runs per page mean a single slow run does not fail it on its own.

## More Eleventy jobs

- [Check for Broken Links in an Eleventy Site's CI](https://getrush.ai/run/add-link-checking/eleventy/)
- [Add an llms.txt File to an Eleventy Site](https://getrush.ai/run/add-llms-txt/eleventy/)
- [Add Mermaid Diagrams to an Eleventy Blog](https://getrush.ai/run/add-mermaid-diagrams/eleventy/)

## The same job on other stacks

- [Add Lighthouse CI to a Gatsby Blog](https://getrush.ai/run/add-lighthouse-ci/gatsby/)
- [Add Lighthouse CI to a Hugo Docs Site](https://getrush.ai/run/add-lighthouse-ci/hugo/)
- [Add Lighthouse CI to a Jekyll Site](https://getrush.ai/run/add-lighthouse-ci/jekyll/)

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