# Add Lighthouse CI to a Hugo Docs Site

Yes. An agent adds Lighthouse CI to your Hugo site: a lighthouserc over the built public directory, pages in every language, score assertions, a workflow, and a PR.

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

## What the agent does

The agent reads how the site is built and tested before it adds a third tool, because a Hugo site with modules and npm scripts has its own rules. In a site laid out like docsy/docsy-example, `hugo.yaml` sets `baseURL` to `https://example.docsy.dev`, pulls the Docsy theme as a Hugo module through `go.mod`, and serves three languages, English in `content/en`, Norwegian in `content/no` and Persian in `content/fa` with `direction: rtl`. `package.json` pins `hugo-extended` at 0.166.0, requires Node 24 and npm 11.18 (`.nvmrc` says 24.22.1), and builds through a chain of scripts: `build` runs `_hugo-dev` with `-DFE` and a `BASE_URL`, `build:production` runs `hugo --cleanDestinationDir --minify`, and `install:safe` is `npm ci --ignore-scripts`. `test:site` runs `node --test` over `tests/*.test.mjs`, which read pages out of `public/` after a build, and `tests/npm-scripts.test.mjs` guards the shape of the scripts themselves. `.github/workflows/links.yaml` already does the full dance on pull requests: `setup-go`, `setup-node` from `.nvmrc` with npm cache, `npm ci`, `npm run update:docsy:pack`, the npm-scripts test, a pinned `lychee` install, `npm run check:links` and a drift check that fails if generated files changed. `netlify.toml` builds previews with `build:preview` and production with `build:production`. `.gitignore` ignores `/public` and `resources/`.

The agent adds `@lhci/cli`, current release 0.15.1, as a devDependency, and `.lighthouserc.json` at the root. `ci.collect.staticDistDir` is `public`, so Lighthouse CI serves the built site itself and no server is needed, and `ci.collect.url` lists the pages that stand for the site: the English home page, `/docs/`, one page under `/docs/getting-started/`, `/blog/`, the Norwegian `/no/docs/` and the Persian `/fa/docs/`, the last because an RTL page is where a theme's layout scores diverge. `numberOfRuns` is set so a flaky metric does not fail a build on one sample. `ci.assert` uses the `lighthouse:recommended` preset with the audits that depend on a live network, such as `uses-http2` and `is-on-https`, turned off for a static server, and the four category scores as `error` thresholds that the agent sets from the scores it measures in its sandbox rather than from a number it wishes were true. `ci.upload.target` is `temporary-public-storage`, so every run links to a full report without an account.

The workflow, `.github/workflows/lighthouse.yaml`, copies the setup steps of `links.yaml` line for line, including the pinned action shas, builds with `npm run build:production -- --baseURL http://localhost/` so internal links resolve against the static server, and runs `npx lhci autorun`. It runs on pull requests and on pushes to `main`, with the same `permissions: contents: read`. Because `tests/npm-scripts.test.mjs` guards the scripts, the agent reads it before adding a `check:lighthouse` script that builds and runs `lhci autorun`, and keeps the naming it expects; `package-lock.json` changes for the one new package, and nothing under `packages/hugoautogen` moves, so the links workflow's drift check stays green. The Google search engine id, the Netlify config and the theme are untouched.

To check it, the agent runs `npm ci`, `npm run update:docsy:pack`, the production build and `npx lhci autorun` in its sandbox, reads the per-URL scores, sets the thresholds just under them, and runs once more to show the assertions pass. It runs `node --test tests/npm-scripts.test.mjs` to show the new script is accepted, runs `npm run _is:clean` to show the drift check would pass, and runs `zizmor` over the new workflow the way `zizmor.yaml` does.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add Lighthouse CI to this Hugo site. Read hugo.yaml, package.json and its scripts, .nvmrc, netlify.toml, .github/workflows/links.yaml, tests/npm-scripts.test.mjs and the content directories first. Add @lhci/cli as a devDependency and a .lighthouserc.json that serves the built public directory with staticDistDir, lists the home page, a docs page, a getting-started page, the blog index and one docs page in each other language including the RTL one, uses the lighthouse:recommended preset with network-only audits turned off, asserts the four category scores at thresholds you set from your own measurements, and uploads to temporary public storage. Add a check:lighthouse script that the npm-scripts test accepts, and a lighthouse workflow that copies the setup steps and pinned actions of links.yaml, builds with build:production and a localhost baseURL, and runs lhci autorun on pull requests and pushes to main. Run the build and lhci in the sandbox, show the scores per page, confirm the npm-scripts test and the drift check pass, and open a pull request with the output.",
  "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` and `.github/workflows/lighthouse.yaml`, and changes `package.json` and `package-lock.json`. Its description pastes the scores per URL from the sandbox run, the thresholds chosen against them, and the `lhci autorun` output showing every assertion passing, with the temporary report link for each page.

