docs: Lighthouse CI on Vercel preview deploys by havardljohansen · Pull Request #4 · frontkom/night-shift

havardljohansen · 2026-05-06T09:22:31Z

Summary

Adds docs/lighthouse-ci-vercel.md — a copy-pasteable writeup for setting up Lighthouse CI on Vercel preview deploys. Works with any framework on Vercel (Next.js, Astro, Remix, Nuxt, plain static, etc.) since the trigger is Vercel's deployment_status GitHub event, which is platform-level, not framework-level.

Requested in the #night-shift Slack thread (Per Andre: "Do you have a writeup or skill on how to set up Lighthouse CI on a Next project so I can replicate it on my side?").

Replaces the closed PR #3 which was opened from a fork before write access was granted.

What it covers

Two files (workflow + .lighthouserc.cjs) with inline comments explaining every non-obvious choice.
The five gotchas that bite first-time LHCI setups, each paired with the mitigation in this config:
1. pull_request trigger races Vercel's preview build → use deployment_status
2. GH-runner ±10pt variance → numberOfRuns: 3 + median
3. PWA audits drag a non-PWA score → no lighthouse:no-pwa preset on day one
4. Default URL list = / only → explicit urls array
5. Auth pages can't be Lighthouse'd → public pages only
Optional Lighthouse CI GitHub App install for PR comments.
Tightening path: warn → error, add preset, make a required check.

Why a separate doc, not a manifest task

This is infrastructure setup — a one-time per-repo configuration. Once LHCI is running, the audit task PR #2 can consume its signal (or its own fresh runs). The doc explicitly frames itself as complementary to #2, not in competition.

Pilot reference

frontkom/merkur-frontend#94 is the working pilot the doc is genericized from.

