# Audit Performance of a Next.js Site with Lighthouse

Yes. An agent builds your Next.js site for production, runs Lighthouse on its key pages and ranks the fixes, each tied to the file in your code that causes it.

[Run this on Rush](https://cloud.getrush.ai/run/lighthouse-audit/nextjs/).

## What the agent does

The agent clones the repository into its own sandbox and reads what will shape the scores before measuring anything. In a Next.js site like vercel/commerce, `package.json` has Next.js `15.6.0-canary.60` and React `19.0.0` with a `pnpm-lock.yaml`, and `next.config.ts` turns on three experimental flags, `ppr`, `inlineCss` and `useCache`, and serves images as AVIF or WebP from `cdn.shopify.com`. Its data comes from a Shopify store: `.env.example` lists `SHOPIFY_STORE_DOMAIN` and `SHOPIFY_STOREFRONT_ACCESS_TOKEN`, and `lib/shopify` builds every page from Storefront API queries, so the agent sets those before building and stops with a clear message if they are missing.

It runs `pnpm install`, `pnpm build` and `pnpm start`, so Lighthouse measures the production server rather than `next dev --turbopack`, whose unminified bundles and on-demand compiling make every score meaningless. Then it runs the Lighthouse CLI in headless Chrome against three pages: the home page, which `app/page.tsx` builds from `ThreeItemGrid`, `Carousel` and `Footer`; a product page under `app/product/[handle]`, taking a real handle from the home page's links; and a collection page under `app/search`. There is no cart page in this storefront: the cart is a Headless UI dialog in `components/cart/modal.tsx`, mounted on every page through `CartProvider` in `app/layout.tsx`, so its cost shows up in the JavaScript of all three. Each page is run for mobile and desktop, three times each, and the median run is kept.

With the JSON reports in hand, the agent reads the audits that cost the most and traces each one to the code. The largest contentful paint on the home page is usually the first `ThreeItemGrid` image, rendered by `GridTileImage` in `components/grid/tile.tsx`, so it checks that `priority` and `sizes` there match the image's real layout width. On the product page it checks the `fill` image in `components/product/gallery.tsx`, which has `priority` and `sizes="(min-width: 1024px) 66vw, 100vw"`. Unused JavaScript is matched against the 15 files marked `"use client"`, among them the cart, the search box in `components/layout/navbar/search.tsx` and `components/welcome-toast.tsx`, and render-blocking and font audits against the Geist font that `app/layout.tsx` loads.

It ranks the five changes by the savings Lighthouse estimates for them and states each as one concrete edit in one file. It changes no code; the branch in the sandbox stays the default branch as cloned.

## Start it with one API call

`POST https://api.prix.dev/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Clone https://github.com/vercel/commerce. Set SHOPIFY_STORE_DOMAIN and SHOPIFY_STOREFRONT_ACCESS_TOKEN from the environment and stop with a clear message if they are missing. Run pnpm install, pnpm build and pnpm start, and run the Lighthouse CLI in headless Chrome on the home page, one product page and one collection page under /search, for mobile and desktop, three runs each, keeping the median. Write lighthouse.md with the scores and Core Web Vitals per page, the five changes that would help most ranked by estimated savings, and for each the file in the repo that causes it and the edit you would make. Attach every Lighthouse JSON report. Change no code."
}
```

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.prix.dev/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 `lighthouse.md` plus one Lighthouse JSON report per page and form factor, all as artifacts on the session, each with a download link that lasts an hour. The markdown opens with a table of the median Performance, Accessibility, Best Practices and SEO scores per page for mobile and desktop, with largest contentful paint, total blocking time and cumulative layout shift beside them. The JSON files open in the Lighthouse viewer, so anyone can see the full audit behind a number.

The five fixes follow, ranked. Each one names the audit it addresses, the estimated saving Lighthouse gave, the file and component responsible (an image's `sizes` in `components/grid/tile.tsx`, a client component that could render on the server, a font that blocks the first paint), and the edit that would fix it. The session's transcript keeps the build output and each Lighthouse run, so the median can be checked against the runs it came from.

Before making the changes, a reviewer checks that the store data in the sandbox looks like production (product images of similar size, a similar number of products on the home page), because a storefront's scores follow its content. Lab scores also differ from what real visitors measure; field data from your analytics is the final word. A follow-up message to the same session can ask the agent to make the top fixes on a branch and re-run Lighthouse to show the difference.

## Run it on every release to production

Scores regress one merge at a time, so run this audit on every production release. Have your deploy pipeline send this request from your server once the release is out, with an `Idempotency-Key` built from the release tag so one release starts one run.

Set a webhook URL on the API key and Rush POSTs `run.completed` with the `session_url` when the run finishes. Your server reads `lighthouse.md` from the session's artifacts and compares the scores with the previous release's, posting only when a page drops.

## Why run it on Rush?

Lighthouse on a laptop measures the laptop: extensions, other tabs and a dev server all move the numbers, and one run is noisy. In a Rush sandbox the agent builds the site for production and runs Lighthouse on a machine with nothing else running, three times per page and form factor, and keeps every JSON report.

The output is a report with its proof: the scores come with the raw reports and the transcript of the build and every run, and each recommendation names the file to change. Several sites, or several branches of one, can be audited at once, one run each, up to the key's concurrent run limit.

## Frequently asked questions

### Where do the Shopify credentials go?

Save `SHOPIFY_STORE_DOMAIN` and `SHOPIFY_STOREFRONT_ACCESS_TOKEN` as secrets in a Rush Project and start the session in that Project with `POST /o/{org}/p/{project}/sessions`; the agent reads them as environment variables. A Storefront token is meant for public storefront reads, so a development store's token is enough.

### Why not run Lighthouse against my production URL?

You can, and the prompt can name it. Building in the sandbox lets the agent tie each audit to the exact source file at the commit it built, and to measure a branch before it ships. Against production, the scores also include your CDN and hosting.

### Will it change my code?

No. The prompt says to change no code, and the result is a report and the raw Lighthouse files. To try the fixes, ask the same session in a follow-up to make them on a branch and run Lighthouse again.

### How noisy are the scores?

Lighthouse varies from run to run, so the agent runs each page three times per form factor and reports the median. The transcript keeps all three runs, so you can see the spread.