The new `lighthouse` workflow runs on the pull request itself beside `links` and `zizmor`, so the first check is the same command on a GitHub runner, and the `links` workflow's drift check shows the generated theme files did not move. The run's record keeps the first, unthresholded run that the thresholds came from.

Before merging, a reviewer decides whether the thresholds should be tighter on the home page than on the RTL docs page, whether `numberOfRuns` is worth the extra minutes on every pull request, and whether to swap temporary storage for a Lighthouse CI server later. The theme, the content and the Netlify build are unchanged.

## Run it on every pull request to the docs site

The workflow is the automation: once merged, every pull request builds the site and scores the listed pages, and a theme change that drops a category below its threshold fails the check with the report linked. A team with several Hugo sites sends this body once per repository to `POST /o/{org}/sessions`, each with its own 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 build: a site that builds with a plain `hugo` command and no npm gets the CLI installed in the workflow instead of `package.json`, and a single-language site gets a shorter URL list. A `webhook_url` on the key reports each `run.completed` with the pull request in `result`, and a `run.failed` names a site whose build broke in the sandbox before Lighthouse ran.

## Why run it on Rush?

Lighthouse CI is one config file, but on a site with Hugo modules, a guarded npm-script layout, a drift check and three languages, the config is the easy part. The agent builds the site the way its own workflow does, measures each page in its own sandbox, and sets thresholds from those numbers rather than from a default that fails on the first RTL page.

The scores, the report links and the passing assertion output stay with the run and are pasted into the pull request. Several sites can get the same change at once, each measured on its own pages.

## Frequently asked questions

### Why a static directory instead of a running server?

Because the site is static. `staticDistDir` makes Lighthouse CI serve `public/` itself, which is simpler than keeping `hugo server` alive in a workflow step and is the same HTML Netlify serves. The build uses a `localhost` base URL so links inside the pages resolve against that server.

### Where do the thresholds come from?

From the agent's own measurement in its sandbox. It runs Lighthouse CI without assertions first, reads the four category scores for each listed page, and sets each threshold just under what the site scores today, so the check guards against regressions without failing on day one. Raising them is a one-line change per category.

### Why include the Norwegian and Persian pages?

Because the theme renders them through different layouts, and the Persian pages are right-to-left. A score measured only on the English home page would miss a regression in the language menu or an RTL style. One page per language keeps the run short while covering each layout once.

### Will the drift check in the links workflow still pass?

Yes. The agent runs `npm run _is:clean` after its changes to confirm nothing under `packages/hugoautogen` or `link-cache.jsonc` moved, and the only generated file that changes is `package-lock.json`, which it commits. The npm-scripts test is run too, so the new script fits the layout that test guards.

## More Hugo jobs

- [Check for Broken Links in a Hugo Site's CI](https://getrush.ai/run/add-link-checking/hugo/)
- [Add llms.txt to a Hugo Docs Site with an Output Format](https://getrush.ai/run/add-llms-txt/hugo/)
- [Add Mermaid Diagrams to a Hugo Docsy Site](https://getrush.ai/run/add-mermaid-diagrams/hugo/)

## The same job on other stacks

- [Add Lighthouse CI to a Jekyll Site](https://getrush.ai/run/add-lighthouse-ci/jekyll/)
- [Add Lighthouse CI to a SolidJS App](https://getrush.ai/run/add-lighthouse-ci/solidjs/)
- [Add Lighthouse CI to a Vite React App](https://getrush.ai/run/add-lighthouse-ci/vite-react/)

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