Genericized writeup for setting up Lighthouse CI on a Next.js app on Vercel, paired with the merkur-frontend pilot (PR #94). Captures the five common gotchas (preview-build race, runner variance, PWA score drag, single-URL coverage, auth/draft pages) and the pilot-week "warn first, tighten later" approach. Lands in docs/ next to roadmap.md so it's discoverable from the contributor side. Closing section frames it as complementary to Henrik's PR #2 (run-Lighthouse-from-task), not in competition: the .lighthouserc.cjs page list is the same list improve-performance would target if pointed at the repo. Requested by Per Andre via #night-shift Slack thread. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The trigger (deployment_status) and the LHCI config are platform-level, not framework-level. Title + intro were narrower than the actual content. Same workflow applies to Astro, Remix, Nuxt, plain static, etc. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Forgot to stage the content edit in the rename commit. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

New task that reads the real Lighthouse CI artifact (per docs/lighthouse-ci-vercel.md) and opens a PR fixing one concrete measured violation. Complements improve-performance (heuristic, source-read) without replacing it. 1. Pre-flight: skip if open night-shift/lhci-fix PR exists for this scope. 2. Download the latest successful LHCI workflow artifact via `gh run download`. 3. Parse `lhr-*.json` reports for failing audits with concrete `details.items[]` pointing at specific files / resources. 4. Pick the highest-leverage one (mobile beats desktop, earlier key pages beat later, larger measured savings beats smaller). 5. Apply a small fix only — single component / image / config tweak. Exit silently on multi-file refactors. 6. Open a PR titled `night-shift/lhci-fix: <one-line>` with the audit ID, measured value, predicted impact, and verification checklist. - `improve-performance` is agent heuristic — it reads source and finds opportunities. Generic. Default-on. - `act-on-lhci-artifact` is data-driven — it consumes real Lighthouse measurements from preview deploys. Opt-in via `LHCI enabled: yes` in the project's Night Shift Config since not all projects have LHCI set up. - They catch different things and can coexist on the same project without conflict (each has its own slug-based dedup pre-flight). Project's `CLAUDE.md` Night Shift Config: ``` - LHCI enabled: yes - LHCI artifact source: github-actions # default; `vercel-comment` exits silently - LHCI workflow: lighthouseci.yml # filename; defaults to this ``` If `LHCI enabled` isn't `yes`, the task exits silently. Setup for LHCI itself lives in `docs/lighthouse-ci-vercel.md` (PR #4, still open). Slotted at `order: 4.5` (between improve-performance@4 and dep-audit@5) in the `audits` bundle. Same `scope: app`, `mode: pull-request`, `slug: lhci-fix`. Bumps NIGHT_SHIFT_VERSION 2026-05-19b → 2026-05-20a per AGENTS.md. Context for Per Andre: this is the response to "do you want to do a PR on using the Lighthouse CI artifact for Merkur project? Could also be a separate, new task" — went with the separate-task path since the existing improve-performance task is heuristic, not artifact-driven, and folding them would force every project to choose one or the other. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

New task that reads the real Lighthouse CI artifact (per docs/lighthouse-ci-vercel.md) and opens a PR fixing one concrete measured violation. Complements improve-performance (heuristic, source-read) without replacing it. 1. Pre-flight: skip if open night-shift/lhci-fix PR exists for this scope. 2. Download the latest successful LHCI workflow artifact via `gh run download`. 3. Parse `lhr-*.json` reports for failing audits with concrete `details.items[]` pointing at specific files / resources. 4. Pick the highest-leverage one (mobile beats desktop, earlier key pages beat later, larger measured savings beats smaller). 5. Apply a small fix only — single component / image / config tweak. Exit silently on multi-file refactors. 6. Open a PR titled `night-shift/lhci-fix: <one-line>` with the audit ID, measured value, predicted impact, and verification checklist. - `improve-performance` is agent heuristic — it reads source and finds opportunities. Generic. Default-on. - `act-on-lhci-artifact` is data-driven — it consumes real Lighthouse measurements from preview deploys. Opt-in via `LHCI enabled: yes` in the project's Night Shift Config since not all projects have LHCI set up. - They catch different things and can coexist on the same project without conflict (each has its own slug-based dedup pre-flight). Project's `CLAUDE.md` Night Shift Config: ``` - LHCI enabled: yes - LHCI artifact source: github-actions # default; `vercel-comment` exits silently - LHCI workflow: lighthouseci.yml # filename; defaults to this ``` If `LHCI enabled` isn't `yes`, the task exits silently. Setup for LHCI itself lives in `docs/lighthouse-ci-vercel.md` (PR #4, still open). Slotted at `order: 4.5` (between improve-performance@4 and dep-audit@5) in the `audits` bundle. Same `scope: app`, `mode: pull-request`, `slug: lhci-fix`. Bumps NIGHT_SHIFT_VERSION 2026-05-19b → 2026-05-20a per AGENTS.md. Context for Per Andre: this is the response to "do you want to do a PR on using the Lighthouse CI artifact for Merkur project? Could also be a separate, new task" — went with the separate-task path since the existing improve-performance task is heuristic, not artifact-driven, and folding them would force every project to choose one or the other. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

havardljohansen and others added 3 commits May 6, 2026 09:54

docs: update title and intro to match broader scope

157cf91

Forgot to stage the content edit in the rename commit. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

havardljohansen requested a review from perandre May 6, 2026 10:08

havardljohansen mentioned this pull request May 20, 2026

feat(tasks): add act-on-lhci-artifact (data-driven perf companion) #19

Merged

4 tasks

perandre merged commit a6e6bd5 into main May 28, 2026

perandre deleted the docs/lighthouse-ci-nextjs branch May 28, 2026 05:55

perandre mentioned this pull request May 28, 2026

docs: LHCI gotcha — deployment_status runs from the default branch #23

Merged

Navigation Menu

Uh oh!

docs: Lighthouse CI on Vercel preview deploys - #4

docs: Lighthouse CI on Vercel preview deploys#4
perandre merged 3 commits into
mainfrom
docs/lighthouse-ci-nextjs

havardljohansen commented May 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

havardljohansen commented May 6, 2026

Summary

What it covers

Why a separate doc, not a manifest task

Pilot reference

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants