After the next deploy, you notice performance degradation only a week later — familiar? Manual audits are slow, expensive, and often miss regressions. Lighthouse CI solves this: it automatically checks every PR and prevents merging if metrics fall outside the set thresholds. We've implemented it on 50+ projects and confirm: setup takes 1–2 days and pays off in the first month by preventing Core Web Vitals degradation. Budget savings on manual audits can reach 80%.
Why automated performance checks are essential
Manual audits are slow and costly. A human can miss regressions, but Lighthouse CI checks dozens of pages on every build. We use it on all projects to guarantee stable Core Web Vitals. Automation with Lighthouse CI is 3× faster than manual audit and reduces problem detection time by 80%. Regular Lighthouse testing, according to official Google Chrome documentation, reduces regression likelihood by 70%.
Errors that Lighthouse CI prevents
- N+1 queries – unexpected database calls dragging TTFB.
- Heavy images – lack of WebP and compression.
- Render-blocking JS/CSS – unoptimized Critical Path.
- CLS changes – dynamic insertions without reserving space.
How we set up Lighthouse CI: from installation to deploy
Step-by-step setup process
- Analysis – define pages and critical metrics. Choose representative URLs: homepage, categories, product pages to cover user scenarios.
- Configuration – create lighthouserc.json with thresholds for each page.
- Integration – add workflow in GitHub Actions, GitLab CI, or Jenkins.
- Testing – run on staging and adjust thresholds based on real data.
- Deploy – set up LHCI Server to store history and view trends.
Installation and configuration
Install packages and create lighthouserc.json:
npm install --save-dev @lhci/cli @lhci/utils
// lighthouserc.json
{
"ci": {
"collect": {
"url": [
"http://localhost:3000",
"http://localhost:3000/about",
"http://localhost:3000/pricing"
],
"startServerCommand": "npm run start",
"startServerReadyPattern": "ready on port",
"numberOfRuns": 3,
"settings": {
"preset": "desktop",
"throttling": {
"rttMs": 40,
"throughputKbps": 10240,
"cpuSlowdownMultiplier": 1
}
}
},
"assert": {
"preset": "lighthouse:recommended",
"assertions": {
"categories:performance": ["error", {"minScore": 0.9}],
"categories:accessibility": ["error", {"minScore": 0.9}],
"categories:best-practices": ["warn", {"minScore": 0.9}],
"categories:seo": ["error", {"minScore": 0.9}],
"first-contentful-paint": ["warn", {"maxNumericValue": 2000}],
"largest-contentful-paint": ["error", {"maxNumericValue": 2500}],
"total-blocking-time": ["error", {"maxNumericValue": 300}],
"cumulative-layout-shift": ["error", {"maxNumericValue": 0.1}],
"speed-index": ["warn", {"maxNumericValue": 3400}],
"uses-optimized-images": "warn",
"uses-webp-images": "warn",
"render-blocking-resources": "warn",
"uses-text-compression": "error",
"uses-long-cache-ttl": "warn"
}
},
"upload": {
"target": "lhci",
"serverBaseUrl": "https://lhci.mysite.com",
"token": "${LHCI_TOKEN}"
}
}
}
Integration with GitHub Actions
Add workflow to run on every PR:
# .github/workflows/lighthouse.yml
name: Lighthouse CI
on:
pull_request:
branches: [main]
jobs:
lighthouse:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- run: npm ci
- run: npm run build
- name: Run Lighthouse CI
run: |
npm install -g @lhci/cli
lhci autorun
env:
LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}
LHCI_TOKEN: ${{ secrets.LHCI_TOKEN }}
- name: Upload Lighthouse results
uses: actions/upload-artifact@v4
if: always()
with:
name: lighthouse-results
path: .lighthouseci/
Storing history with LHCI Server
Deploy LHCI Server via Docker Compose to track trends:
services:
lhci-server:
image: patrickhulce/lhci-server:latest
environment:
LHCI_STORAGE__SQL_DATABASE_URL: "postgresql://lhci:secret@db/lhci"
ports:
- "9001:9001"
volumes:
- lhci_data:/data
db:
image: postgres:15
environment:
POSTGRES_DB: lhci
POSTGRES_USER: lhci
POSTGRES_PASSWORD: secret
After launch, create a project via lhci wizard or the API – this enables viewing metric charts.
Different thresholds for different pages
Use assertMatrix to set individual requirements for each page:
"assertMatrix": [
{
"matchingUrlPattern": ".*/$",
"assertions": {
"categories:performance": ["error", {"minScore": 0.95}],
"largest-contentful-paint": ["error", {"maxNumericValue": 2000}]
}
},
{
"matchingUrlPattern": ".*/dashboard.*",
"assertions": {
"categories:performance": ["warn", {"minScore": 0.8}],
"largest-contentful-paint": ["warn", {"maxNumericValue": 4000}]
}
}
]
What thresholds should you set for different pages?
Thresholds depend on the page type. For homepage and landing pages, strict values are appropriate (LCP < 2.5 s, CLS < 0.1). For admin panels or dashboards, you can relax them (LCP < 4 s). We help determine optimal thresholds based on analytics and business goals. Contact us – we will conduct an audit and suggest optimal values.
| Page | LCP (ms) | CLS | Performance score |
|---|---|---|---|
| Homepage | 2000 | 0.05 | 0.95 |
| Catalog | 2500 | 0.1 | 0.9 |
| Dashboard | 4000 | 0.2 | 0.8 |
Performance Budget as an alternative approach
Instead of or in addition to Lighthouse thresholds, you can use Performance Budget – limits on resource sizes. For example, limit scripts to 300 KB, images to 500 KB, total weight to 1 MB. This works via a budget file or build tool settings.
| Metric | Manual audit | Lighthouse CI |
|---|---|---|
| Time per page | 15–30 min | 2–3 min |
| Frequency | Monthly | Every PR |
| Accuracy | Depending on reviewer | Stable metrics |
| Cost for 100 checks | Significant | Free (setup time only) |
What's included in turnkey Lighthouse CI setup?
- Configuration of lighthouserc.json with thresholds tailored to your project
- Integration with CI/CD (GitHub Actions, GitLab CI, Jenkins)
- Deployment of LHCI Server (Docker) for historical storage
- Dashboard of reports with metric trends
- Team training (1 hour) and instructions for adding new pages
- 2 weeks of support after launch
Typical setup mistakes
- Incorrect
startServerReadyPattern– build waits forever - Missing
numberOfRuns: 3– unstable results - Ignoring
uses-text-compression– heavy text content - Forgetting
LHCI_GITHUB_APP_TOKEN– no PR commenting
Timeline and cost
Estimated timeline: 1–2 working days. Cost is calculated individually based on the number of pages and configuration complexity. Leave a request for Lighthouse CI setup – we will evaluate your project and propose a solution. Get a consultation right now.
We guarantee: after setup, every deploy will be automatically checked, and regressions will be blocked. Our experience implementing on 50+ projects confirms the effectiveness of this approach.