# Audit Performance of an Astro Site with Lighthouse Yes. An agent builds your Astro site in a sandbox, runs Lighthouse in the browser on key pages and returns lighthouse.md tying each fix to a file in the repo. [Run this on Rush](https://cloud.getrush.ai/run/lighthouse-audit/astro/). ## What the agent does The agent clones the repository and installs with the lockfile's package manager. On withastro/starlight that means a pnpm workspace (`packageManager: "pnpm@11.22.0"`, `pnpm-workspace.yaml` including `packages/**/*`, `examples/**/*` and `docs`), Astro `^7.2.10` at the root, and the docs site in `docs/` (`starlight-docs`) depending on `@astrojs/starlight` as `workspace:*`, `sharp` `^0.35.3`, and `@astro-community/astro-embed-youtube`. The docs `astro.config.mjs` sets `site` to `https://starlight.astro.build/`, enables Starlight with many locales, a logo pair under `docs/src/assets`, and `og.jpg` in `docs/public`. It builds the docs package (`pnpm --filter starlight-docs build` or `pnpm build` inside `docs/` after workspace packages are built as the root `build` script expects) and serves the production output locally in the sandbox. It does not deploy to Netlify or change `astro.config.mjs`. In the sandbox browser it runs Lighthouse against the docs home (`/` from `docs/src/content/docs/index.mdx`, the splash hero using `hero-star.webp`) and two long guide pages such as `/guides/i18n/` (`guides/i18n.mdx`, ~400 lines) and `/guides/site-search/` (`guides/site-search.mdx`, which documents Pagefind). Lighthouse runs with desktop and mobile settings only if the prompt asks for both; the default is one form factor per page so the five recommendations stay comparable. The agent saves each JSON under a stable name (`lighthouse-home.json`, `lighthouse-guides-i18n.json`, …) beside `lighthouse.md`. Network conditions are the Lighthouse defaults in the sandbox browser, not your office Wi-Fi. From each Lighthouse result it records performance, accessibility, best-practices and SEO scores, then maps the top opportunities to files in the repo: large hero image → `docs/src/assets/hero-star.webp` and the splash frontmatter in `index.mdx`; render-blocking or unused JavaScript → Starlight client islands and Pagefind UI (`pagefind` / `@pagefind/default-ui` in `@astrojs/starlight`); font or CSS weight → styles under `packages/starlight` and `docs/src/assets/landing.css`; third-party script → the Fathom snippet in `astro.config.mjs` `head`. Recommendations that Lighthouse cannot tie to a path stay labeled as environment or hosting concerns. It writes `lighthouse.md` with the scores, the five changes that would help most (each with the file path), and attaches the raw Lighthouse JSON as additional artifacts. No source file is modified. ## Start it with one API call `POST https://api.prix.dev/o/{org}/sessions` ```json { "agent": "claude", "input": "Clone https://github.com/withastro/starlight, make a production build, serve it in the sandbox, and run Lighthouse in the browser on the docs home and two long docs pages. Write lighthouse.md with the scores, the five changes that would help most, and for each the file in the repo that causes it. Attach the Lighthouse JSON. 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 the Lighthouse JSON files as session artifacts. The Markdown lists scores per URL and five prioritized changes with repo paths; the JSON is the unmodified Lighthouse output for each page. A docs engineer verifies the file paths exist, decides which image or script changes to take, and can ask a follow-up on the same session to implement the first fix as a pull request. Nothing in the default branch changes until that separate step. ## Run it on every docs release or weekly Schedule a weekly run, or trigger on publishes of the docs site, with this prompt. Each run builds from the current default branch so regressions in `hero-star.webp`, Pagefind or third-party scripts show up as score drops. On `run.completed`, archive the JSON next to the deploy and open an issue only when performance falls below a threshold you set. ## Why run it on Rush? Running Lighthouse on a laptop against `astro dev` measures the wrong thing; a production build in a clean sandbox matches what users hit. Rush builds, serves and drives the browser there, and keeps the JSON with the session. Your machine's Chrome extensions and network do not skew the scores, and several sites can be audited in parallel without juggling local ports. Starlight docs are image- and search-heavy; local guesses about Pagefind or hero weight are weaker than a production build measured in a clean browser. The report ties each opportunity to a path under `docs/` or `packages/starlight` so the next change has an owner. ## Frequently asked questions ### Does it change any Astro or Starlight source? No. The prompt says change no code. You get Markdown and JSON artifacts only. A follow-up can turn a recommendation into a PR if you ask. ### Why production build instead of astro dev? Dev mode skips minification and often skips Pagefind and image optimization. Lighthouse numbers from `astro build` output are the ones that matter for a shipped docs site. ### Can I pick different pages? Yes. Name the paths in the prompt. The default of home plus two long guides matches Starlight's real content shape (splash index and dense MDX guides). ### Will Fathom or other analytics run? The agent serves the built site locally; third-party scripts in `astro.config.mjs` may still be present in the HTML. The report notes third-party script cost when Lighthouse attributes time to them. ### Does the monorepo root need a full packages build first? Yes when `docs` depends on `workspace:*` Starlight. The agent builds workspace packages the docs package imports before `astro build` in `docs/`, following the root `package.json` scripts rather than inventing a one-off command.