All jobs

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 RushOpens 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 with this body:

{
  "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.

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

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

The same job on other stacks

Keep reading