# Add Lighthouse CI to a VitePress Docs Site

Yes. An agent builds your VitePress site, adds a Lighthouse CI config and a workflow that audits key pages on every pull request, and opens a PR.

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

## What the agent does

The agent starts from how the site is built and where it is served. In a docs site laid out like vuejs/docs, `package.json` has a `build` script that runs `vitepress build`, a `preinstall` script of `npx only-allow pnpm`, `packageManager` set to `pnpm@10.33.0`, an `engines.node` floor of 20, and a `pnpm.overrides` entry that pins the `vite` under `vitepress` to 8.0.7; `.npmrc` turns off `package-manager-strict`. `netlify.toml` builds with Node 24 and publishes `.vitepress/dist`, and `vercel.json` rewrites every path to its `.html` file and sets long cache headers on `/assets/`. The only workflow in `.github/workflows/` is `automerge.yml`, which auto-merges Dependabot updates of `@vue/theme`, so nothing in CI measures the pages. In `.vitepress/config.ts` the agent reads `srcDir: 'src'`, the `sitemap` hostname, and a `head` that inlines `restorePreference.js` and `uwu.js` and loads two third-party scripts, the Fathom analytics tag and an ad script from bitterbrains, both of which Lighthouse will count against the site.

It installs with `pnpm install --frozen-lockfile` and runs `pnpm run build` in its sandbox, then lists `.vitepress/dist` to pick the pages worth auditing: the home page, the quick start and introduction under `guide/`, the API index, the tutorial, and one examples page, each as the `.html` file the build writes. Those paths go into `lighthouserc.json` at the root with `ci.collect.staticDistDir` set to `.vitepress/dist`, so Lighthouse CI serves the built files itself and no dev server is needed, and `ci.upload.target` set to `temporary-public-storage`, which needs no account and links a report from the job log.

The assertions come from a real first pass. The agent adds `@lhci/cli` to `devDependencies`, runs `pnpm exec lhci autorun` against the build in its sandbox, where a headless Chrome is available, and reads the scores and the failing audits page by page. The third-party scripts fail audits the repository cannot fix, so those audits are set to `warn` with a comment naming the script, while audits the site controls, such as image sizes under `src/public/images`, unused CSS from the theme, and accessibility checks, keep `error`. Category minimum scores are set just under what the first pass measured, so the check guards against regressions without failing the pull request that introduces it.

The workflow is `.github/workflows/lighthouse.yml`, triggered on `pull_request`, with `pnpm/action-setup` reading the version from `packageManager`, `actions/setup-node` on Node 24 to match `netlify.toml`, a pnpm store cache, `pnpm install --frozen-lockfile`, `pnpm run build`, and `pnpm exec lhci autorun`. Its permissions are `contents: read` only. The agent runs `actionlint` over the new file, runs the full `lhci autorun` once more to confirm the assertions pass on the current build, and opens a pull request with the config, the workflow, the two `package.json` lines and the score table from its sandbox run.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add Lighthouse CI to this VitePress site. Read package.json, .npmrc, netlify.toml, vercel.json, .vitepress/config.ts and every file under .github/workflows first. Install with the package manager package.json names, run the build, and choose five or six representative built pages from the output directory. Write lighthouserc.json with staticDistDir pointing at the build output, those pages as URLs, temporary-public-storage as the upload target, and assertions you set from a real lhci autorun in this sandbox: warn on audits that only third-party scripts named in the config head can fix, error on the rest, and category minimums just under the measured scores. Add @lhci/cli as a devDependency. Add .github/workflows/lighthouse.yml on pull_request that installs with the same package manager and Node version netlify.toml uses, builds, and runs lhci autorun, with contents: read permissions only. Run actionlint on the workflow and lhci autorun once more, then open a pull request that includes the measured scores per page and the reason behind every warn-level assertion.",
  "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`, and the `@lhci/cli` entry in `package.json` with its lines in `pnpm-lock.yaml`. Its description lists the pages audited, the performance, accessibility, best-practices and SEO scores the agent measured in its sandbox for each, which audits are set to warn and why, and the `actionlint` result.

Once merged, every pull request gets a Lighthouse job whose log links to the uploaded reports, and a page that drops under a category minimum or fails an error-level audit turns the check red before the change ships.

Before merging, a reviewer opens one of the linked reports to see that the pages were served from the static build rather than a dev server, decides whether the minimum scores should be tightened after a few runs, and checks that the warn-level audits are the ones third-party scripts cause and not ones the site could fix.

## Run it on every new documentation site

A team with several VitePress sites sends this body once per repository from its own server, each a `POST /o/{org}/sessions` with that repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own `package.json` and config: a site on npm gets an npm workflow, a site with no third-party scripts gets no warn-level assertions, and a site with `cleanUrls` on gets extensionless URLs in its config.

Once the job exists, an automation on the Project with a `github` trigger on `pull_request.opened` and the prompt "if the Lighthouse job failed on this pull request, read its report and comment with the audits that regressed, each with the page and the number" starts one run per pull request. The trigger adds the pull request after the prompt, and only work by an owner, member or collaborator fires it.

## Why run it on Rush?

Setting Lighthouse thresholds by guesswork produces a check that is either red on day one or never fires. The agent builds the site, audits the real pages in a sandbox with a browser, and writes the thresholds from those numbers, with the reasoning for each warn-level audit kept in the config and the pull request rather than in someone's head.

The build log, the Lighthouse runs and the `actionlint` output stay with the run, so a reviewer can see which audits failed before the assertions were written. A team that owns many docs sites starts one run per repository at the same time, each in its own sandbox with its own Chrome.

## Frequently asked questions

### Does it need a dev server running in CI?

No. The config points `staticDistDir` at the build output, so Lighthouse CI serves the files itself. That also keeps the audited pages identical to what the host serves, apart from the `.html` rewrite in `vercel.json`, which the static server handles because the config lists the `.html` files directly.

### What about the analytics and ad scripts in the config head?

Lighthouse counts their bytes and their blocking time against the site, and the repository cannot change them. The agent sets the audits they alone affect to `warn`, with a comment naming the script, so they appear in every report without failing the check.

### Will it work with pnpm's only-allow preinstall?

Yes. The workflow installs with pnpm through `pnpm/action-setup`, which reads the version from `packageManager`, so the `preinstall` guard passes. An npm or yarn install step would be refused by that guard before anything built.

### Why temporary public storage instead of a Lighthouse server?

It needs no account, no secret and no server, and each run's reports are linked from the job log. A team that wants score history over time can later switch `ci.upload.target` to its own LHCI server; the assertions and the workflow stay the same.

## More VitePress jobs

- [Add Link Checking to a VitePress Site](https://getrush.ai/run/add-link-checking/vitepress/)
- [Add llms.txt to a VitePress Blog](https://getrush.ai/run/add-llms-txt/vitepress/)
- [Add Mermaid Diagrams to a VitePress Site](https://getrush.ai/run/add-mermaid-diagrams/vitepress/)

## The same job on other stacks

- [Add Lighthouse CI to a Vue App](https://getrush.ai/run/add-lighthouse-ci/vue/)
- [Add Lighthouse CI to a Docusaurus Site](https://getrush.ai/run/add-lighthouse-ci/docusaurus/)
- [Add Lighthouse CI to an Eleventy Site](https://getrush.ai/run/add-lighthouse-ci/eleventy/)

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