Automated Lighthouse Checks
Add the Lighthouse CI GitHub Action, set performance and accessibility score thresholds, and block merges that regress Core Web Vitals.
Automated Lighthouse Checks is a free Frontend Academy lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Frontend Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Why Automate Lighthouse?
Manual Lighthouse runs catch performance regressions late — usually after a real user complains. Automated Lighthouse CI runs on every PR, fails builds that regress key metrics, and trends scores over time. Treat performance like a test suite.
Lighthouse CI
The open-source Lighthouse CI (lhci) toolset by Google: runs Lighthouse multiple times, takes the median, asserts against thresholds, and uploads results.
npm install -D @lhci/cli
# Run locally:
npx lhci autorunlighthouserc.json — Configuration
Configure URLs to test, number of runs, and assertions.
// lighthouserc.json
{
"ci": {
"collect": {
"url": [
"http://localhost:3000",
"http://localhost:3000/blog",
"http://localhost:3000/pricing"
],
"numberOfRuns": 5,
"startServerCommand": "npm run start"
},
"assert": {
"assertions": {
"categories:performance": ["error", { "minScore": 0.9 }],
"categories:accessibility": ["error", { "minScore": 0.95 }],
"categories:seo": ["warn", { "minScore": 0.9 }],
"largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
"total-blocking-time": ["error", { "maxNumericValue": 200 }],
"cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }]
}
},
"upload": {
"target": "temporary-public-storage"
}
}
}GitHub Action Integration
The official treosh/lighthouse-ci-action runs lhci on every PR and posts a status check.
# .github/workflows/lighthouse.yml
name: Lighthouse CI
on: [pull_request]
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: '20', cache: 'npm' }
- run: npm ci && npm run build
- uses: treosh/lighthouse-ci-action@v11
with:
configPath: ./lighthouserc.json
uploadArtifacts: true
temporaryPublicStorage: trueMedian of Multiple Runs
Lighthouse scores vary between runs because of timing noise. numberOfRuns: 5 takes the median — stable enough to assert against. Below 3 runs gives flaky results.
Performance Budgets
Beyond scores, set hard budgets on resource size and counts. The build fails if budgets are exceeded.
// budget.json
[
{
"resourceSizes": [
{ "resourceType": "script", "budget": 300 },
{ "resourceType": "image", "budget": 100 }
],
"resourceCounts": [
{ "resourceType": "third-party", "budget": 10 }
]
}
]
// lighthouserc.json:
"collect": {
"settings": { "budgetsPath": "./budget.json" }
}Lighthouse CI Server
Self-host the LHCI server to retain historical data, see trend charts, and compare branches over time. Or use temporary public storage for one-off PR results.
Testing Authenticated Pages
Use Puppeteer scripts to log in before Lighthouse runs.
// lighthouserc.json
"collect": {
"puppeteerScript": "./lighthouse-login.js",
"url": ["http://localhost:3000/dashboard"]
}
// lighthouse-login.js
module.exports = async (browser, context) => {
const page = await browser.newPage();
await page.goto('http://localhost:3000/login');
await page.fill('#email', 'test@example.com');
await page.fill('#password', 'test123');
await page.click('button[type=submit]');
await page.waitForNavigation();
};Slack/Discord Notifications
Pipe LHCI results to your team chat — performance regressions deserve the same attention as test failures.
Mobile vs Desktop
Lighthouse defaults to mobile (slow 4G + mid-tier CPU). For desktop, set preset: 'desktop'. Most production apps should audit both — separate jobs in CI.
Calibrating Thresholds
Start with current scores as baselines. Don't fail PRs day 1 — log and warn first. Once your team is used to the workflow, ratchet up the thresholds.
Beyond Lighthouse
Lighthouse is lab data. Pair with real user monitoring (RUM): web-vitals npm package + your analytics, or services like SpeedCurve and Calibre, give true-world performance trends.
Quick Check
Why does Lighthouse CI typically take the median of multiple runs (e.g. 5) rather than a single run?
Recap: Automated Lighthouse
lhci autorun integrates with CI. Configure in lighthouserc.json: URLs, runs (5+), assertions on categories and metrics, performance budgets. treosh/lighthouse-ci-action for GitHub. Self-host LHCI server for trends. Use Puppeteer scripts for authenticated pages. Audit mobile + desktop. Start with warnings; tighten thresholds over time. Pair with RUM for full picture.
Frequently asked questions
Is the “Automated Lighthouse Checks” lesson free?
Yes — the full text of “Automated Lighthouse Checks” is free to read here on the web, and the Frontend Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Frontend Academy course, upgrade to CoddyKit PRO.
What will I learn in “Automated Lighthouse Checks”?
Add the Lighthouse CI GitHub Action, set performance and accessibility score thresholds, and block merges that regress Core Web Vitals. You practise Frontend Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Frontend Academy?
No prior experience is required. Frontend Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Automated Lighthouse Checks” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Frontend Academy lesson?
Yes. Every Frontend Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.