What the agent does
The agent starts from how the app is built and tested, because a Lighthouse job has to audit the same output the site ships. In a Vue app laid out like antfu-collective/vitesse, package.json names pnpm@10.30.2 as the package manager, build is vite-ssg build, and vite.config.ts sets ssgOptions so the build writes prerendered HTML into dist, minified, with beasties inlining critical CSS and vite-ssg-sitemap writing a sitemap when the build finishes. The pages are the ones under src/pages: index.vue, about.md, the dynamic hi/[name].vue and the [...all].vue catch-all. .github/workflows/ci.yml already has four jobs, lint, typecheck, test on Node 22 and 24, and test-e2e, which builds and serves the site with npx vite preview --port 3333 for Cypress.
Dependencies in this repository are not pinned in package.json: each one reads catalog:dev or catalog:build, and the version lives in the catalogs section of pnpm-workspace.yaml. So the agent adds @lhci/cli to devDependencies as catalog:dev and adds its version to the dev catalog, then runs pnpm install so pnpm-lock.yaml carries it, because every CI job installs with --frozen-lockfile and would fail on a lockfile that does not match. The workspace file also sets trustPolicy: no-downgrade and a minimum release age, which the install respects on its own.
It then writes lighthouserc.cjs at the root with ci.collect.staticDistDir set to dist, so Lighthouse CI serves the prerendered files itself and no vite preview is needed, and leaves url unset so every HTML file the build wrote is audited, not only the home page. Assertions use the lighthouse:no-pwa preset first, since vite-plugin-pwa registers a service worker with registerType: 'autoUpdate' and a full PWA audit would judge the manifest and icons rather than the pages; the pull request says this and how to switch presets later. Upload goes to temporary public storage, which prints a report link into the job log for each page.
The new lighthouse job in ci.yml copies the install steps the other jobs use, pnpm/action-setup@v3 and actions/setup-node@v4 with cache: pnpm, runs pnpm run build, then pnpm exec lhci autorun. In its sandbox the agent runs the same build and audit once to see the config load and the scores print, and runs pnpm run lint, because eslint . with the @antfu/eslint-config rules covers the new config file too and the lint-staged hook would otherwise rewrite it on commit.
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 Vue app. Read package.json, pnpm-workspace.yaml, vite.config.ts, index.html, netlify.toml and .github/workflows/ci.yml first. Add @lhci/cli as a dev dependency the way the other dev dependencies are declared, with its version in the catalog, and run pnpm install so the lockfile is updated. Write a lighthouserc config that audits the prerendered HTML in dist with staticDistDir and the lighthouse:no-pwa assertion preset, uploading to temporary public storage. Add a lighthouse job to ci.yml that mirrors the existing install steps, builds, and runs lhci autorun. Run the build, the audit and pnpm run lint in your sandbox and quote the results. Do not change the existing jobs. Open a pull request.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- 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.
- 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.
- 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 touching four files: package.json and pnpm-workspace.yaml for the dependency and its catalog entry, pnpm-lock.yaml, the new lighthouserc.cjs, and .github/workflows/ci.yml with the one added job. The existing lint, typecheck, test and test-e2e jobs are untouched. The description quotes the audit as it ran in the sandbox, page by page with the category scores and the report links, and names the preset it chose and why.
The lighthouse job runs on the pull request itself, so the first real report is on the checks tab before anyone merges. The run's record keeps the build output and the audit output, so a reviewer can see which HTML files were found under dist and confirm the about page and the catch-all page were audited along with the home page.
Before merging, a reviewer decides whether the assertions should block or only warn, and whether to turn on the budgets Lighthouse CI supports for script size, since the report shows where the bundle stands today.
Run it on every new Vue repository
A team with several Vite sites sends one POST /o/{org}/sessions per repository with this body and that repository's URL in resources, from a script. Each run reads its own vite.config.ts, so a site that is not prerendered with vite-ssg gets a config that starts vite preview instead of serving dist statically, and each opens its own pull request.
Give the key a webhook_url and Rush POSTs run.completed when each run's turn ends, with session_url to read the pull request from; send a request_id, a UUID, in each body so a retried call returns the run it already started instead of a second one. A run whose audit or lint fails ends needs_review rather than opening a pull request that claims a green check.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Lighthouse CI is the kind of job that is one afternoon on a laptop and keeps slipping, because the config has to match how the site is built, the dependency has to be declared the way this repository declares dependencies, and the first run needs a browser and a built site. The agent reads those from the files rather than from a template, so the job that lands is the one that works for a vite-ssg build with catalog-pinned dependencies and a frozen lockfile.
The build and the audit run in the agent's own sandbox, with their output kept with the run, and the pull request quotes them, so the reviewer reads real scores instead of a promise. Across many repositories the same request runs in parallel, one sandbox and one pull request each, and a person only reads the ones that came back.
Frequently asked questions
Why serve dist statically instead of starting vite preview?
Because vite-ssg build writes finished HTML for each page into dist, and Lighthouse CI's staticDistDir serves that directory itself and audits every HTML file in it. The Cypress job needs vite preview because it clicks through the app; an audit of the shipped HTML does not.
Will the frozen lockfile break the install?
Not if the lockfile is updated in the same pull request. The agent runs pnpm install after adding the dependency so pnpm-lock.yaml matches, which is what --frozen-lockfile checks in every job.
Why the lighthouse:no-pwa preset?
The app registers a service worker through vite-plugin-pwa, and the full recommended preset includes PWA audits that fail on manifest and icon details unrelated to page speed or accessibility. Starting without them gives a report about the pages; the pull request says how to add the PWA audits back once the manifest is final.
Does this slow down CI?
It adds one job that runs alongside the existing four. It builds the site once more, as the test and test-e2e jobs already do, then audits each page. Nothing is added to the other jobs.
More Vue jobs
The same job on other stacks
- Add Lighthouse CI to a Docusaurus Site (Docusaurus)
- Add Lighthouse CI to an Eleventy Site (Eleventy)
- Add Lighthouse CI to a Gatsby Blog (Gatsby)