# Unlighthouse

> Google Lighthouse for your entire site.

Canonical Origin: https://unlighthouse.dev/

## LLM Resources

- [Full Content](https://unlighthouse.dev/llms-full.txt): Complete page content in markdown format.

---

- **Page:** Free Lighthouse & Core Web Vitals Tools · Unlighthouse
- **Source:** https://unlighthouse.dev/tools
- **Description:** Free bulk Core Web Vitals checker, Lighthouse score calculator, CLS debugger, LCP finder, and more. Test multiple pages at once with no signup.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Performance **Tools

Free interactive tools to understand and improve your Lighthouse scores.

[<h2>**Bulk PageSpeed Test**</h2>Test up to 10 URLs at once with PageSpeed Insights. Get performance scores for multiple pages in one batch.**Batch Testing****Performance****Core Web Vitals**](https://unlighthouse.dev/tools/bulk-pagespeed) [<h2>**Core Web Vitals Checker**</h2>Check if your page passes Google's Core Web Vitals. Test LCP, CLS, and INP with lab and real user data.**LCP****CLS****INP****Core Web Vitals**](https://unlighthouse.dev/tools/cwv-checker) [<h2>**Core Web Vitals History**</h2>Track real user performance over 25 weeks. See how your LCP, CLS, and INP trends change over time with CrUX data.**Field Data****Trends****CrUX**](https://unlighthouse.dev/tools/cwv-history) [<h2>**TTFB Checker**</h2>Test Time to First Byte with real Chrome user data. Compare field vs lab TTFB and track server response trends.**TTFB****Server Response****CrUX**](https://unlighthouse.dev/tools/ttfb-checker) [<h2>**CWV Compare**</h2>Compare Core Web Vitals across multiple websites. Benchmark your site against competitors with real Chrome user data.**Competitor Analysis****CrUX****Benchmarking**](https://unlighthouse.dev/tools/cwv-compare) [<h2>**Lighthouse Report Viewer**</h2>Upload your Lighthouse JSON report to visualize scores, metrics, and audits interactively.**All Categories****Audits****Metrics**](https://unlighthouse.dev/tools/lighthouse-report-viewer) [<h2>**Lighthouse Score Calculator**</h2>Calculate your performance score interactively. Adjust metrics to see how they impact your overall Lighthouse score.**FCP****SI****LCP****TBT****CLS**](https://unlighthouse.dev/tools/lighthouse-score-calculator) [<h2>**LCP Element Finder**</h2>Identify which element is your Largest Contentful Paint and get actionable recommendations to improve it.**LCP****Core Web Vital**](https://unlighthouse.dev/tools/lcp-finder) [<h2>**INP Analyzer**</h2>Analyze Interaction to Next Paint issues. Find slow event handlers and optimize responsiveness.**INP****Core Web Vital**](https://unlighthouse.dev/tools/inp-analyzer) [<h2>**CLS Debugger**</h2>Debug Cumulative Layout Shift issues. Identify elements causing unexpected layout shifts.**CLS****Core Web Vital**](https://unlighthouse.dev/tools/cls-debugger) [<h2>**HAR File Viewer**</h2>Analyze HTTP Archive files with network waterfall, request timing, resource breakdown, and protocol distribution. Entirely client-side.**Network Waterfall****Request Analysis****Performance**](https://unlighthouse.dev/tools/har-viewer) [<h2>**JSON Size Analyzer**</h2>Calculate JSON payload size with minification savings, gzip/brotli estimates, key contributions, and duplicate key analysis. Entirely client-side.**Size Analysis****Minification****Compression**](https://unlighthouse.dev/tools/json-size) [<h2>**Page Size Checker**</h2>Test page weight with resource breakdown, third-party analysis, unused code detection, and HTTP Archive percentile comparison.**Page Weight****Resources****Third Parties**](https://unlighthouse.dev/tools/page-size) [<h2>**PageSpeed Insights Performance**</h2>Get detailed PageSpeed Insights performance data with field and lab metrics.**Performance****Field Data**](https://unlighthouse.dev/tools/pagespeed-insights-performance)

---

- **Page:** Learn Lighthouse &amp; Web Vitals: Performance Guides · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse
- **Description:** Free guides to improve Lighthouse scores and Core Web Vitals. Fix LCP, CLS, INP, accessibility, and SEO audits with actionable tutorials and tools.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Learn Google Lighthouse**

Guides and tutorials for improving your site's Core Web Vitals and performance. All guides include authoritative citations from Google and real-world statistics.

## **Core Web Vitals **

Core Web Vitals are [~~Google's ranking factor~~](https://developers.google.com/search/docs/appearance/core-web-vitals) for measuring user experience. Only [~~48% of mobile sites~~](https://almanac.httparchive.org/en/2024/performance) currently pass all three metrics.

[**59%** mobile pass rate<h3>**Largest Contentful Paint (LCP)**</h3>Improve loading performance. Only 59% of mobile sites pass.](https://unlighthouse.dev/learn-lighthouse/lcp) [**79%** mobile pass rate<h3>**Cumulative Layout Shift (CLS)**</h3>Eliminate layout shifts. 79% of mobile sites pass.](https://unlighthouse.dev/learn-lighthouse/cls) [**New** replaced FID<h3>**Interaction to Next Paint (INP)**</h3>Make interactions responsive. Replaced FID in March 2024.](https://unlighthouse.dev/learn-lighthouse/inp)

## **Guides **

[<h3>**Core Web Vitals Overview**</h3>What they measure, why they matter, and how to test them.](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) [<h3>**Bulk Lighthouse Testing**</h3>Test every page, not just the homepage.](https://unlighthouse.dev/learn-lighthouse/bulk-lighthouse-testing) [<h3>**Lighthouse CI**</h3>Automate audits in your CI/CD pipeline with @lhci/cli.](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci) [<h3>**PageSpeed Insights API**</h3>Fetch Lighthouse data programmatically with Node.js or Python.](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api) [<h3>**PSI vs Lighthouse**</h3>Why scores differ between PageSpeed Insights and local Lighthouse.](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-vs-lighthouse) [<h3>**Lighthouse with Playwright**</h3>Run audits on authenticated pages and SPAs.](https://unlighthouse.dev/learn-lighthouse/playwright)

## **Audit Categories **

[<h3>**SEO Audits**</h3>All 8 Lighthouse SEO checks explained with fixes.](https://unlighthouse.dev/learn-lighthouse/seo) [<h3>**Accessibility**</h3>

16 audit guides covering ARIA, contrast, and screen readers.](https://unlighthouse.dev/learn-lighthouse/accessibility) [<h3>**Best Practices**</h3>HTTPS, console errors, deprecated APIs, and more.](https://unlighthouse.dev/learn-lighthouse/best-practices)

## **Free Tools **

[<h3>**Bulk PageSpeed Test**</h3>Test multiple URLs at once with the PageSpeed Insights API.](https://unlighthouse.dev/tools/bulk-pagespeed) [<h3>**Core Web Vitals Checker**</h3>Check if a page passes all three Core Web Vitals.](https://unlighthouse.dev/tools/cwv-checker) [<h3>**CWV Comparison**</h3>Compare Core Web Vitals across 2-4 sites side-by-side.](https://unlighthouse.dev/tools/cwv-compare)

### **Test Your Entire Site **

Most tools only test one page at a time. Unlighthouse scans your entire site and shows scores for every page.

[**Get Started **](https://unlighthouse.dev/guide/getting-started/installation)

---

- **Page:** Bulk PageSpeed &amp; Core Web Vitals Test - Free Multi-URL Tool · Unlighthouse
- **Source:** https://unlighthouse.dev/tools/bulk-pagespeed
- **Description:** Free bulk Core Web Vitals and PageSpeed test. Check LCP, CLS, INP for up to 10 URLs at once. Get Lighthouse scores and CWV pass/fail for multiple pages.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Bulk PageSpeed **Test

Test up to 10 URLs at once with Google's PageSpeed Insights API. Get Lighthouse performance scores, Core Web Vitals, and optimization insights.

**Bulk PageSpeed Test**

**Enter URLs **(one per line, max 10)

0/10 URLs

Device:

Enter URLs to run a bulk PageSpeed test

Test up to 10 URLs at once

## **Frequently Asked Questions **

<details>

<summary>**01**

### **What is bulk PageSpeed testing?**

</summary>

Bulk PageSpeed testing lets you analyze multiple URLs simultaneously using the PageSpeed Insights API. Instead of testing pages one at a time, you can submit up to 10 URLs and get Lighthouse performance scores, Core Web Vitals, and audit results for all pages at once.

</details>

<details>

<summary>**02**

### **How do I use the PageSpeed Insights API for bulk testing?**

</summary>

The PageSpeed Insights API (pagespeedonline/v5/runpagespeed) accepts a URL parameter and returns Lighthouse results as JSON. This tool handles the API calls for you, but for programmatic access you can call the API directly with your own API key for higher rate limits.

</details>

<details>

<summary>**03**

### **Is there a limit to bulk PageSpeed testing?**

</summary>

This free tool allows testing up to 10 URLs at once. The PageSpeed Insights API has rate limits (400 requests per day for anonymous users, 25,000 with an API key). For scanning entire sites with hundreds of pages, use Unlighthouse CLI instead.

</details>

<details>

<summary>**04**

### **What metrics does bulk PageSpeed testing show?**

</summary>

Each URL gets a full Lighthouse audit including: Performance score (0-100), Core Web Vitals (LCP, CLS, TBT/INP), First Contentful Paint, Speed Index, and a pass/fail summary. Results help identify which pages need optimization.

</details>

<details>

<summary>**05**

### **When should I use bulk testing vs full site scanning?**

</summary>

Use bulk testing for quick checks of specific pages like landing pages, product pages, or comparing competitor URLs. For comprehensive site-wide analysis with all pages automatically discovered, use Unlighthouse CLI which crawls your sitemap and tests every page.

</details>

### **Related Guides **

[**Fix LCP Issues **](https://unlighthouse.dev/learn-lighthouse/lcp) [** Fix CLS Issues **](https://unlighthouse.dev/learn-lighthouse/cls) [** Bulk Testing Guide **](https://unlighthouse.dev/learn-lighthouse/bulk-lighthouse-testing) [** Understand Speed Index **](https://unlighthouse.dev/glossary/speed-index)

### **Need to scan your entire site? **

Unlighthouse automatically discovers and audits hundreds of pages on your site. Get comprehensive performance insights with a single command.

$ npx unlighthouse --site example.com

[**Try Unlighthouse CLI (Free) **](https://unlighthouse.dev/guide/getting-started) [** Automate Audits in CI **](https://unlighthouse.dev/integrations/ci)

---

- **Page:** Core Web Vitals Test - Free CWV Checker · Unlighthouse
- **Source:** https://unlighthouse.dev/tools/cwv-checker
- **Description:** Check if your page passes Google's Core Web Vitals. Test LCP, CLS, and INP with lab and real user data. Free tool with actionable recommendations.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Core Web Vitals **Test

Check if your page passes Google's Core Web Vitals with lab and real user data.

**Core Web Vitals Assessment**

Enter a URL to check Core Web Vitals

## **Frequently Asked Questions **

<details>

<summary>**01**

### **What are Core Web Vitals?**

</summary>

Core Web Vitals are three metrics Google uses to measure user experience: LCP (loading speed), CLS (visual stability), and INP (interactivity). They are a confirmed ranking factor in Google Search.

</details>

<details>

<summary>**02**

### **What is a good Core Web Vitals score?**

</summary>

Good scores are: LCP under 2.5 seconds, CLS under 0.1, and INP under 200 milliseconds. To pass Core Web Vitals, at least 75% of page loads must meet the "good" threshold for all three metrics.

</details>

<details>

<summary>**03**

### **What's the difference between Lab and Field data?**

</summary>

Lab data is collected in a controlled environment (Lighthouse). Field data is from real users via the Chrome User Experience Report (CrUX). Field data is what Google uses for ranking, but lab data helps diagnose issues.

</details>

<details>

<summary>**04**

### **Do Core Web Vitals affect SEO?**

</summary>

Yes. Core Web Vitals are a confirmed Google ranking factor as part of page experience signals. Pages that pass CWV may have a ranking advantage over those that don't, especially for competitive queries.

</details>

### **Optimize Your Core Web Vitals **

[**Fix LCP **](https://unlighthouse.dev/learn-lighthouse/lcp) [** Fix CLS **](https://unlighthouse.dev/learn-lighthouse/cls) [** Fix INP **](https://unlighthouse.dev/learn-lighthouse/inp) [** Full Guide **](https://unlighthouse.dev/learn-lighthouse/core-web-vitals)

---

- **Page:** TTFB Checker - Test Time to First Byte · Unlighthouse
- **Source:** https://unlighthouse.dev/tools/ttfb-checker
- **Description:** Free TTFB test tool. Check your server response time with real Chrome user data (CrUX). Compare field vs lab TTFB and track trends over time.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **TTFB **Checker

Test Time to First Byte with real Chrome user data and lab measurements.

**Time to First Byte**Server response time

Enter a domain to check TTFB

Measures Time to First Byte (server response time)

## **Frequently Asked Questions **

<details>

<summary>**01**

### **What is Time to First Byte (TTFB)?**

</summary>

Time to First Byte (TTFB) measures how long it takes for the browser to receive the first byte of response from the server after making a request. It includes DNS lookup, TCP connection, TLS handshake, and server processing time. A good TTFB is under 800ms.

</details>

<details>

<summary>**02**

### **Why is TTFB important for performance?**

</summary>

TTFB directly impacts all subsequent metrics like LCP and FCP. A slow server response delays everything—the browser can't start parsing HTML, downloading resources, or rendering content until TTFB completes. Improving TTFB creates a faster foundation for your entire page load.

</details>

<details>

<summary>**03**

### **What causes slow TTFB?**

</summary>

Slow TTFB is typically caused by: slow server-side processing, database query delays, no server-side caching, distance between user and server (no CDN), unoptimized backend code, shared hosting resource limits, and cold starts on serverless functions.

</details>

<details>

<summary>**04**

### **How do I improve my TTFB?**

</summary>

To improve TTFB: use a CDN to serve content closer to users, implement server-side caching (Redis, Varnish), optimize database queries, use edge rendering or SSR at the edge, upgrade hosting infrastructure, enable HTTP/2 or HTTP/3, and reduce server-side processing complexity.

</details>

<details>

<summary>**05**

### **What is the difference between origin and URL TTFB in CrUX?**

</summary>

Origin TTFB is the aggregate across all pages on your domain from real Chrome users. URL TTFB is specific to a single page. Origin data has more samples and is more stable, while URL data shows page-specific performance but may have insufficient data for low-traffic pages.

</details>

### **Learn More About Web Performance **

[**LCP Guide **](https://unlighthouse.dev/learn-lighthouse/lcp) [** Core Web Vitals **](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) [** TTFB Glossary **](https://unlighthouse.dev/glossary/ttfb)

---

- **Page:** Core Web Vitals History - Track Performance Over Time · Unlighthouse
- **Source:** https://unlighthouse.dev/tools/cwv-history
- **Description:** Free CrUX history viewer. Track 25 weeks of LCP, CLS, and INP trends from real Chrome users. Monitor Core Web Vitals changes over time.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Core Web Vitals **History

Track Core Web Vitals trends over time with 25 weeks of real Chrome user data.

**CrUX Historical Data**Field data from real Chrome users

Enter a domain to view CrUX history

Tracks real Chrome user data over 25 weeks

### **Optimize Your Core Web Vitals **

[**Full Guide **](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) [** Fix LCP **](https://unlighthouse.dev/learn-lighthouse/lcp) [** Fix CLS **](https://unlighthouse.dev/learn-lighthouse/cls) [** Fix INP **](https://unlighthouse.dev/learn-lighthouse/inp)

## **Frequently Asked Questions **

<details>

<summary>**01**

### **What is Core Web Vitals history data?**

</summary>

CrUX (Chrome User Experience Report) stores 25 weeks of real user performance data for sites with sufficient traffic. This historical data shows how your Core Web Vitals (LCP, CLS, INP) have changed over time, helping you track improvement or detect regressions.

</details>

<details>

<summary>**02**

### **Where does this historical performance data come from?**

</summary>

Historical data comes from CrUX, Google's dataset of real Chrome user experiences. Google collects anonymized performance metrics from Chrome users who have opted in. The data represents the 75th percentile (p75) of real user experiences over 28-day rolling periods.

</details>

<details>

<summary>**03**

### **Why don't I see historical data for my site?**

</summary>

CrUX only includes sites with sufficient traffic from Chrome users. New sites, low-traffic pages, or sites visited primarily by non-Chrome browsers may not have data. Origin-level data aggregates all pages and requires less traffic than URL-specific data.

</details>

<details>

<summary>**04**

### **What can I learn from Core Web Vitals trends?**

</summary>

Trends help you: correlate performance changes with deployments, detect gradual degradation before users notice, measure the impact of optimizations over time, compare mobile vs desktop performance, and identify seasonal patterns affecting user experience.

</details>

<details>

<summary>**05**

### **How often is CrUX historical data updated?**

</summary>

CrUX data is updated weekly with a new 28-day rolling window. Each data point represents the 75th percentile of user experiences during that collection period. This means changes you make today will start showing in the data within 1-4 weeks.

</details>

---

- **Page:** Bulk Core Web Vitals Test - Compare CWV Across Sites · Unlighthouse
- **Source:** https://unlighthouse.dev/tools/cwv-compare
- **Description:** Bulk test and compare Core Web Vitals across multiple websites. See how your LCP, CLS, and INP stack up against competitors with real Chrome user data.

Star Unlighthouse on GitHubUnlighthouse on GitHub

**PERFORMANCE SHOWDOWN **

# **CWV **Compare

**Pit your site against competitors. Real Chrome user data. Clear winners. **

**Core Web Vitals Comparison**• Field data from real Chrome users

**CrUX **

**Enter domains to compare **

Compare 2-4 sites using real Chrome user data

## **Frequently Asked Questions **

<details>

<summary>**01**

### **What data is being compared?**

</summary>

This tool compares real user performance data from the Chrome User Experience Report (CrUX). It shows P75 values—the experience of 75% of your users.

</details>

<details>

<summary>**02**

### **Why is there no data for a site?**

</summary>

Sites need sufficient Chrome traffic to appear in CrUX. New sites, low-traffic sites, or sites blocking data collection won't have field data available.

</details>

<details>

<summary>**03**

### **How is the winner determined?**

</summary>

For each metric, the site with the lowest (fastest/best) P75 value wins. Overall winner prioritizes Core Web Vitals pass rate, then combined metric performance.

</details>

<details>

<summary>**04**

### **Can I share this comparison?**

</summary>

Yes! The URL updates as you compare sites. Copy and share the URL to show others the same comparison results.

</details>

### **Improve Your Core Web Vitals **

[**Fix LCP **](https://unlighthouse.dev/learn-lighthouse/lcp) [** Fix CLS **](https://unlighthouse.dev/learn-lighthouse/cls) [** Fix INP **](https://unlighthouse.dev/learn-lighthouse/inp) [** Full Guide **](https://unlighthouse.dev/learn-lighthouse/core-web-vitals)

---

- **Page:** Lighthouse Scoring Calculator - Calculate Performance Scores · Unlighthouse
- **Source:** https://unlighthouse.dev/tools/lighthouse-score-calculator
- **Description:** Free interactive Lighthouse scoring calculator. See how FCP, LCP, TBT, CLS, and Speed Index weights and thresholds determine your Lighthouse performance score. Enter your metrics to calculate your score.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Lighthouse Score **Calculator

See exactly how each metric contributes to your performance score.

## **Import from PageSpeed Insights **

**Lighthouse v13 Scoring**

**82**

**First Contentful Paint**

1.8s82

0msTime until first text or image is painted9.0s

**Speed Index**

3.4s82

0msHow quickly content visually populates17.4s

**Largest Contentful Paint**** CWV **

2.5s82

0msTime until largest content element is visible12.0s

**Total Blocking Time**

200ms82

0msSum of blocking time for long tasks1.8s

**Cumulative Layout Shift**** CWV **

0.1082

0.00Movement of visible elements during load1.00

**FCP**** +8**

**SI**** +8**

**LCP**** +20**

**TBT**** +25**

**CLS**** +20**

=
**82**/ 100

## **Understanding the Metrics **

Lighthouse performance score is a weighted average of these five key metrics. Improving any of them will raise your overall score.

**FCP**

### **First Contentful Paint**

**Weight: 10% **

Time until first text or image is painted

**SI**

### [Speed Index](https://unlighthouse.dev/glossary/speed-index)

**Weight: 10% **

How quickly content visually populates

**LCP**

### **Largest Contentful Paint**

**Weight: 25% ****Core Web Vital **

Time until largest content element is visible

**TBT**

### [Total Blocking Time](https://unlighthouse.dev/glossary/tbt)

**Weight: 30% **

Sum of blocking time for long tasks

**CLS**

### **Cumulative Layout Shift**

**Weight: 25% ****Core Web Vital **

Movement of visible elements during load

## **Frequently Asked Questions **

### **How does Lighthouse calculate the performance score?**

Lighthouse calculates performance score as a weighted average of six metrics: First Contentful Paint (10%), Speed Index (10%), Largest Contentful Paint (25%), Total Blocking Time (30%), and Cumulative Layout Shift (25%). Each metric is scored 0-100 using log-normal curves based on real-world data from HTTPArchive.

### **Why do my Lighthouse scores vary between runs?**

Lighthouse scores can vary 5-10 points between runs due to: network conditions, server response time variations, third-party script loading, background processes on your device, and variability in JavaScript execution. Run multiple tests and use the median score for accuracy.

### **What is a good Lighthouse performance score?**

A score of 90-100 is considered good (green), 50-89 needs improvement (orange), and 0-49 is poor (red). Focus on reaching 90+ but don't obsess over perfect 100—the last few points have diminishing returns and normal variance makes it impractical.

### **Which metrics have the biggest impact on Lighthouse score?**

Total Blocking Time (30%) and Largest Contentful Paint (25%) together account for 55% of your score. CLS adds another 25%. To improve your score quickly, focus on reducing JavaScript execution time (TBT) and optimizing your largest above-the-fold element (LCP).

### **Why is my PageSpeed Insights score different from Chrome DevTools?**

PageSpeed Insights tests from Google's servers with a simulated mobile device, while Chrome DevTools uses your local machine and network. PSI also shows field data from real Chrome users (CrUX) which reflects actual user experience and may differ significantly from lab results.

## **Optimize Your Real-World Scores **

Lighthouse is a lab test. For production sites, use our free tools to check your real Chrome User Experience data.

[**Setup Unlighthouse **](https://unlighthouse.dev/guide/getting-started/installation) [**Learn Web Vitals **](https://unlighthouse.dev/learn-lighthouse/core-web-vitals)

---

- **Page:** Lighthouse Report Viewer - Analyze JSON Reports Online Free · Unlighthouse
- **Source:** https://unlighthouse.dev/tools/lighthouse-report-viewer
- **Description:** Free Lighthouse JSON viewer and report analyzer. Upload or paste Lighthouse JSON to view scores, Core Web Vitals, and audit details. Works with PageSpeed Insights API output and Chrome DevTools exports.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Lighthouse Report **Viewer

Upload or paste a Lighthouse JSON report to analyze scores, Core Web Vitals, and audits interactively.

**Report Viewer**

**Drop your Lighthouse JSON here **

or click to browse files

**How to export Lighthouse JSON: **

1. Open Chrome DevTools (F12)
2. Go to the Lighthouse tab
3. Run an audit
4. Click "Export" → "Save as JSON"

## **How to Read a Lighthouse Report **

Lighthouse audits your page across five categories. Each category receives a score from 0-100, with **90+** being good, **50-89** needing improvement, and **below 50** being poor.

Focus on **Performance** first—it directly impacts user experience and SEO. Within Performance, prioritize the **Opportunities** section, which shows specific improvements with estimated savings.

### **Category Quick Reference **

**Performance **

Loading speed, interactivity, visual stability

**Accessibility **

Screen readers, contrast, keyboard navigation

**Best Practices **

Security, modern APIs, image optimization

**SEO **

Meta tags, crawlability, mobile-friendliness

**PWA **

Installability, offline support, app-like experience

## **Pro Tips for Improving Your Score **

### **Start with Quick Wins **

Focus on opportunities with the highest estimated savings first. Image optimization and unused code are often easy fixes.

### **Test Multiple Times **

Lighthouse scores can vary between runs. Test 3-5 times and average the results for a more accurate picture.

### **Prioritize Core Web Vitals **

LCP, CLS, and INP directly affect search rankings. Focus on getting these green before other optimizations.

### **Test on Mobile **

Google uses mobile-first indexing. Your mobile score matters more than desktop for SEO.

### **Check Field Data **

Lab data (Lighthouse) is synthetic. Check Chrome UX Report for real-world user experience data.

### **Don't Chase 100 **

Diminishing returns after 90. A score of 90+ is excellent—spend time on features, not micro-optimizations.

## **Frequently Asked Questions **

<details>

<summary>**01**

### **How do I view a Lighthouse JSON report?**

</summary>

Upload your Lighthouse JSON file by dragging and dropping it onto this page, clicking the upload area, or pasting the JSON content directly. The viewer will parse and display your performance scores, metrics, and audit results in an interactive format.

</details>

<details>

<summary>**02**

### **How do I export a Lighthouse report as JSON?**

</summary>

In Chrome DevTools, run a Lighthouse audit then click "Save as JSON" in the report header. From the command line, run: npx lighthouse &lt;url&gt; --output=json --output-path=report.json. The PageSpeed Insights API also returns JSON that works with this viewer.

</details>

<details>

<summary>**03**

### **What information does a Lighthouse JSON report contain?**

</summary>

Lighthouse reports include performance scores (0-100), Core Web Vitals metrics (LCP, CLS, TBT), detailed audit results for performance, accessibility, best practices, SEO, and PWA categories, plus timing data, screenshots, and optimization opportunities.

</details>

<details>

<summary>**04**

### **Can I compare multiple Lighthouse reports?**

</summary>

This viewer shows one report at a time. For comparing reports over time, consider Lighthouse CI which stores historical data, or export multiple JSON reports and compare the metrics manually. The Unlighthouse CLI can scan your entire site and track changes.

</details>

<details>

<summary>**05**

### **Why use a Lighthouse report viewer instead of the HTML report?**

</summary>

JSON reports are smaller, easier to store, and work better with automation. This viewer provides the same visual experience as HTML reports, with additional features like dark mode, better mobile support, and the ability to quickly inspect specific audits.

</details>

<details>

<summary>**06**

### **Is this Lighthouse viewer free?**

</summary>

Yes, this Lighthouse JSON viewer is completely free with no signup required. Your report data stays in your browser and is never uploaded to any server. Use it as often as you need for viewing and analyzing Lighthouse reports.

</details>

<details>

<summary>**07**

### **How do I view a Lighthouse report online?**

</summary>

Use this free Lighthouse report viewer to view reports online. Upload a JSON file, paste JSON content, or load a sample report. The viewer displays all scores, Core Web Vitals metrics, performance opportunities, and audit results in an interactive format—no installation required.

</details>

Explore more Lighthouse tools

[**Score Calculator **](https://unlighthouse.dev/tools/lighthouse-score-calculator) [** PageSpeed Insights **](https://unlighthouse.dev/tools/pagespeed-insights-performance) [** Learn Lighthouse **](https://unlighthouse.dev/learn-lighthouse) [** Core Web Vitals Guide **](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) [** PSI vs Lighthouse **](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-vs-lighthouse)

---

- **Page:** LCP Element Finder - Identify Your Largest Contentful Paint · Unlighthouse
- **Source:** https://unlighthouse.dev/tools/lcp-finder
- **Description:** Free LCP test tool. Find your Largest Contentful Paint element, see timing breakdowns, and get actionable recommendations to improve loading speed.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **LCP Element **Finder

Identify which element is your Largest Contentful Paint and get actionable fixes.

**LCP Analysis**

Enter a URL to find the LCP element

## **What is Largest Contentful Paint? **

LCP measures how long it takes for the **largest visible content element** to render on screen. This is typically a hero image, headline, or large text block. Google uses LCP as one of the three [Core Web Vitals](https://web.dev/vitals/) that directly affect search rankings.

A good LCP score means users perceive your page as **loaded quickly**—even if other content is still loading in the background. The LCP element changes as the page loads, so the final LCP is measured when the largest element stops changing.

### **LCP Timeline **

0ms

Navigation

\~800ms

FCP

**2.5s **

**LCP ✓ **

LCP marks when the **largest element** finishes rendering.

## **LCP Phases Breakdown **

See how time is spent loading your largest element

Slowed 4× for clarity

Total: 2500ms

TTFB800ms

Load Delay400ms

Load Time600ms

Render Delay700ms

### **Time to First Byte**

Phase 1 of 4

**800ms**

25%

Time waiting for the server to respond with the first byte of HTML.

**How to optimize **

- Use a CDN to serve content closer to users
- Enable server-side caching

### **Resource Load Delay**

Phase 2 of 4

**400ms**

15%

Time between TTFB and when the browser starts loading the LCP resource.

**How to optimize **

- Add \<link rel="preload"> for LCP image
- Avoid lazy-loading the LCP image

### **Resource Load Duration**

Phase 3 of 4

**600ms**

25%

Time spent downloading the LCP image or video resource.

**How to optimize **

- Compress images with WebP or AVIF
- Use responsive images with srcset

### **Element Render Delay**

Phase 4 of 4

**700ms**

35%

Time from resource loaded (or TTFB for text) until the element is painted.

**How to optimize **

- Reduce JavaScript bundle size
- Use font-display: optional for web fonts

Based on [DebugBear](https://www.debugbear.com/docs/lcp-by-phase) and [web.dev](https://web.dev/articles/optimize-lcp)

### **LCP Scoring Thresholds **

Google's LCP thresholds are based on **real user data** from millions of websites. To pass Core Web Vitals, **75% of page visits** must have an LCP under 2.5 seconds.

**≤2.5s **

**Good **

**2.5-4s **

**Needs Work **

**\>4s **

**Poor **

**LCP Score Distribution **

0s**2.5s****4.0s**8s**Good****Meh****Poor**

Source: [web.dev/lcp](https://web.dev/lcp/)

### **Common LCP Elements **

What typically becomes the LCP element

**Hero Images**

Large banner or header images above the fold

**H1 Headlines**

Large text headings on text-heavy pages

**Background Images**

CSS background-image on large containers

**Video Posters**

Poster images for \<video> elements

### **What Affects LCP **

Common issues that slow down your LCP

[**Slow Server** Server response delays everything](https://unlighthouse.dev/learn-lighthouse/lcp/slow-server-response) [**Render Blocking** CSS and sync JS block painting](https://unlighthouse.dev/learn-lighthouse/lcp/render-blocking-resources) [**No Priority** LCP image loads too late](https://unlighthouse.dev/learn-lighthouse/lcp/prioritize-lcp-image) [**Lazy Loaded** Critical image has loading="lazy"](https://unlighthouse.dev/learn-lighthouse/lcp/lcp-lazy-loaded) [**CSR Delay** JS must execute before LCP renders](https://unlighthouse.dev/learn-lighthouse/lcp/client-side-rendering) [**Custom Fonts** Web fonts delay text LCP](https://unlighthouse.dev/learn-lighthouse/cls/web-fonts-causing-foit)

### **Quick LCP Fixes **

High-impact optimizations you can implement today

#### **For Image LCP **

- Add `fetchpriority="high"`
- Remove `loading="lazy"`
- Preload with `rel="preload"`
- Use WebP or AVIF formats

#### **For Text LCP **

- Preload critical fonts
- Use `font-display: optional`
- Inline critical CSS
- Remove render-blocking scripts

## **Frequently Asked Questions **

<details>

<summary>**01**

### **What is Largest Contentful Paint (LCP)?**

</summary>

Largest Contentful Paint (LCP) is a Core Web Vital that measures loading performance. It marks the time when the largest content element (usually an image or text block) becomes visible in the viewport. A good LCP score is 2.5 seconds or less.

</details>

<details>

<summary>**02**

### **How do I find my LCP element?**

</summary>

This tool identifies your LCP element automatically by running a Lighthouse audit. It shows you exactly which element is your LCP—typically a hero image, video poster, or large text heading—along with timing breakdowns and optimization recommendations.

</details>

<details>

<summary>**03**

### **Why is my LCP image lazy-loaded?**

</summary>

Lazy-loading your LCP image is a common mistake that significantly hurts performance. Images above the fold (visible without scrolling) should load immediately with fetchpriority="high" and never use loading="lazy". This tool detects if your LCP is incorrectly lazy-loaded.

</details>

<details>

<summary>**04**

### **How do I improve my LCP score?**

</summary>

To improve LCP: preload your LCP image with &lt;link rel="preload"&gt;, add fetchpriority="high" to the LCP element, use modern image formats (WebP/AVIF), optimize server response time (TTFB), remove render-blocking resources, and ensure the LCP element is in the initial HTML (not injected by JavaScript).

</details>

<details>

<summary>**05**

### **What are the LCP sub-parts or phases?**

</summary>

LCP consists of four phases: Time to First Byte (TTFB), Resource Load Delay (time from TTFB until the browser starts loading the LCP resource), Resource Load Time (time to download the LCP resource), and Element Render Delay (time from download complete until the element is painted). Optimizing each phase improves overall LCP.

</details>

### **Check LCP Across Your Entire Site **

Your homepage might be fast, but what about product pages, blog posts, and landing pages?

[**Get Started **](https://unlighthouse.dev/guide/getting-started/installation) [**LCP Deep Dive **](https://unlighthouse.dev/learn-lighthouse/lcp)

---

- **Page:** INP Analyzer - Test Interaction to Next Paint · Unlighthouse
- **Source:** https://unlighthouse.dev/tools/inp-analyzer
- **Description:** Free INP testing tool. Analyze your Interaction to Next Paint score, find long tasks blocking the main thread, and improve responsiveness.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **INP **Analyzer

Find what's blocking your main thread and slowing down interactions.

**INP Analysis**

Enter a URL to analyze INP

## **What is Interaction to Next Paint? **

INP measures how quickly your page responds to user interactions like clicks, taps, and keyboard input. It captures the **worst interaction latency** during a page visit, reporting when the browser finally paints a response. Google replaced FID with INP as a [Core Web Vital](https://web.dev/vitals/) in March 2024.

Since INP requires real user interactions, lab tools like Lighthouse use [**Total Blocking Time (TBT) **](https://unlighthouse.dev/glossary/tbt) as a proxy. TBT measures how long the main thread was blocked by long tasks during page load—a strong predictor of poor INP.

### **INP Timeline **

Click

Processing

**Paint **

Good INP**≤200ms**

## **Common Causes of Poor INP **

### **Long Tasks **

JavaScript executing for >50ms blocks the main thread. Break up work with `requestIdleCallback` or `scheduler.yield()`.

### **Third-Party Scripts **

Analytics, chat widgets, and ads often block the main thread. Load them async or use Partytown to run in a web worker.

### **Hydration **

Framework hydration can block interactions. Use progressive hydration, islands architecture, or server components.

### **Large DOM **

Too many DOM nodes slow down style calculations and layout. Keep nodes under 1,500 and virtualize long lists.

### **Layout Thrashing **

Reading and writing layout properties in a loop forces synchronous reflows. Batch DOM reads and writes.

### **Bundle Size **

Large JavaScript bundles take longer to parse and execute. Use code splitting, tree shaking, and lazy loading.

## **Frequently Asked Questions **

<details>

<summary>**01**

### **What is Interaction to Next Paint (INP)?**

</summary>

Interaction to Next Paint (INP) is a Core Web Vital that measures responsiveness. It tracks the delay between user interactions (clicks, taps, key presses) and the visual feedback. A good INP score is 200 milliseconds or less, indicating a responsive experience.

</details>

<details>

<summary>**02**

### **How is INP different from First Input Delay (FID)?**

</summary>

INP replaced FID as a Core Web Vital in March 2024. While FID only measured the first interaction, INP measures ALL interactions throughout the page lifecycle and reports the worst one. This makes INP a more comprehensive measure of real-world interactivity.

</details>

<details>

<summary>**03**

### **What causes poor INP scores?**

</summary>

Poor INP is typically caused by: long JavaScript tasks blocking the main thread, heavy third-party scripts (analytics, ads, widgets), unoptimized event handlers, layout thrashing from DOM manipulation, and large JavaScript bundles that take time to parse and execute.

</details>

<details>

<summary>**04**

### **How do I improve my INP score?**

</summary>

To improve INP: break long tasks into smaller chunks using yield patterns, defer non-critical JavaScript, use code splitting to reduce bundle size, optimize event handlers to avoid forced layouts, move heavy computation to web workers, and audit third-party scripts for performance impact.

</details>

<details>

<summary>**05**

### **Why does lab data show TBT instead of INP?**

</summary>

Total Blocking Time (TBT) is used as a lab proxy for INP because true INP requires real user interactions. TBT measures time spent on long tasks (&gt;50ms) during page load, which correlates with interactivity. Field data from real users provides actual INP measurements.

</details>

### **Related Tools **

[**LCP Finder **](https://unlighthouse.dev/tools/lcp-finder) [** Score Calculator **](https://unlighthouse.dev/tools/lighthouse-score-calculator) [** INP Optimization Guide **](https://unlighthouse.dev/learn-lighthouse/inp) [** INP Glossary **](https://unlighthouse.dev/glossary/inp)

---

- **Page:** HAR File Viewer - Analyze HTTP Archive Files Online Free · Unlighthouse
- **Source:** https://unlighthouse.dev/tools/har-viewer
- **Description:** Free HAR file viewer and network analyzer. Upload HAR files to visualize waterfall charts, request timing, resource breakdown, and protocol analysis. Entirely client-side, no data uploaded.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **HAR File **Viewer

Upload a HAR file to analyze network requests, waterfall timing, and resource breakdown. Entirely client-side.

**HAR File Analyzer**

**Drop your HAR file here **

or click to browse files

**How to export a HAR file: **

1. Open Chrome DevTools (F12) → Network tab
2. Reload the page to capture all requests
3. Right-click the request list → "Save all as HAR with content"

## **How to Read a HAR File **

A HAR file logs every HTTP request your browser makes when loading a page. Each entry captures the **URL, method, status code, headers, timing data, and response size**. The waterfall chart visualizes the sequence and overlap of these requests.

Focus on requests with long **wait times (TTFB)** — these indicate slow server responses. Large **receive phases** point to oversized assets that need compression or optimization.

### **Timing Phases Explained **

**blocked**

Time spent queued before the request could be sent

**DNS Lookup**

Time to resolve the domain name to an IP address

**connect**

Time to establish a TCP connection

**SSL/TLS**

Time for the TLS/SSL handshake

**send**

Time to send the HTTP request to the server

**Waiting (TTFB)**

Time waiting for the server to respond (Time to First Byte)

**receive**

Time to download the response body

## **What to Look For in HAR Files **

### **Slow TTFB **

Wait times over 200ms for the main document suggest server-side bottlenecks — slow databases, no caching, or distant servers.

### **Too Many Requests **

Pages with 80+ requests are above median. Combine scripts, use sprites, and lazy-load below-fold assets.

### **Missing Compression **

If transfer size equals uncompressed size for text files, Brotli or Gzip compression isn't enabled on your server.

### **HTTP/1.1 Bottlenecks **

Staircase waterfall patterns indicate HTTP/1.1 connection limits. Upgrade to HTTP/2 or HTTP/3 for multiplexing.

### **Third-Party Bloat **

Check the domain breakdown — third-party scripts (analytics, ads) often account for 30-50% of total page weight.

### **Low Cache Hit Rate **

A rate below 30% means most assets aren't cached. Set proper Cache-Control headers for static resources.

## **Frequently Asked Questions **

<details>

<summary>**01**

### **What is a HAR file?**

</summary>

A HAR (HTTP Archive) file is a JSON-formatted log of all HTTP transactions between a browser and a website. It records every request and response, including URLs, headers, timing data, status codes, and response sizes. HAR files are used to diagnose network performance issues, debug API calls, and analyze page load behavior.

</details>

<details>

<summary>**02**

### **How do I export a HAR file from Chrome?**

</summary>

Open Chrome DevTools (F12), go to the Network tab, load your page, then right-click the request list and select "Save all as HAR with content." Alternatively, click the download arrow icon in the Network toolbar. Make sure to check "Preserve log" if you need to capture redirects.

</details>

<details>

<summary>**03**

### **How do I export a HAR file from Firefox?**

</summary>

Open Firefox DevTools (F12), go to the Network tab, load your page, then click the gear icon and select "Save All As HAR." Firefox HAR exports include the same timing and header data as Chrome exports.

</details>

<details>

<summary>**04**

### **Is my data safe when using this HAR viewer?**

</summary>

Yes. This viewer runs entirely in your browser — your HAR file is never uploaded to any server. However, OWASP warns that HAR files pose a major security risk as they capture full request payloads, including plaintext passwords in postData and active Cookie session tokens. Never share raw HAR files publicly without first sanitizing sensitive headers.

</details>

<details>

<summary>**05**

### **How do I read a waterfall chart?**

</summary>

Each horizontal bar represents one HTTP request. The bar is divided into colored phases. A "Staircase" pattern indicates sequential loading, while a "Wall" pattern suggests HTTP/2 or HTTP/3 (QUIC) multiplexing. Long "waiting" (TTFB) bars point to backend bottlenecks, and long "receiving" bars indicate large unoptimized assets. Note that with HTTP/3, connect and SSL phases often collapse into a single 1-RTT event.

</details>

<details>

<summary>**06**

### **Why is my HAR file so large?**

</summary>

HAR files include full response bodies by default, with binary content (images, fonts) base64-encoded. A typical page load can produce a 5-50MB HAR file. To reduce size, some tools offer options to export without response bodies.

</details>

Explore more performance tools

[**Lighthouse Viewer **](https://unlighthouse.dev/tools/lighthouse-report-viewer) [** PageSpeed Insights **](https://unlighthouse.dev/tools/pagespeed-insights-performance) [** CWV Checker **](https://unlighthouse.dev/tools/cwv-checker)

---

- **Page:** CLS Debugger - Free Layout Shift Testing Tool · Unlighthouse
- **Source:** https://unlighthouse.dev/tools/cls-debugger
- **Description:** Free CLS testing tool. Enter a URL to find which elements cause Cumulative Layout Shift and get actionable fixes. No signup required.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **CLS **Debugger

Find which elements cause layout shifts and fix the jank.

**CLS Analysis**

Enter a URL to debug layout shifts

## **What is Cumulative Layout Shift? **

CLS measures **visual stability**—how much elements move unexpectedly while the page loads. A high CLS score means users experience jarring shifts, like clicking a button that suddenly moves because an ad loaded above it.

Google considers CLS one of the three [Core Web Vitals](https://web.dev/vitals/) that directly affect search rankings. A score of **0.1 or below** is considered good.

### **Layout Shift Example **

Elements moving after render causes poor **user experience** and missed clicks.

## **Common CLS Causes & Fixes **

Most layout shifts come from these common issues

**Unsized Images**

Images without width/height push content when they load.

`<img width="800" height="600" ...>`

**Font Loading**

Custom fonts can cause text to reflow when they load.

`font-display: optional;`

**Dynamic Content**

Ads, embeds, and async content push existing content.

`Reserve space with min-height`

**CSS Animations**

Avoid animating properties that trigger layout.

`Use transform, not top/left`

**Injected Elements**

Banners, cookie notices, and alerts inserted at the top.

`Use position: fixed or sticky`

**Missing Placeholders**

Async content should have skeleton loaders.

`Show skeleton while loading`

## **Frequently Asked Questions **

<details>

<summary>**01**

### **What is Cumulative Layout Shift (CLS)?**

</summary>

Cumulative Layout Shift (CLS) is a Core Web Vital that measures visual stability. It quantifies how much page content unexpectedly shifts during loading. A good CLS score is 0.1 or less, meaning minimal unexpected movement of visible elements.

</details>

<details>

<summary>**02**

### **How do I find layout shift culprits on my page?**

</summary>

This CLS debugger identifies exactly which elements cause layout shifts by analyzing your page with Lighthouse. It shows you the specific DOM elements, their shift scores, and visual overlays highlighting problem areas. Common culprits include images without dimensions, ads, embeds, and dynamically injected content.

</details>

<details>

<summary>**03**

### **What causes high CLS scores?**

</summary>

High CLS is typically caused by: images or videos without explicit width/height attributes, ads or embeds that resize after loading, web fonts causing FOUT/FOIT, dynamically injected content above existing content, and animations that trigger layout changes instead of using transform.

</details>

<details>

<summary>**04**

### **How do I fix Cumulative Layout Shift issues?**

</summary>

To fix CLS: always set width and height on images and video elements, reserve space for ads and embeds with CSS aspect-ratio, use font-display: optional or swap with fallback fonts, avoid inserting content above existing content, and use CSS transforms for animations instead of properties that trigger layout.

</details>

<details>

<summary>**05**

### **What is the difference between CLS in lab data vs field data?**

</summary>

Lab CLS measures layout shifts during initial page load in a controlled environment. Field CLS (from real users) captures shifts throughout the entire page session, including those from user interactions. Field data often shows higher CLS because it includes shifts from lazy-loaded content and user-triggered changes.

</details>

Explore more Core Web Vitals tools

[**LCP Finder **](https://unlighthouse.dev/tools/lcp-finder) [** Full Performance Report **](https://unlighthouse.dev/tools/pagespeed-insights-performance) [** CLS Optimization Guide **](https://unlighthouse.dev/learn-lighthouse/cls)

---

- **Page:** JSON Size Calculator - Measure &amp; Analyze JSON Size Online Free · Unlighthouse
- **Source:** https://unlighthouse.dev/tools/json-size
- **Description:** Free JSON size calculator. Measure raw, minified, gzip, and brotli sizes. Analyze key contributions, depth, and duplicate key overhead. Paste JSON, get instant size breakdown. 100% client-side.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **JSON Size **Analyzer

Paste JSON to analyze size, minification savings, compression estimates, and key contributions. Entirely client-side.

**JSON Size Analysis**

## **Why JSON Size Matters **

JSON is the most common data format for APIs and configuration files. Large JSON payloads directly impact **page load time, Time to First Byte (TTFB), and Largest Contentful Paint (LCP)**. Every kilobyte matters on mobile networks.

Minification removes whitespace and formatting, typically saving **10-30%** of raw size. Server compression (gzip/brotli) provides another **70-85%** reduction on top of that.

### **Compression Comparison **

**Raw **

100%

**Minified **

\~75%

**Gzip **

\~22%

**Brotli **

\~20%

## **Tips to Reduce JSON Size **

### **Shorten Key Names **

In arrays of objects, key names repeat for every item. Shorter keys like "n" instead of "name" save bytes multiplied by array length.

### **Remove Nulls **

Omit null and empty string fields from API responses. The absence of a key is more compact than "key":null.

### **Enable Compression **

Always serve JSON with Content-Encoding: br (Brotli) or gzip. This is the single biggest size reduction you can apply.

### **Paginate Large Arrays **

Don't return 1000 items when the client only shows 20. Use cursor-based pagination to keep payloads small.

### **Use Field Selection **

Implement sparse fieldsets or GraphQL to let clients request only the fields they need, reducing payload size.

### **Consider Alternatives **

For very large datasets, consider MessagePack, Protocol Buffers, or streaming JSON (NDJSON) instead of monolithic JSON.

## **Frequently Asked Questions **

<details>

<summary>**01**

### **How is JSON size calculated?**

</summary>

Raw size is measured in UTF-8 bytes using the Blob API. Minified size is computed by parsing the JSON and re-serializing with JSON.stringify (no whitespace). The difference between raw and minified is your savings from removing formatting.

</details>

<details>

<summary>**02**

### **How accurate are the gzip and brotli estimates?**

</summary>

The estimates use typical compression ratios: \~4.5x for gzip and \~5.1x for brotli on JSON data (Brotli offers best density for APIs). Alternatively, Zstandard (Zstd) achieves \~4.5x but is significantly faster. Real compression depends on data entropy and repetition. These estimates are within 10-20% of actual compression.

</details>

<details>

<summary>**03**

### **Why should I optimize JSON size?**

</summary>

Large JSON payloads hurt performance in two ways: network transfer time and mobile CPU parsing. On mobile devices, native JSON.parse is highly optimized (V8 parses &gt;10KB payloads 1.5x faster than JS literals), but main-thread execution time for massive payloads can block the UI. Additionally, REST API over-fetching often results in 30-50% of returned data being discarded by the client. Optimizing reduces mobile latency and CPU blocking.

</details>

<details>

<summary>**04**

### **What does "duplicate key bytes" mean?**

</summary>

When you have an array of objects with the same keys (like API responses), the key names are repeated for every object. Duplicate key bytes shows how much space is wasted on repeated key strings. This overhead shrinks dramatically with compression.

</details>

<details>

<summary>**05**

### **Is my JSON data uploaded anywhere?**

</summary>

No. This tool runs entirely in your browser. Your JSON is never sent to any server. All parsing, analysis, and minification happen client-side using JavaScript.

</details>

<details>

<summary>**06**

### **Why does my JSON fail to parse?**

</summary>

Common issues include trailing commas (not valid JSON), single quotes instead of double quotes, unquoted keys, comments, or JavaScript expressions like undefined. Use a JSON validator to find the exact error location.

</details>

<details>

<summary>**07**

### **How can I reduce my JSON payload size?**

</summary>

Minify by removing whitespace. Use shorter key names for large arrays of objects. Remove null/empty fields. Enable gzip or brotli compression on your server. Consider binary formats like MessagePack or Protocol Buffers for very large payloads.

</details>

Explore more performance tools

[**HAR Viewer **](https://unlighthouse.dev/tools/har-viewer) [** PageSpeed Insights **](https://unlighthouse.dev/tools/pagespeed-insights-performance) [** Lighthouse Viewer **](https://unlighthouse.dev/tools/lighthouse-report-viewer)

---

- **Page:** Page Size Checker - Test Page Weight &amp; Resource Breakdown Free · Unlighthouse
- **Source:** https://unlighthouse.dev/tools/page-size
- **Description:** Free page size checker. Analyze total page weight, resource breakdown by type, third-party script weight, unused code, and compression efficiency. Compare against HTTP Archive percentiles.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Page Size **Checker

Analyze page weight, resource breakdown, third-party scripts, and unused code with real Lighthouse data.

**Page Size Analysis**

Enter a URL to check page size

## **Why Page Weight Matters **

Page weight directly impacts **Largest Contentful Paint (LCP)** and **Time to Interactive**. The median mobile page now weighs 2.5 MB, growing \~10% per year. But median doesn't mean good — sites in the **bottom 25th percentile** (under 1 MB) consistently score higher on Core Web Vitals.

JavaScript is the most expensive resource type: every 50 KB of JS costs \~100ms of parse/compile time on mid-range phones. Images are cheaper byte-for-byte since they don't block the main thread, but unoptimized images are the largest contributor to total page weight.

### **Page Weight Benchmarks (Mobile) **

**P10**

489.0 KB

**P25**

1.0 MB

**P50**

2.5 MB

**P75**

5.0 MB

**P90**

8.1 MB

Source: HTTP Archive, 2025-2026 mobile data

## **How to Reduce Page Weight **

### **Optimize Images **

Use AVIF (50% savings over JPEG) or WebP (30% savings). Serve responsive sizes with srcset. Lazy-load below-fold images.

### **Trim JavaScript **

Tree-shake unused code. Code-split routes. Audit npm dependencies — many bundles ship 30-50% unused code.

### **Enable Brotli **

Brotli compresses 15-25% better than gzip for text resources. Most CDNs and reverse proxies support it out of the box.

### **Audit Third Parties **

Third-party scripts average 30-50% of total page weight. Remove unused trackers, defer non-essential scripts, and use lightweight alternatives.

### **Variable Fonts **

Replace multiple font files with a single variable font. Subset to only the characters you need. Use WOFF2 format.

### **Set Budgets **

Set a performance budget (e.g., 200 KB JS, 500 KB images). Use Lighthouse CI to enforce budgets in your CI pipeline.

## **Frequently Asked Questions **

<details>

<summary>**01**

### **What is a good page size?**

</summary>

Under 1 MB total transfer size is excellent. 1-2 MB is acceptable for content-rich pages. 2-3 MB is heavy and will impact mobile users. Over 3 MB is considered poor — the median web page is around 2.5 MB on mobile, but that doesn't mean it's good. Aim to be in the bottom 25th percentile.

</details>

<details>

<summary>**02**

### **How does page size affect performance?**

</summary>

Larger pages take longer to download (hurting LCP) and require more CPU to parse JavaScript (hurting TBT and INP). 50% of mobile sites take over 14s to become interactive, with a median mobile Total Blocking Time (TBT) of 1,916ms. Every 100 KB of JavaScript costs roughly 100ms of parse time on mid-range phones. Images are less CPU-expensive than JavaScript byte-for-byte.

</details>

<details>

<summary>**03**

### **What is the average web page size in 2026?**

</summary>

According to HTTP Archive data, the median mobile page weighs about 2,559 KB (\~2.5 MB), growing roughly 10% year-over-year. Desktop median is about 2,862 KB. At the 90th percentile, pages exceed 8 MB. JavaScript and images are the two largest contributors.

</details>

<details>

<summary>**04**

### **Does page size affect SEO?**

</summary>

Indirectly, yes. Page size impacts Core Web Vitals (LCP, INP, CLS). While only 48% of mobile sites pass all CWVs and speed has a weak direct correlation to organic rank, a 1-second delay can lead to a 7% drop in conversions. Very large pages also affect crawl budget and have a larger carbon footprint — a median 2.5MB page correlates linearly with higher energy use in data transfer.

</details>

<details>

<summary>**05**

### **What is the difference between transfer size and uncompressed size?**

</summary>

Transfer size is the actual bytes sent over the network after gzip or brotli compression. Uncompressed size is the raw content before compression. Text-based resources (HTML, CSS, JS, JSON) typically compress 3-5x. Images are already compressed so transfer and uncompressed sizes are similar.

</details>

<details>

<summary>**06**

### **How do I reduce my page size?**

</summary>

Compress images with AVIF/WebP (30-50% savings over JPEG). Tree-shake and code-split JavaScript. Remove unused CSS. Enable brotli compression on your server. Lazy-load images below the fold. Audit third-party scripts — they often account for 30-50% of total page weight.

</details>

Explore more performance tools

[**Full PSI Report **](https://unlighthouse.dev/tools/pagespeed-insights-performance) [** LCP Finder **](https://unlighthouse.dev/tools/lcp-finder) [** HAR Viewer **](https://unlighthouse.dev/tools/har-viewer) [** JSON Size **](https://unlighthouse.dev/tools/json-size)

---

- **Page:** PageSpeed Insights - Full Performance Report · Unlighthouse
- **Source:** https://unlighthouse.dev/tools/pagespeed-insights-performance
- **Description:** Comprehensive PageSpeed Insights performance report with Core Web Vitals, resource analysis, third-party breakdown, and actionable recommendations.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **PageSpeed Insights **Performance

Comprehensive performance analysis with Core Web Vitals, resource breakdown, and optimization opportunities.

**Performance Analysis**

Enter a URL to generate a full performance report

## **Frequently Asked Questions **

<details>

<summary>**01**

### **What is PageSpeed Insights?**

</summary>

PageSpeed Insights (PSI) is a Google tool that analyzes web page performance using Lighthouse. It provides a performance score (0-100), Core Web Vitals metrics, and actionable optimization recommendations for both mobile and desktop.

</details>

<details>

<summary>**02**

### **What is the difference between PageSpeed Insights and Lighthouse?**

</summary>

PageSpeed Insights runs Lighthouse audits on Google's servers and adds real user data from CrUX (Chrome User Experience Report). Lighthouse in Chrome DevTools runs locally. PSI also provides field data showing how real users experience your page.

</details>

<details>

<summary>**03**

### **Why is my mobile score lower than desktop?**

</summary>

PSI applies CPU throttling (4x slowdown) and network throttling for mobile tests, simulating a mid-range phone on 4G. Desktop tests use minimal throttling. This means JavaScript-heavy pages score significantly lower on mobile.

</details>

<details>

<summary>**04**

### **How do I improve my PageSpeed Insights score?**

</summary>

Focus on the highest-impact metrics: reduce Total Blocking Time (30% weight) by code-splitting JavaScript, optimize Largest Contentful Paint (25%) by preloading key resources, and minimize Cumulative Layout Shift (25%) by setting image dimensions.

</details>

---

- **Page:** Unlighthouse: Site-Wide Google Lighthouse Audits · Unlighthouse
- **Source:** https://unlighthouse.dev/
- **Description:** Scan every page of your site with Google Lighthouse. Unlighthouse discovers URLs, runs audits in parallel, and combines results in one report.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Lighthouse for your **entire site

Unlighthouse is a free, open-source CLI that runs Google Lighthouse on every page of your site in parallel. Auto-discovers URLs, crawls in parallel, and delivers one unified performance report.

$npxunlighthouse--siteexample.com

[**Get Started **](https://unlighthouse.dev/guide/getting-started/installation) [** GitHub **](https://github.com/harlan-zw/unlighthouse)

Node 22+ · MIT licensed · Zero config

localhost:5678

## **Why Unlighthouse **

### **Parallel Scans **

Threaded workers with opportunistic throttling for fast audits.

### **Auto Crawling **

Discovers URLs via robots.txt, sitemap.xml, and internal links.

### **Smart Sampling **

Auto-samples dynamic routes to reduce scan time.

### **Modern UI **

Search, sort, and re-scan pages in the Vite-powered client.

### **SEO Insights **

Titles, meta descriptions, share images, link analysis.

### **A11y Summary **

Accessibility audit with contrast issue visualization.

## **Improve every page **

Go from a site-wide audit to the tools and guidance needed to understand and fix each result.

- [**Performance Tools**Test Core Web Vitals, inspect reports, and diagnose page weight.](https://unlighthouse.dev/tools)
- [**Learn Lighthouse**Understand Lighthouse audits, metrics, and practical fixes.](https://unlighthouse.dev/learn-lighthouse)
- [**Integrations**Run Unlighthouse from the CLI, CI, Nuxt, Vite, or Webpack.](https://unlighthouse.dev/integrations/cli)
- [**Web Performance Glossary**Look up Core Web Vitals and Lighthouse terminology.](https://unlighthouse.dev/glossary)

**6.2K**

downloads per day

185K

monthly downloads

4.8K

GitHub stars

## **Community Funded **

Unlighthouse is free and open-source thanks to generous community sponsors.

[**Become a sponsor **](https://github.com/sponsors/harlan-zw)

### **Top Sponsors **

[![Daniel Roe](https://avatars.githubusercontent.com/u/28706372?u=c4a5aa5232c09c3248533366d5c93a138d7e8987&v=4)**Daniel Roe**](https://roe.dev) [![Jan-Henrik Damaschke](https://avatars.githubusercontent.com/u/15030951?u=724eb8ee4cae7792ddf13e25c31589dd6c5cb1d1&v=4)**Jan-Henrik Damaschke**](https://www.itinsights.org)

### **Gold Sponsors **

[![Massive Monster](https://avatars.githubusercontent.com/u/11852534?v=4)](https://massivemonster.co) [![Localazy](https://avatars.githubusercontent.com/u/59409404?v=4)](https://localazy.com)

### **Backers **

[![Marko](https://avatars.githubusercontent.com/u/2497323?u=189c706b73e0495b56688589447d3e46b8045f73&v=4)](https://github.com/aussieboi) [![Christian Ducrot](https://avatars.githubusercontent.com/u/3525119?u=6b662d7c909bb2c725194f0f9290d2b8e78b7188&v=4)](https://www.ducrot.de) [![Maik](https://avatars.githubusercontent.com/u/16877165?u=51e3a642e812d53c7d51037f4cf421e9faf9a3f9&v=4)](https://github.com/just-maik) [![Leopold Kristjansson](https://avatars.githubusercontent.com/u/2579324?v=4)](https://github.com/leopoldkristjansson) [![Govind](https://avatars.githubusercontent.com/u/76161333?u=6bdc2ffc727c22c77ebbf31579f773a770aa385e&v=4)](https://admakeai.com) [![Email Testing for Developers - SMTP Labs, Inc.](https://avatars.githubusercontent.com/u/89388475?v=4)](https://github.com/smtplabs) [![Laioutr GmbH](https://avatars.githubusercontent.com/u/159871102?v=4)](https://www.laioutr.com) [![reshepe](https://avatars.githubusercontent.com/u/175365848?v=4)](https://reshepe.dev) [![Elmo](https://avatars.githubusercontent.com/u/229394758?v=4)](https://www.elmohq.com) [![AdKit](https://avatars.githubusercontent.com/u/242531394?v=4)](https://adkit.so) [![Obelinf](https://avatars.githubusercontent.com/u/297651075?v=4)](https://obelinf.com)

---

- **Page:** Core web vitals guide · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/core-web-vitals
- **Description:** Master Core Web Vitals - Google's page experience metrics. Learn LCP, CLS, INP thresholds, how to measure them, and fixes that improve rankings and conversions.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Core web vitals guide**

Master Core Web Vitals - Google's page experience metrics. Learn LCP, CLS, INP thresholds, how to measure them, and fixes that improve rankings and conversions.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)14 min read Published **Jan 12, 2025** Updated **Aug 9, 2026**

Core Web Vitals are Google's metrics for loading performance, visual stability, and interaction responsiveness. Google uses them within its broader [**~~page experience systems~~**](https://developers.google.com/search/docs/appearance/page-experience), while relevance and content quality remain the stronger search signals.

In the [**~~2025 Web Almanac~~**](https://almanac.httparchive.org/en/2025/performance), 48% of mobile sites and 56% of desktop sites passed all three metrics.

## What are core web vitals

Core Web Vitals are three specific metrics that measure loading performance, visual stability, and interactivity:

| **Metric** | **Full Name** | **Measures** | **Good** | **Poor** |
| --- | --- | --- | --- | --- |
| **LCP** | Largest Contentful Paint | Loading speed | ≤2.5s | >4.0s |
| **CLS** | Cumulative Layout Shift | Visual stability | ≤0.1 | >0.25 |
| **INP** | Interaction to Next Paint | Responsiveness | ≤200ms | >500ms |

Google [**~~measures these thresholds at the 75th percentile~~**](https://web.dev/articles/defining-core-web-vitals-thresholds) of page loads. 75% of visitors must experience "good" scores for your site to pass.

[**~~INP replaced FID as a Core Web Vital on March 12, 2024~~**](https://web.dev/blog/inp-cwv-march-12). If you're still optimizing for First Input Delay, you're targeting an outdated metric.

---

## Largest contentful paint (LCP)

LCP measures how long it takes for the largest visible content element to render. It remains the hardest Core Web Vital to pass: [**~~62% of mobile pages achieved good LCP in 2025~~**](https://almanac.httparchive.org/en/2025/performance).

### What is a good LCP score

| **LCP Time** | **Rating** | **What It Means** |
| --- | --- | --- |
| ≤2.5s | Good | Users perceive the page as fast |
| 2.5-4.0s | Needs Improvement | Noticeable delay causes users to bounce |
| >4.0s | Poor | Significant user frustration, high abandonment |

### What elements can be LCP

The LCP element is the largest image or text block visible in the viewport:

- **Images** (including CSS background images): [**~~76% of mobile pages use an image as their LCP element~~**](https://almanac.httparchive.org/en/2025/performance)
- **Video poster images** (the thumbnail before playback)
- **Block-level text elements** (headings, paragraphs)

### Common LCP issues

| **Issue** | **Impact** | **Prevalence** |
| --- | --- | --- |
| [**~~Slow server response (TTFB)~~**](https://unlighthouse.dev/learn-lighthouse/lcp/slow-server-response) | High | Delays every resource discovered from the HTML |
| [**~~Render-blocking resources~~**](https://unlighthouse.dev/learn-lighthouse/lcp/render-blocking-resources) | High | CSS and JS that delay first paint |
| [**~~Large unoptimized images~~**](https://unlighthouse.dev/learn-lighthouse/lcp/large-images) | High | Uncompressed or oversized images |
| [**~~Client-side rendering delays~~**](https://unlighthouse.dev/learn-lighthouse/lcp/client-side-rendering) | Medium | JavaScript-heavy frameworks |
| [**~~LCP image not prioritized~~**](https://unlighthouse.dev/learn-lighthouse/lcp/prioritize-lcp-image) | Medium | Missing fetchpriority or preload |

### LCP business impact

- [**~~Vodafone improved LCP by 31% and saw 8% more sales~~**](https://web.dev/case-studies/vodafone)
- [**~~NDTV halved their LCP and achieved 50% lower bounce rates~~**](https://web.dev/case-studies/ndtv)
- [**~~Tokopedia reduced LCP by 55% and increased organic traffic by 23%~~**](https://web.dev/case-studies/tokopedia)

→ [**~~Complete LCP guide~~**](https://unlighthouse.dev/learn-lighthouse/lcp) | [**~~All LCP fixes~~**](https://unlighthouse.dev/learn-lighthouse/lcp#common-lcp-issues)

---

## Cumulative layout shift (CLS)

CLS measures unexpected layout shifts during the page lifecycle. It is the most widely passed Core Web Vital: [**~~81% of mobile pages achieved good CLS in 2025~~**](https://almanac.httparchive.org/en/2025/performance).

### What is a good CLS score

| **CLS Score** | **Rating** | **What It Means** |
| --- | --- | --- |
| ≤0.1 | Good | Stable layout, minimal shifts |
| 0.1-0.25 | Needs Improvement | Noticeable movement frustrates users |
| >0.25 | Poor | Significant layout instability |

Lighthouse calculates CLS as: **Impact Fraction × Distance Fraction**. A shift affecting 50% of the viewport that moves 25% of the viewport height = 0.5 × 0.25 = 0.125 CLS.

### What causes layout shifts

| **Cause** | **Impact** | **Prevalence** |
| --- | --- | --- |
| [**~~Images without dimensions~~**](https://unlighthouse.dev/learn-lighthouse/cls/unsized-images) | High | [**~~62% of mobile pages~~**](https://almanac.httparchive.org/en/2025/performance) have at least one unsized image |
| [**~~Ads and embeds~~**](https://unlighthouse.dev/learn-lighthouse/cls/ads-embeds-iframes) | High | Third-party content without reserved space |
| [**~~Dynamically injected content~~**](https://unlighthouse.dev/learn-lighthouse/cls/dynamic-content-injection) | Medium | Banners, notifications, modals |
| [**~~Web fonts causing FOIT/FOUT~~**](https://unlighthouse.dev/learn-lighthouse/cls/web-fonts-causing-foit) | Medium | Font swapping changes text size |
| [**~~CSS animations~~**](https://unlighthouse.dev/learn-lighthouse/cls/animations-transitions) | Low | Animations that trigger layout |

### CLS business impact

- [**~~Redbus reduced CLS from 1.65 to 0 and saw 80-100% higher mobile conversion~~**](https://web.dev/case-studies/vitals-business-impact)
- [**~~Yahoo! Japan fixed CLS and achieved 15% more page views per session~~**](https://web.dev/case-studies/vitals-business-impact)
- [**~~AliExpress improved CLS and reduced bounce rate by 15%~~**](https://web.dev/case-studies/vitals-business-impact)

→ [**~~Complete CLS guide~~**](https://unlighthouse.dev/learn-lighthouse/cls) | [**~~All CLS fixes~~**](https://unlighthouse.dev/learn-lighthouse/cls#common-cls-issues)

---

## Interaction to next paint (INP)

INP measures how quickly your page responds to user interactions. Unlike FID (which only measured the *first* interaction), INP tracks *all* interactions because [**~~90% of user time on a page is spent after initial load~~**](https://web.dev/articles/inp).

### What is a good INP score

| **INP Time** | **Rating** | **What It Means** |
| --- | --- | --- |
| ≤200ms | Good | Interactions feel instant |
| 200-500ms | Needs Improvement | Noticeable lag on interactions |
| >500ms | Poor | Sluggish, frustrating experience |

### How browsers calculate INP

INP measures the full interaction lifecycle:

1. **Input delay**: Time from user action to event handler start
2. **Processing time**: Time to execute event handlers
3. **Presentation delay**: Time to render the visual update

The reported INP is usually the longest interaction. For pages with many interactions, the algorithm ignores one worst interaction per 50 interactions to reduce the effect of rare outliers. Lighthouse cannot measure INP from a normal synthetic page load; use CrUX or real-user monitoring.

### Common INP issues

| **Issue** | **Impact** | **Lab Proxy** |
| --- | --- | --- |
| [**~~Long-running JavaScript~~**](https://unlighthouse.dev/learn-lighthouse/inp/long-running-javascript) | High | Total Blocking Time (TBT) |
| [**~~Heavy event handlers~~**](https://unlighthouse.dev/learn-lighthouse/inp/event-handler-delays) | High | Main thread work |
| [**~~Large DOM size~~**](https://unlighthouse.dev/learn-lighthouse/inp/dom-size) | Medium | DOM nodes >1,400 |
| [**~~Third-party scripts~~**](https://unlighthouse.dev/learn-lighthouse/inp/third-party-scripts) | Medium | Blocking main thread |
| [**~~Hydration delays~~**](https://unlighthouse.dev/learn-lighthouse/inp/hydration-issues) | Medium | Framework-specific |

### The INP gap

The [**~~2025 Web Almanac~~**](https://almanac.httparchive.org/en/2025/performance) found good INP on 97% of desktop pages and 77% of mobile pages. Mobile devices still face much more main-thread pressure.

### INP business impact

- [**~~Trendyol reduced INP by 50% and saw 1% increase in click-through rate~~**](https://web.dev/case-studies/vitals-business-impact)
- [**~~The Economic Times cut INP by 30% and achieved 50% lower bounce rate~~**](https://web.dev/case-studies/economic-times-inp)
- [**~~redBus improved INP by 75% alongside 7% increase in conversions~~**](https://web.dev/case-studies/redbus-inp)

→ [**~~Complete INP guide~~**](https://unlighthouse.dev/learn-lighthouse/inp) | [**~~All INP fixes~~**](https://unlighthouse.dev/learn-lighthouse/inp#common-inp-issues)

---

## Other web vitals

Beyond the three Core Web Vitals, several other metrics affect your Lighthouse Performance score and user experience.

### First contentful paint (FCP)

FCP measures when the first text or image is painted. It's the earliest signal that the page is loading.

| **FCP Time** | **Rating** |
| --- | --- |
| ≤1.8s | Good |
| 1.8-3.0s | Needs Improvement |
| >3.0s | Poor |

**Weight in Lighthouse:** 10% of Performance score

FCP issues share root causes with LCP - fix render-blocking resources and server response time to improve both.

### Speed index (SI)

Speed Index measures how quickly content is visually populated during page load. It captures the perceived loading experience.

| **Speed Index** | **Rating** |
| --- | --- |
| ≤3.4s | Good |
| 3.4-5.8s | Needs Improvement |
| >5.8s | Poor |

**Weight in Lighthouse:** 10% of Performance score

Speed Index improves when above-the-fold content loads progressively rather than all at once.

### Time to first byte (TTFB)

TTFB measures the time from the navigation request until the first response byte arrives. It is not a Core Web Vital, but it precedes every other loading milestone and forms the first sub-part of LCP.

| **Metric** | **Good** | **Needs Improvement** | **Poor** |
| --- | --- | --- | --- |
| **TTFB** | ≤800ms | 800ms-1800ms | >1800ms |

The [**~~2025 Web Almanac~~**](https://almanac.httparchive.org/en/2025/performance) found good TTFB on 44% of mobile pages. If TTFB consumes much of the 2.5-second LCP budget, fix caching, redirects, server work, or network distance before tuning the LCP image.

→ [**~~Fix slow server response~~**](https://unlighthouse.dev/learn-lighthouse/lcp/slow-server-response)

### Total blocking time (TBT)

TBT measures the total time the main thread was blocked by long tasks (>50ms) between FCP and Time to Interactive. It's a lab proxy for INP.

| **TBT** | **Rating** |
| --- | --- |
| ≤200ms | Good |
| 200-600ms | Needs Improvement |
| >600ms | Poor |

**Weight in Lighthouse:** 30% of Performance score - the highest-weighted metric

TBT [**~~correlates well with INP~~**](https://web.dev/articles/tbt), making it the best lab metric for predicting real-world interactivity.

→ [**~~Fix total blocking time~~**](https://unlighthouse.dev/learn-lighthouse/inp/total-blocking-time)

### Lighthouse performance score weights

The overall Lighthouse Performance score is a [**~~weighted average~~**](https://developer.chrome.com/docs/lighthouse/performance/performance-scoring) of five metrics:

| **Metric** | **Weight** | **Primary Improvement** |
| --- | --- | --- |
| **TBT** | 30% | Reduce JavaScript, break up long tasks |
| **LCP** | 25% | Optimize images, improve TTFB |
| **CLS** | 25% | Set dimensions, reserve space |
| **FCP** | 10% | Remove render-blocking resources |
| **SI** | 10% | Progressive loading, critical CSS |

LCP, CLS, and TBT account for **80%** of your score. Focus there first.

→ [**~~Try the score calculator~~**](https://unlighthouse.dev/tools/lighthouse-score-calculator)

---

## How to measure core web vitals

### Lab data (synthetic testing)

Lab tools test in controlled environments - useful for debugging but [**~~not used by Google for ranking~~**](https://developers.google.com/search/docs/appearance/core-web-vitals#ranking).

**Tools:**

- [**Core Web Vitals Checker**](https://unlighthouse.dev/tools/cwv-checker) - Test any page with lab and field data
- [**LCP Finder**](https://unlighthouse.dev/tools/lcp-finder) - Identify your LCP element and optimization opportunities
- [**CLS Debugger**](https://unlighthouse.dev/tools/cls-debugger) - Find and fix layout shift sources
- [**INP Analyzer**](https://unlighthouse.dev/tools/inp-analyzer) - Diagnose interaction responsiveness issues
- **Chrome DevTools**: Performance panel shows LCP, CLS, and long tasks
- **Lighthouse**: Full performance audit with actionable recommendations
- **WebPageTest**: Filmstrip view and waterfall analysis

For CI/CD integration, [**~~Lighthouse CI~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci) runs audits on every commit and fails builds when metrics regress.

```bash
npx unlighthouse --site https://your-site.com
```

### Field data (real user monitoring)

Field data from actual visitors is the source Google uses to assess Core Web Vitals:

- [**~~PageSpeed Insights~~**](https://pagespeed.web.dev) - Shows CrUX data for your URL and origin ([**~~how it differs from Lighthouse~~**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-vs-lighthouse))
- [**~~Search Console~~**](https://search.google.com/search-console/about) - Core Web Vitals report with URL-level groupings
- [**~~Chrome UX Report (CrUX)~~**](https://developer.chrome.com/docs/crux): 28-day rolling window of real user data

CrUX uses a rolling 28-day window, so a deployed fix appears gradually as older visits leave the window.

### Lab vs field differences

| **Aspect** | **Lab Data** | **Field Data** |
| --- | --- | --- |
| **Device** | Simulated throttling | Real user devices |
| **Network** | Fixed conditions | Variable connections |
| **Interactions** | Scripted or none | Real user behavior |
| **Use for** | Debugging, CI/CD | SEO ranking, real UX |

Your lab scores often differ significantly from field data. A page can score 95 in Lighthouse but fail Core Web Vitals in the field if real users have slower devices or networks.

---

## Why core web vitals matter for SEO

Google says good Core Web Vitals contribute to [**~~page experience~~**](https://developers.google.com/search/docs/appearance/page-experience), but a perfect report does not guarantee top rankings. Improve failing metrics for users first. Do not remove useful content or functionality merely to chase a score.

### User experience & conversions

The [**~~Google research on the business impact of Core Web Vitals~~**](https://web.dev/case-studies/vitals-business-impact) found a **0.1 second improvement** in site speed can:

- Increase retail conversions by **8.4%**
- Boost average order value by **9.2%**
- Increase travel conversions by **10.1%**

Google research shows bounce rate increases [**~~32% when load time goes from 1 to 3 seconds~~**](https://web.dev/learn/performance/why-speed-matters), and [**~~90% at 5 seconds~~**](https://web.dev/learn/performance/why-speed-matters).

---

## Current state of the web (2025)

According to the [**~~2025 HTTP Archive Web Almanac~~**](https://almanac.httparchive.org/en/2025/performance):

| **Metric** | **Mobile Pass Rate** | **Desktop Pass Rate** |
| --- | --- | --- |
| LCP | 62% | 74% |
| CLS | 81% | 72% |
| INP | 77% | 97% |
| **All Three** | **48%** | **56%** |

Mobile pass rates rose from 36% in 2023 to 48% in 2025. More than half of mobile sites still miss at least one Core Web Vital.

---

## Test your entire site

Most tools only test one page. Your homepage might score 100, but what about:

- Product pages with heavy images?
- Blog posts with embedded videos?
- Dynamic pages with JavaScript widgets?

The [**~~2025 Web Almanac~~**](https://almanac.httparchive.org/en/2025/performance) found different results for home pages and secondary pages. Test every important template, not only the home page.

```bash
npx unlighthouse --site https://your-site.com
```

---

## Next steps

1. **Audit**: [**~~Run Unlighthouse~~**](https://unlighthouse.dev/guide/getting-started/installation) to find issues across all pages
2. **Prioritize**: Fix the highest-impact issues first (TBT, LCP, CLS account for 80% of score)
3. **Automate**: Set up [**~~Lighthouse CI~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci) to catch regressions before they reach production
4. **Monitor**: Set up continuous monitoring to track real user metrics *Monitor*\*: Set up continuous monitoring to track real user metrics l user metrics

### **Related **

[**Core Web Vitals Checker**](https://unlighthouse.dev/tools/cwv-checker) [**Lighthouse CI Guide**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci) [**Bulk Lighthouse Testing**](https://unlighthouse.dev/learn-lighthouse/bulk-lighthouse-testing) [**Largest Contentful Paint (LCP) Guide**](https://unlighthouse.dev/learn-lighthouse/lcp) [**Cumulative Layout Shift (CLS) Guide**](https://unlighthouse.dev/learn-lighthouse/cls) [**Interaction to Next Paint (INP) Guide**](https://unlighthouse.dev/learn-lighthouse/inp) [**CWV Compare Tool**](https://unlighthouse.dev/tools/cwv-compare) [**Lighthouse Score Calculator**](https://unlighthouse.dev/tools/lighthouse-score-calculator) [**LCP Definition**](https://unlighthouse.dev/glossary/lcp) [**CLS Definition**](https://unlighthouse.dev/glossary/cls) [**INP Definition**](https://unlighthouse.dev/glossary/inp)

[**Bulk lighthouse testing** Run Lighthouse on your entire site with Unlighthouse. Limit pages with --maxRoutes, filter by URL pattern, and automate bulk audits.](https://unlighthouse.dev/learn-lighthouse/bulk-lighthouse-testing) 

**On this page **

- [What are core web vitals](#what-are-core-web-vitals)
- [Largest contentful paint (LCP)](#largest-contentful-paint-lcp)
- [Cumulative layout shift (CLS)](#cumulative-layout-shift-cls)
- [Interaction to next paint (INP)](#interaction-to-next-paint-inp)
- [Other web vitals](#other-web-vitals)
- [How to measure core web vitals](#how-to-measure-core-web-vitals)
- [Why core web vitals matter for SEO](#why-core-web-vitals-matter-for-seo)
- [Current state of the web (2025)](#current-state-of-the-web-2025)
- [Test your entire site](#test-your-entire-site)
- [Next steps](#next-steps)

---

- **Page:** Largest Contentful Paint (LCP): Good Scores, Fixes &amp; Guide · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/lcp
- **Description:** LCP measures when the main content loads. Good score: ≤2.5s mobile. Fix slow LCP with image optimization, TTFB improvements, and render-blocking resource removal.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Largest Contentful Paint (LCP): Good Scores, Fixes & Guide**

LCP measures when the main content loads. Good score: ≤2.5s mobile. Fix slow LCP with image optimization, TTFB improvements, and render-blocking resource removal.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)9 min read Published **Jan 18, 2025** Updated **Aug 9, 2026**

**Largest Contentful Paint (LCP) measures when the main content finishes loading.** A good LCP score is 2.5 seconds or less on mobile (same threshold for desktop). Scores above 4 seconds are classified as poor. LCP is one of [**~~Google's three Core Web Vitals~~**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) and directly affects search ranking.

**LCP**Largest Contentful Paint** CWV **

**25% weight **

Good ≤2.5sPoor >4.0s

LCP is the Core Web Vital developers struggle with most. The [**~~Chrome UX Report shows about 40% of sites miss the recommended LCP threshold~~**](https://web.dev/articles/top-cwv).

Why? LCP spans the full loading path: server response, resource discovery, transfer, and rendering. You need to find the slow sub-part before choosing a fix.

## What is LCP?

Largest Contentful Paint marks when the main content finishes loading. It answers the user's question: "Is this page showing me what I came for?"

The element considered "largest" changes as the page loads. The browser reports the final LCP candidate once the user interacts or the page finishes loading.

**LCP Thresholds:**

| **Device** | **Good** | **Needs Improvement** | **Poor** |
| --- | --- | --- | --- |
| Mobile | ≤2.5s | 2.5–4.0s | >4.0s |
| Desktop | ≤2.5s | 2.5–4.0s | >4.0s |

**Score Weight:** LCP accounts for **25%** of your Lighthouse Performance score.

**What elements can be LCP:**

- `**<img>**` elements: [**~~76% of mobile pages have an image as LCP~~**](https://almanac.httparchive.org/en/2025/performance)
- `**<video>**` elements (poster image or first frame)
- Elements with CSS `**background-image**` via `**url()**`
- Block-level elements containing text: [**~~about 24% of mobile LCP elements~~**](https://almanac.httparchive.org/en/2025/performance)

## Why LCP matters

### User experience

Users don't wait. When the main content takes too long, they assume the page is broken. The 2.5-second mobile threshold is based on [**~~research into user attention spans~~**](https://web.dev/articles/defining-core-web-vitals-thresholds) - after 3 seconds, users start losing patience and bouncing.

The visual impact is immediate: a blank or skeleton screen for 4+ seconds feels broken. A fully-rendered hero in under 2.5 seconds feels fast.

### SEO impact

LCP is one of [**~~Google's Core Web Vitals ranking factors~~**](https://developers.google.com/search/docs/appearance/core-web-vitals). Google uses field data (CrUX) from the 75th percentile - meaning 75% of your users need good LCP for it to count as "good" for ranking purposes.

[**~~Google describes Core Web Vitals as one part of page experience~~**](https://developers.google.com/search/docs/appearance/page-experience). Relevance still matters more, so treat LCP as a user experience requirement rather than a shortcut to higher rankings.

### Business impact

Real-world case studies demonstrate significant revenue correlation:

| **Company** | **LCP Improvement** | **Business Impact** |
| --- | --- | --- |
| [**~~Rakuten~~**](https://web.dev/case-studies/rakuten) | Achieved good LCP | 61% higher conversion rate |
| [**~~Vodafone~~**](https://web.dev/case-studies/vitals-business-impact) | 31% improvement | 8% more sales |
| [**~~Tokopedia~~**](https://web.dev/case-studies/vitals-business-impact) | 55% (3.78s → 1.72s) | 23% better session duration |
| [**~~NDTV~~**](https://web.dev/case-studies/vitals-business-impact) | 50% reduction | 50% better bounce rate |
| [**~~Agrofy~~**](https://web.dev/case-studies/vitals-business-impact) | 70% improvement | 76% less load abandonment |

The pattern is consistent: faster LCP correlates with better engagement and conversion.

## Start with field data

CrUX and Search Console report LCP at the 75th percentile, split by mobile and desktop. Start with the failing device group and URL pattern. Then reproduce one representative page in Lighthouse or Chrome DevTools.

Mobile-first indexing describes which page version Google crawls. It does not make desktop performance irrelevant. A slow desktop experience still affects desktop users, and CrUX reports it separately.

If URL-level CrUX data is unavailable, use origin data as context, not proof that the page passes. Low-traffic pages may have different templates and LCP elements from the home page.

## LCP sub-parts breakdown

Google recommends [**~~breaking LCP into four sub-parts~~**](https://web.dev/articles/optimize-lcp) to pinpoint exactly where time is being wasted:

| **Sub-part** | **Target % of LCP** | **What it measures** |
| --- | --- | --- |
| **TTFB** | \~40% (1.0s) | Time for server to return first byte |
| **Resource Load Delay** | <10% (0.25s) | Time before LCP resource starts downloading |
| **Resource Load Duration** | \~40% (1.0s) | Time to download the LCP resource |
| **Element Render Delay** | <10% (0.25s) | Time from download complete to painted |

These percentages are diagnostic guidelines, not fixed budgets. The two delay phases should be close to zero. TTFB and resource transfer take real network time, so they usually occupy most of a healthy LCP trace.

### Why this matters

Each sub-part has different causes:

- **High TTFB**: Server issues, no caching, redirects, slow database
- **High Load Delay**: LCP image not discoverable in HTML, blocked by scripts
- **High Load Duration**: Image too large, no CDN, slow connection
- **High Render Delay**: Render-blocking CSS/JS, large DOM, client-side rendering

Measure first, then target the right sub-part. The [**~~2026 LCP practices guide~~**](https://unlighthouse.dev/learn-lighthouse/lcp/best-practices-2026) covers current Lighthouse Insights and newer browser features after you fix the basic loading path.

## Common LCP issues

Poor LCP stems from a short list of causes. Here are the most impactful:

| **Issue** | **Impact** | **Difficulty** | **Fix Time** |
| --- | --- | --- | --- |
| [**~~Slow Server Response (TTFB)~~**](https://unlighthouse.dev/learn-lighthouse/lcp/slow-server-response) | High | Medium | Hours–Days |
| [**~~Render-Blocking Resources~~**](https://unlighthouse.dev/learn-lighthouse/lcp/render-blocking-resources) | High | Medium | Hours |
| [**~~Redirects~~**](https://unlighthouse.dev/learn-lighthouse/lcp/redirects) | High | Low | Minutes |
| [**~~Prioritize LCP Image~~**](https://unlighthouse.dev/learn-lighthouse/lcp/prioritize-lcp-image) | High | Low | Minutes |
| [**~~LCP Lazy-Loaded~~**](https://unlighthouse.dev/learn-lighthouse/lcp/lcp-lazy-loaded) | High | Low | Minutes |
| [**~~Resource Load Delay~~**](https://unlighthouse.dev/learn-lighthouse/lcp/resource-load-delay) | High | Medium | Hours |
| [**~~Client-Side Rendering~~**](https://unlighthouse.dev/learn-lighthouse/lcp/client-side-rendering) | High | High | Hours–Days |
| [**~~Large Images~~**](https://unlighthouse.dev/learn-lighthouse/lcp/large-images) | Medium | Low | Minutes |
| [**~~Lazy Loading Above Fold~~**](https://unlighthouse.dev/learn-lighthouse/lcp/lazy-loading-above-fold) | Medium | Low | Minutes |
| [**~~Total Byte Weight~~**](https://unlighthouse.dev/learn-lighthouse/lcp/total-byte-weight) | Medium | Medium | Hours |
| [**~~Unminified JavaScript~~**](https://unlighthouse.dev/learn-lighthouse/lcp/unminified-javascript) | Medium | Low | Minutes |
| [**~~Unused JavaScript~~**](https://unlighthouse.dev/learn-lighthouse/lcp/unused-javascript) | Medium | High | Hours–Days |

→ [**~~Diagnose your specific issue~~**](https://unlighthouse.dev/learn-lighthouse/lcp#common-lcp-issues)

## How to measure LCP

### Lab testing (development)

Lab tests give you controlled, reproducible results - but they represent synthetic conditions, not real users.

**Chrome DevTools:**

1. Open DevTools → Performance tab
2. Click record → reload page
3. Look for "LCP" marker in timeline
4. Hover to see which element and timing

**Lighthouse:** Run an audit in DevTools or via CLI. Check the LCP metric and related audits under "Opportunities" and "Diagnostics."

**WebPageTest:** Detailed waterfall analysis showing exactly when LCP happens relative to other resources. Use for deep debugging.

### Field data (real users)

Field data is what Google uses for ranking. It represents actual user experience.

**PageSpeed Insights:** Enter your URL to see CrUX (Chrome User Experience Report) data. This is the [**~~same data Google uses for ranking decisions~~**](https://developers.google.com/search/docs/appearance/core-web-vitals).

**Google Search Console:** The Core Web Vitals report shows which URLs pass or fail, grouped by similar pages.

**Web Vitals JavaScript Library:**

```js
import { onLCP } from 'web-vitals'

onLCP((metric) => {
  console.log('LCP:', metric.value, 'ms')
  console.log('Element:', metric.attribution.element)
  console.log('URL:', metric.attribution.url)
})
```

Send this data to your analytics for real user monitoring.

To catch regressions automatically, set up [**~~Lighthouse CI~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci) in your deployment pipeline.

### Lab vs field discrepancy

Common: your lab score is fine but field data fails. This usually means:

- Real users have slower connections than your test
- Real users hit pages you're not testing
- Third-party scripts behave differently in production
- Caching works in lab but not for first-time visitors

Always prioritize field data over lab scores.

## Framework guides

Framework-specific optimizations for LCP:

**Next.js**

Image component, automatic optimization, and App Router streaming.

**Nuxt**

NuxtImage, automatic srcset, and Nitro prerendering.

**React**

Suspense boundaries, lazy loading, and SSR strategies.

**Vue**

Async components, SSR hydration, and image handling.

**Svelte**

[**~~SvelteKit~~**](https://svelte.dev/docs/kit/introduction) loading strategies and image optimization.

**Angular**

NgOptimizedImage and SSR with Angular Universal.

## Test your entire site

Checking LCP page-by-page misses the big picture. Your homepage might pass while 200 blog posts fail. Product pages might score well except for ones with large hero images.

[**~~Unlighthouse~~**](https://unlighthouse.dev/) scans your entire site and surfaces LCP scores for every page. The CLI is free and runs locally. Cloud adds scheduled monitoring and historical tracking to catch regressions before users do.

## Common myths

### " [**~~schema.org~~**](http://schema.org) improves LCP"

**False.** Structured data (JSON-LD) helps search engines understand your content and can improve Click-Through Rate (CTR) via rich results, but it has **zero direct impact** on LCP or load times. Focus on [**~~rendering performance~~**](https://unlighthouse.dev/learn-lighthouse/lcp/render-blocking-resources), not meta tags.

### "accessibility hurts performance"

**False.** Accessible sites are often faster. Semantic HTML is lighter than `**div**` soup. However, screen readers rely on the DOM being ready. A site with a fast LCP but blocked main thread (poor INP) creates a frustrating experience for assistive technology users. Fast LCP is the first step in digital accessibility.

### **Related **

[**Core Web Vitals Overview**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) [**Fix CLS**](https://unlighthouse.dev/learn-lighthouse/cls) [**Fix INP**](https://unlighthouse.dev/learn-lighthouse/inp) [**LCP Definition**](https://unlighthouse.dev/glossary/lcp) [**Speed Index**](https://unlighthouse.dev/glossary/speed-index) [**LCP Finder Tool**](https://unlighthouse.dev/tools/lcp-finder)

[**Hydration Issues** Framework hydration blocks interactivity. Delay and partial hydration strategies to make SSR sites responsive faster.](https://unlighthouse.dev/learn-lighthouse/inp/hydration-issues) [**Slow Server Response** Reduce server response time to improve LCP. Learn CDN setup, caching strategies, database optimization, and edge computing solutions.](https://unlighthouse.dev/learn-lighthouse/lcp/slow-server-response)

**On this page **

- [What is LCP?](#what-is-lcp)
- [Why LCP matters](#why-lcp-matters)
- [Start with field data](#start-with-field-data)
- [LCP sub-parts breakdown](#lcp-sub-parts-breakdown)
- [Common LCP issues](#common-lcp-issues)
- [How to measure LCP](#how-to-measure-lcp)
- [Framework guides](#framework-guides)
- [Test your entire site](#test-your-entire-site)
- [Common myths](#common-myths)

---

- **Page:** Lighthouse CI (LHCI): Complete Guide to @lhci&#x2F;cli in 2026 · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/lighthouse-ci
- **Description:** Complete guide to Lighthouse CI (@lhci/cli) from Google. Automate Lighthouse audits in CI/CD, enforce performance budgets, prevent regressions. Install, configure, GitHub Actions.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Lighthouse CI (LHCI): Complete Guide to @lhci/cli in 2026**

Complete guide to Lighthouse CI (@lhci/cli) from Google. Automate Lighthouse audits in CI/CD, enforce performance budgets, prevent regressions. Install, configure, GitHub Actions.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw) Published **Jan 24, 2025** Updated **Apr 13, 2026**

Lighthouse CI (LHCI) is Google's official tool for running Lighthouse audits in continuous integration pipelines. It catches performance regressions before they reach production.

**Current Version**: LHCI 0.15.x uses Lighthouse 12.6.1. The PWA category was [**~~removed in Lighthouse 12~~**](https://developers.google.com/speed/docs/insights/release_notes) (May 2024). Lighthouse 13 is not yet supported as it requires Node 22.19+.

## What is Lighthouse CI?

Lighthouse CI is a suite of tools that integrate Lighthouse into your CI/CD workflow:

- **@lhci/cli**: Command-line tool for running audits (\~2M monthly [**~~npm~~**](https://npmjs.com) downloads)
- **@lhci/server**: Optional server for storing historical data
- **GitHub App**: Status checks on pull requests

## Why Use Lighthouse CI?

[**~~Elite performers are 2.6x more likely~~**](https://dora.dev/publications/2023-dora-report/) to have integrated automated performance testing into their CI/CD pipelines. Without it, regressions slip through:

1. Developer fixes performance issues
2. PR gets merged
3. Next week, someone adds a 500KB image
4. Performance tanks, nobody notices until users complain

LHCI solves this by running Lighthouse on every commit and failing builds that don't meet your standards.

## Key Features

- **Regression prevention**: Fail builds when [**~~Core Web Vitals~~**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) like [**~~LCP~~**](https://unlighthouse.dev/learn-lighthouse/lcp), [**~~CLS~~**](https://unlighthouse.dev/learn-lighthouse/cls), and [**~~TBT~~**](https://unlighthouse.dev/glossary/tbt) (proxy for [**~~INP~~**](https://unlighthouse.dev/learn-lighthouse/inp)) drop
- **Performance budgets**: Set thresholds for scores and resource sizes
- **Historical tracking**: Compare builds over time
- **Variance reduction**: Run multiple times, use median results
- **GitHub integration**: Status checks and PR comments

## Quick Start

Install and run:

```bash
npm install -g @lhci/cli
lhci autorun --collect.url=https://example.com --upload.target=temporary-public-storage
```

Or with a config file (`**lighthouserc.js**`):

```js
export default {
  ci: {
    collect: {
      url: ['https://example.com/'],
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
}
```

Then run:

```bash
lhci autorun
```

## Setting Up Lighthouse Continuous Integration

Getting Lighthouse into your CI pipeline takes four steps: install `**@lhci/cli**`, add a config file with your URLs and budgets, wire it into your CI workflow (GitHub Actions, GitLab CI, etc.), and optionally connect the LHCI server for historical tracking. The tutorials below walk through each platform in detail.

## How It Works

The `**lhci autorun**` command executes three steps:

1. **collect**: Runs Lighthouse N times per URL
2. **assert**: Checks results against budgets/assertions
3. **upload**: Stores results (temporary storage, filesystem, or LHCI server)

Run `**lhci healthcheck --fatal**` separately to verify Chrome and config before autorun.

Results are saved to `**.lighthouseci/**` locally.

## What LHCI Measures

Lighthouse CI audits four categories on every run:

- **Performance**: [**~~Core Web Vitals~~**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) ([**~~LCP~~**](https://unlighthouse.dev/learn-lighthouse/lcp), [**~~CLS~~**](https://unlighthouse.dev/learn-lighthouse/cls), [**~~TBT~~**](https://unlighthouse.dev/glossary/tbt) as proxy for [**~~INP~~**](https://unlighthouse.dev/learn-lighthouse/inp)) and other speed metrics
- **Accessibility**: [**~~Screen reader support, color contrast, ARIA~~**](https://unlighthouse.dev/learn-lighthouse/accessibility)
- **SEO**: [**~~Meta tags, structured data, mobile-friendliness~~**](https://unlighthouse.dev/learn-lighthouse/seo)
- **Best Practices**: [**~~HTTPS, console errors, deprecated APIs~~**](https://unlighthouse.dev/learn-lighthouse/best-practices)

Each category gets a 0-100 score. Set thresholds in your config to block merges when scores drop.

**How scores map to percentiles**: A score of 50 means you're faster than 75% of sites. A score of 90 puts you in the [**~~top 8% of all websites~~**](https://developer.chrome.com/docs/lighthouse/performance/performance-scoring). Currently, only [**~~53% of origins pass all Core Web Vitals~~**](https://almanac.httparchive.org/en/2025/performance).

## Prerequisites

- [**~~Node.js~~**](https://nodejs.org/en) 18+
- Chrome/Chromium installed
- A URL to test (can be localhost with `**startServerCommand**`)

## Tutorials

[GitHub Actions](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/github-actions)

**GitHub Actions**

Set up LHCI with GitHub Actions and status checks.

[GitLab CI](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/gitlab-ci)

**GitLab CI**

Configure LHCI for GitLab CI/CD pipelines.

[Configuration](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/configuration)

**Configuration**

All lighthouserc.js options explained.

[Performance Budgets](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/budgets)

**Performance Budgets**

Set and enforce performance thresholds.

[LHCI Server](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/server)

**LHCI Server**

Self-host a dashboard for historical tracking.

[Troubleshooting](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/troubleshooting)

**Troubleshooting**

Fix common LHCI issues.

## Performance Impact

Why invest in performance testing? Research shows direct business impact:

- [**~~BBC loses 10% of users~~**](https://www.creativebloq.com/features/how-the-bbc-builds-websites-that-scale) for every additional second of load time
- [**~~Amazon estimates~~**](https://www.cloudflare.com/learning/performance/more/website-performance-conversion-rates/) every 100ms of latency costs 1% in sales
- [**~~Google research~~**](https://web.dev/articles/why-speed-matters) shows bounce probability increases 90% as load time goes from 1s to 5s

## Resources

- [**~~GitHub Repository~~**](https://github.com/GoogleChrome/lighthouse-ci)
- [**~~Official Documentation~~**](https://googlechrome.github.io/lighthouse-ci/)
- [**~~npm Package~~**](https://www.npmjs.com/package/@lhci/cli) i)

### **Related **

[**Core Web Vitals Guide**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) [**Bulk Lighthouse Testing**](https://unlighthouse.dev/learn-lighthouse/bulk-lighthouse-testing) [**LCP Guide**](https://unlighthouse.dev/learn-lighthouse/lcp) [**CLS Guide**](https://unlighthouse.dev/learn-lighthouse/cls) [**INP Guide**](https://unlighthouse.dev/learn-lighthouse/inp) [**Core Web Vitals Checker**](https://unlighthouse.dev/tools/cwv-checker) [**Bulk PageSpeed Test**](https://unlighthouse.dev/tools/bulk-pagespeed)

[**LHCI vs Unlighthouse** Honest side-by-side comparison of @lhci/cli and Unlighthouse. Setup, URL discovery, budgets, reporting, and when each tool fits your workflow.](https://unlighthouse.dev/learn-lighthouse/lhci-vs-unlighthouse) [**GitHub Actions** Complete Lighthouse CI GitHub Actions documentation. Step-by-step YAML workflows, status checks, PR comments, and treosh/lighthouse-ci-action setup.](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/github-actions)

**On this page **

- [What is Lighthouse CI?](#what-is-lighthouse-ci)
- [Why Use Lighthouse CI?](#why-use-lighthouse-ci)
- [Key Features](#key-features)
- [Quick Start](#quick-start)
- [Setting Up Lighthouse Continuous Integration](#setting-up-lighthouse-continuous-integration)
- [How It Works](#how-it-works)
- [What LHCI Measures](#what-lhci-measures)
- [Prerequisites](#prerequisites)
- [Tutorials](#tutorials)
- [Performance Impact](#performance-impact)
- [Resources](#resources)

---

- **Page:** Cumulative Layout Shift (CLS): What Is a Good Score &amp; How to Fix · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/cls
- **Description:** Google considers a CLS score of 0.1 or less as good. Learn what causes layout shifts and how to fix CLS with proven techniques for images, fonts, ads, and dynamic content.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Cumulative Layout Shift (CLS): What Is a Good Score & How to Fix**

Google considers a CLS score of 0.1 or less as good. Learn what causes layout shifts and how to fix CLS with proven techniques for images, fonts, ads, and dynamic content.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)8 min read Published **Jan 18, 2025** Updated **Aug 9, 2026**

**Cumulative Layout Shift (CLS) measures unexpected movement of page content.** Google considers a CLS score of 0.1 or less good, above 0.1 through 0.25 needs improvement, and above 0.25 poor. CLS is one of the three [**~~Core Web Vitals~~**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals).

**CLS**Cumulative Layout Shift** CWV **

**25% weight **

Good ≤0.10Poor >0.25

CLS measures unexpected layout shifts, visible elements moving without the user causing the movement. In the [**~~2025 Web Almanac~~**](https://almanac.httparchive.org/en/2025/performance), 81% of mobile pages and 72% of desktop pages had good CLS.

But "easiest" doesn't mean unimportant. Layout shifts destroy trust. When users click a button and hit an ad instead, or lose their reading position because a banner appeared, they leave.

[**~~Redbus reduced CLS from 1.65 to 0 and saw 80-100% higher mobile conversion rates~~**](https://web.dev/case-studies/vitals-business-impact). Visual stability directly impacts revenue.

## What is CLS?

Cumulative Layout Shift tracks how much visible content moves unexpectedly. Lighthouse calculates the score by multiplying two fractions for each shift:

**Impact Fraction** × **Distance Fraction** = Layout Shift Score

- **Impact fraction:** Percentage of viewport affected by the shift
- **Distance fraction:** Distance elements moved relative to viewport

A small image shifting 50px causes less CLS than a large banner shifting 200px.

**CLS Thresholds:**

| **Score** | **Rating** | **What it means** |
| --- | --- | --- |
| ≤0.1 | Good | Stable, predictable layout |
| 0.1–0.25 | Needs Improvement | Noticeable shifts, frustrating UX |
| >0.25 | Poor | Severe shifts, users misclick |

**Score Weight:** CLS accounts for **25%** of your Lighthouse Performance score - tied with LCP for the largest weight.

**How Lighthouse measures CLS:** Since [**~~April 2021~~**](https://web.dev/blog/evolving-cls), CLS uses a "session window" approach. It captures the maximum burst of layout shifts with a 1-second gap and 5-second cap. This makes CLS [**~~more fair for long-lived pages and SPAs~~**](https://web.dev/blog/evolving-cls).

**User-initiated shifts are excluded:** Layout shifts within [**~~500ms of discrete user input~~**](https://web.dev/articles/cls) (clicks, taps, keypresses) don't count. Scroll and pinch gestures don't trigger this exclusion - those are continuous inputs.

→ [**~~Full CLS definition~~**](https://unlighthouse.dev/glossary/cls)

## Why CLS matters

### User experience

Layout shifts cause users to:

- Click the wrong button or link (the infamous "misclick")
- Lose their place while reading
- Accidentally trigger unwanted actions like purchases
- Perceive the site as broken or low-quality

The frustration is visceral. Users don't think "this page has poor CLS" - they think "this site is garbage."

### Search impact

CLS contributes to the [**~~page experience signals Google considers~~**](https://developers.google.com/search/docs/appearance/page-experience), but a good score does not guarantee a ranking change. Google evaluates field data at the 75th percentile. At least 75% of measured visits must be at or below 0.1 for a URL or origin to be classed as good.

### Business impact

| **Company** | **CLS Improvement** | **Business Impact** |
| --- | --- | --- |
| [**~~Redbus~~**](https://web.dev/case-studies/vitals-business-impact) | 1.65 → 0 | 80-100% higher mobile conversions |
| [**~~Yahoo! Japan~~**](https://web.dev/case-studies/vitals-business-impact) | 98% reduction | 15% more page views per session |
| [**~~AliExpress~~**](https://web.dev/case-studies/vitals-business-impact) | 10x improvement | 15% lower bounce rates |
| [**~~iCook~~**](https://web.dev/case-studies/vitals-business-impact) | 15% improvement | 10% more ad revenue |

The pattern is clear: visual stability correlates with engagement and conversion.

## Common CLS issues

Lighthouse identifies these root causes for layout shifts:

| **Issue** | **Impact** | **Difficulty** |
| --- | --- | --- |
| [**~~Images Without Dimensions~~**](https://unlighthouse.dev/learn-lighthouse/cls/unsized-images) | High | Low |
| [**~~Large Layout Shifts~~**](https://unlighthouse.dev/learn-lighthouse/cls/layout-shifts) | High | Varies |
| [**~~Dynamic Content Injection~~**](https://unlighthouse.dev/learn-lighthouse/cls/dynamic-content-injection) | High | Medium |
| [**~~Web Fonts (FOIT/FOUT)~~**](https://unlighthouse.dev/learn-lighthouse/cls/web-fonts-causing-foit) | Medium | Medium |
| [**~~Ads, Embeds, iframes~~**](https://unlighthouse.dev/learn-lighthouse/cls/ads-embeds-iframes) | Medium | Medium |
| [**~~Animations & Transitions~~**](https://unlighthouse.dev/learn-lighthouse/cls/animations-transitions) | Low | Low |

The audit tracks up to 15 layout shifts and shows the element that shifted most for each event, along with the root cause (unsized media, web font loaded, or injected iframe).

→ [**~~All CLS issues and fixes~~**](https://unlighthouse.dev/learn-lighthouse/cls#common-cls-issues)

### Try it: layout shift playground

Trigger common layout shifts and see how they affect the CLS score:

Loading demo...

## How to measure CLS

### Lab testing (development)

Lab tests give you controlled, reproducible results - but they capture only shifts during page load, not during longer sessions.

**Chrome DevTools:**

1. Open DevTools → **Performance** tab
2. Click record → reload page → stop recording
3. Look for pink "Layout Shift" entries in the timeline
4. Click to see which elements shifted and by how much

**Lighthouse:** Run an audit and check the CLS metric. The "Avoid large layout shifts" diagnostic shows the top shifting elements with their root causes.

**[**~~CLS Debugger Tool~~**](https://unlighthouse.dev/tools/cls-debugger):** Enter any URL to identify exactly which elements cause layout shifts - no install required.

**Console snippet:**

```js
function observeLayoutShifts() {
  const observer = new PerformanceObserver((list) => {
    list.getEntries().forEach((entry) => {
      console.log('CLS:', entry.value, entry.sources)
    })
  })

  observer.observe({ type: 'layout-shift', buffered: true })
  return () => observer.disconnect()
}
```

Call `**observeLayoutShifts()**` in the browser console. It logs each shift with its source element and returns a cleanup function.

### Field data (real users)

Field data captures shifts throughout the user session, not just initial load.

**PageSpeed Insights:** Shows CrUX data for your URL - the same data Google uses for ranking.

**Google Search Console:** Core Web Vitals report groups URLs by CLS status.

**Web Vitals Chrome Extension:** Shows CLS in real-time and highlights shifting elements with red overlays.

**Web Vitals JavaScript Library:**

```js
import { onCLS } from 'web-vitals'

onCLS((metric) => {
  console.log('CLS:', metric.value)
  console.log('Entries:', metric.entries)
})
```

To catch regressions automatically, set up [**~~Lighthouse CI~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci) in your deployment pipeline.

### Lab vs field CLS

**Important:** Lab CLS can be [**~~artificially lower than field CLS~~**](https://web.dev/articles/lab-and-field-data-differences) because:

- Lab tests end at "page load" while field data captures shifts throughout the session
- Ads and third-party content may load differently in lab conditions
- User interactions in the field trigger shifts that lab tests miss

Always verify with real user data. If field CLS is worse than lab, you have shifts happening after initial load - likely from ads, lazy-loaded content, or user interactions.

## Diagnose the failing visit

The aggregate CLS number tells you a problem exists. Attribution tells you where to look.

1. Check PageSpeed Insights or Search Console to identify the failing device group and URL pattern.
2. Reproduce a representative URL with a fresh profile. Cookie banners and ads often disappear after the first visit.
3. Record the whole interaction flow in the DevTools Performance panel, not only the initial load.
4. Expand each layout shift cluster and inspect both the shifted element and the element that caused it to move.
5. Verify the fix with field monitoring. CrUX uses a rolling window, so it will not change immediately after deployment.

### Common gotchas

| **Gotcha** | **Impact** | **Fix** |
| --- | --- | --- |
| **Late-loading CSS** | Flash of Unstyled Content (FOUC) | Ensure critical CSS is inline or loaded in `**<head>**`. Async CSS loading without critical CSS extraction guarantees layout shifts. |
| **Viewport Meta Tag** | Scaling and layout | Missing `**<meta name="viewport" content="width=device-width, initial-scale=1">**` makes mobile rendering unreliable. |
| **Cookie Banners** | 0.1+ CLS Score | Often ignored in development because "I already accepted it." Test in Incognito mode. Banners pushing content down are a top CLS cause. |

## Framework guides

Framework-specific CLS fixes:

**Next.js**

next/image with dimensions, font optimization with next/font.

**Nuxt**

NuxtImage sizing, @nuxt/fonts for font loading.

**React**

Placeholder strategies, Suspense boundary sizing.

**Vue**

v-if/v-show transitions, async component sizing.

**Svelte**

enhanced:img dimensions, transition handling.

**Angular**

NgOptimizedImage with dimensions, @angular/fonts.

## Test your entire site

Most tools only test one page at a time. Your homepage might pass CLS while your blog template has unsized images causing shifts on every post.

[**~~Unlighthouse~~**](https://unlighthouse.dev/) scans your entire site and shows CLS scores for every page. The CLI is free and runs locally. Cloud adds scheduled monitoring to catch regressions before users do.

### **Related **

[**Core Web Vitals Overview**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) [**Fix LCP**](https://unlighthouse.dev/learn-lighthouse/lcp) [**Fix INP**](https://unlighthouse.dev/learn-lighthouse/inp) [**CLS Definition**](https://unlighthouse.dev/glossary/cls) [**CLS Debugger Tool**](https://unlighthouse.dev/tools/cls-debugger)

[**Inspector Issues** Resolve browser-detected problems including mixed content, cookie issues, CSP violations, and cross-origin blocks that appear in Chrome's Issues panel.](https://unlighthouse.dev/learn-lighthouse/best-practices/inspector-issues) [**Images Without Dimensions** Images without width and height cause layout shifts. Add explicit dimensions to prevent your page from jumping around as images load.](https://unlighthouse.dev/learn-lighthouse/cls/unsized-images)

**On this page **

- [What is CLS?](#what-is-cls)
- [Why CLS matters](#why-cls-matters)
- [Common CLS issues](#common-cls-issues)
- [How to measure CLS](#how-to-measure-cls)
- [Diagnose the failing visit](#diagnose-the-failing-visit)
- [Framework guides](#framework-guides)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Web Performance Glossary · Unlighthouse
- **Source:** https://unlighthouse.dev/glossary
- **Description:** Definitions and explanations of Core Web Vitals, Lighthouse metrics, and web performance terminology.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Web Performance Glossary **

Definitions and explanations of Core Web Vitals, Lighthouse metrics, and web performance terminology.

## **Core Web Vitals **

Google's three key metrics that affect search rankings.

[<h3>**CLS**</h3>

CLS measures visual stability. Learn what it is, thresholds, and how to prevent layout shifts.](https://unlighthouse.dev/glossary/cls) [<h3>**INP**</h3>

INP measures responsiveness. Learn what it is, thresholds, and how to improve interaction speed.](https://unlighthouse.dev/glossary/inp) [<h3>**LCP**</h3>

LCP measures loading performance. Learn what it is, thresholds, and how to improve your score.](https://unlighthouse.dev/glossary/lcp)

## **Lighthouse Performance Metrics **

Additional metrics reported by Lighthouse that contribute to your performance score.

[<h3>**Speed Index**</h3>Speed Index (SI) measures how fast visible content fills the viewport. Good: ≤3.4s mobile, ≤1.3s desktop. 10% of Lighthouse performance score. Thresholds, tools, fixes.](https://unlighthouse.dev/glossary/speed-index) [<h3>**FCP**</h3>

FCP measures when the first content renders. Learn what it is, thresholds, and how to improve it.](https://unlighthouse.dev/glossary/fcp) [<h3>**TTFB**</h3>

TTFB measures server response time. Learn what it is, thresholds, and how to optimize it.](https://unlighthouse.dev/glossary/ttfb) [<h3>**TBT**</h3>

TBT measures main thread blocking during load. Learn what it is, thresholds, and how to reduce blocking time.](https://unlighthouse.dev/glossary/tbt)

## **Deprecated Metrics **

[<h3>**TTI (Deprecated)**</h3>TTI measured page interactivity but was deprecated in Lighthouse 10. Learn what replaced it.](https://unlighthouse.dev/glossary/tti)

## **Measure Your Site **

Use Unlighthouse to audit all these metrics across your entire website in a single scan.

$npxunlighthouse--siteexample.com

[**Get Started **](https://unlighthouse.dev/guide/getting-started/installation)

---

- **Page:** Interaction to Next Paint (INP) Guide · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/inp
- **Description:** Master INP optimization with practical fixes for JavaScript execution, DOM operations, and event handlers. Improve responsiveness across your site.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Interaction to Next Paint (INP) Guide**

Master INP optimization with practical fixes for JavaScript execution, DOM operations, and event handlers. Improve responsiveness across your site.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)9 min read Published **Jan 18, 2025**

**INP**Interaction to Next Paint** CWV **

**0% weight **

Good ≤200msPoor >500ms

INP is the [**~~hardest Core Web Vital for mobile users~~**](https://almanac.httparchive.org/en/2024/performance). While 97% of desktop pages pass, only 74% of mobile pages achieve good INP. That 23-point gap matters - mobile users make up [**~~over 60% of web traffic~~**](https://gs.statcounter.com/platform-market-share/desktop-mobile-tablet).

INP [**~~replaced FID as a Core Web Vital on March 12, 2024~~**](https://web.dev/blog/inp-cwv-march-12). The bar got higher: [**~~93% of sites passed FID~~**](https://web.dev/blog/inp-cwv), but FID only measured input delay on the first interaction. INP measures everything - every click, tap, and keypress throughout the entire page session.

## What is INP?

Interaction to Next Paint measures responsiveness - how long it takes for the page to visually respond after a user interacts. Google uses this definition from the Lighthouse audit:

> *"Interaction to Next Paint measures page responsiveness, how long it takes the page to visibly respond to user input."*

**INP Thresholds:**

| **Score** | **Rating** | **What It Feels Like** |
| --- | --- | --- |
| ≤200ms | Good | Instant, responsive |
| 200–500ms | Needs Improvement | Noticeable lag |
| >500ms | Poor | Frustratingly slow |

**Score Weight:** INP doesn't directly affect Lighthouse Performance scores in lab mode. Instead, Lighthouse uses [**~~Total Blocking Time (TBT)~~**](https://unlighthouse.dev/glossary/tbt) as a proxy, which accounts for **30%** of the score. In field data (CrUX), CrUX measures INP directly.

## What triggers INP

INP only measures discrete interactions - events that have a clear start and end:

| **Interaction Type** | **Examples** |
| --- | --- |
| **Clicks** | Button clicks, link clicks, checkbox toggles |
| **Taps** | Mobile screen taps, touch inputs |
| **Key Presses** | Typing in inputs, keyboard shortcuts |

**Not measured:** Scrolling, hovering, and pinch-to-zoom. These are continuous interactions with different performance characteristics.

The browser tracks all qualifying interactions during the page session. Your INP score is typically the worst interaction (or 98th percentile on pages with many interactions).

## Why INP matters

### User experience

Users expect instant feedback. [**~~Research shows~~**](https://web.dev/articles/defining-core-web-vitals-thresholds) that delays over 200ms start to feel sluggish. Past 500ms, users assume something is broken.

The consequences of poor INP:

- Users click multiple times, triggering duplicate actions
- Forms feel unresponsive, causing input errors
- E-commerce checkouts get abandoned
- Users perceive your site as low-quality

Since [**~~90% of user time on a page happens after it loads~~**](https://web.dev/articles/inp), INP captures the experience that matters most.

### SEO impact

INP officially replaced FID as a [**~~Core Web Vital ranking factor on March 12, 2024~~**](https://developers.google.com/search/docs/appearance/core-web-vitals). While FID only measured the *first* interaction, INP influences ranking eligibility by measuring *all* interactions.

For 2025, the bar is strict: Google treats <200ms as the "Good" threshold for ranking boosts. Sites consistently failing this metric see reduced visibility in competitive search results.

### Industry benchmarks & competitive advantage

Passing Core Web Vitals is harder than it looks. As of mid-2024, [**~~only \~47% of websites passed all Core Web Vitals~~**](https://almanac.httparchive.org/en/2024/performance).

| **Sector** | **INP Pass Rate** | **Opportunity** |
| --- | --- | --- |
| **eCommerce** | Low | High - most catalogs are heavy |
| **News/Media** | Medium | High - ad scripts kill INP |
| **B2B SaaS** | High | Low - usually simpler apps |

Fixing INP isn't just about compliance - it's a competitive advantage. If you're in the 47% that pass, you're likely outranking half your competitors on technical merit alone.

### Business impact

Real-world improvements show direct business correlation:

| **Company** | **INP Change** | **Business Impact** |
| --- | --- | --- |
| [**~~Trendyol~~**](https://web.dev/case-studies/trendyol-inp) | 50% reduction | 1% higher click-through rate |
| [**~~The Economic Times~~**](https://web.dev/case-studies/economic-times-inp) | 3x faster | 43% lower bounce rate |
| [**~~redBus~~**](https://web.dev/case-studies/redbus-inp) | 72% reduction | Higher engagement metrics |
| [**~~Taboola~~**](https://web.dev/case-studies/taboola-inp) | Multiple optimizations | 5.5% higher ad click-through |

## Understanding INP sub-parts

Every interaction breaks down into three phases. [**~~Presentation delay often accounts for a significant portion of total INP~~**](https://web.dev/articles/optimize-inp#presentation_delay) on average - often the overlooked bottleneck.

| **Phase** | **What Happens** | **What Causes Delays** |
| --- | --- | --- |
| **Input Delay** | Time waiting for main thread to become free | Long tasks blocking the thread |
| **Processing Duration** | Time running your event handlers | Complex handler logic |
| **Presentation Delay** | Time for browser to render the result | DOM updates, layout, paint |

**The critical insight:** Most developers focus on processing duration because that's their code. But input delay and presentation delay often account for 60%+ of total INP. A efficient event handler still fails INP if the main thread was blocked or the DOM update triggered expensive layout.

### Try it: response time lab

Click the buttons to feel the difference between fast and slow responses:

Loading demo...

## Common INP issues

Poor INP stems from a handful of causes. Here are the most impactful:

| **Issue** | **Impact** | **Difficulty** | **Fix Time** |
| --- | --- | --- | --- |
| [**~~Long-Running JavaScript~~**](https://unlighthouse.dev/learn-lighthouse/inp/long-running-javascript) | High | Medium | Hours |
| [**~~Heavy DOM Operations~~**](https://unlighthouse.dev/learn-lighthouse/inp/heavy-dom-operations) | High | Medium | Hours |
| [**~~Third-Party Scripts~~**](https://unlighthouse.dev/learn-lighthouse/inp/third-party-scripts) | High | Low | Minutes–Hours |
| [**~~Total Blocking Time~~**](https://unlighthouse.dev/learn-lighthouse/inp/total-blocking-time) | High | Medium | Hours |
| [**~~DOM Size~~**](https://unlighthouse.dev/learn-lighthouse/inp/dom-size) | Medium | Medium | Hours |
| [**~~Event Handler Delays~~**](https://unlighthouse.dev/learn-lighthouse/inp/event-handler-delays) | Medium | Low | Minutes |
| [**~~Hydration Issues~~**](https://unlighthouse.dev/learn-lighthouse/inp/hydration-issues) | Medium | High | Hours–Days |

→ [**~~Diagnose your specific issue~~**](https://unlighthouse.dev/learn-lighthouse/inp#common-inp-issues)

## How to measure INP

### Lab testing (proxy)

INP requires real user interaction - you can't measure it with an automated page load. Lab tools use Total Blocking Time (TBT) as a proxy because [**~~TBT correlates twice as well with INP than FID did~~**](https://github.com/GoogleChrome/web.dev/issues/8395).

**Chrome DevTools:**

1. Open DevTools → **Performance** tab
2. Check **"Web Vitals"** in settings
3. Click record → interact with the page → stop recording
4. Look for interaction events and their duration

**Lighthouse:** Check the TBT score as your INP proxy. The thresholds are:

- **Mobile:** Good ≤200ms, Poor >600ms
- **Desktop:** Good ≤150ms, Poor >350ms

**[**~~INP Analyzer Tool~~**](https://unlighthouse.dev/tools/inp-analyzer):** Enter any URL to analyze interaction responsiveness - no install required.

### Field data (real users)

Field data is what Google uses for ranking. It represents actual user experience.

**PageSpeed Insights:** Enter your URL to see CrUX (Chrome User Experience Report) INP data. This shows real-world performance from Chrome users.

**Search Console:** The Core Web Vitals report shows which URLs pass or fail INP, grouped by similar pages.

**Web Vitals JavaScript Library:**

```js
import { onINP } from 'web-vitals'

onINP((metric) => {
  console.log('INP:', metric.value, 'ms')
  console.log('Element:', metric.attribution.interactionTarget)
  console.log('Type:', metric.attribution.interactionType)
})
```

To catch regressions automatically, set up [**~~Lighthouse CI~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci) in your deployment pipeline.

### Mobile vs desktop gap

The INP gap between devices is massive:

| **Device** | **Good INP Rate (2024)** |
| --- | --- |
| Desktop | 97% |
| Mobile | 74% |

This [**~~23-point gap~~**](https://almanac.httparchive.org/en/2024/performance) means mobile optimization is essential. Mobile devices have:

- Slower CPUs that struggle with JavaScript
- Touch events that trigger more complex handlers
- Limited memory causing more garbage collection pauses

Test on real mobile devices, not just throttled desktop browsers.

## Framework guides

Framework-specific INP optimizations:

**Next.js**

Hydration strategies, Server Components, and useTransition.

**Nuxt**

Payload optimization, lazy hydration, and component islands.

**React**

startTransition, useDeferredValue, and avoiding re-render cascades.

**Vue**

Reactivity optimization, async components, and computed caching.

**Svelte**

Minimal runtime overhead and smart DOM updates.

**Angular**

Zone.js optimization, OnPush change detection, and signals.

## Test your entire site

Most tools test one page at a time. That's a problem for INP - different pages have different JavaScript, different event handlers, and different interaction patterns.

Your homepage might pass while your checkout fails. Product pages might be fast until someone opens the image gallery.

[**~~Unlighthouse~~**](https://unlighthouse.dev/) scans your entire site and shows TBT (INP proxy) scores for every page. You'll see which templates have issues, which pages are outliers, and whether your fixes work at scale.

The CLI is free and runs locally. Cloud adds scheduled monitoring to catch regressions before users report them.

### **Related **

[**Core Web Vitals Overview**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) [**Fix LCP**](https://unlighthouse.dev/learn-lighthouse/lcp) [**Fix CLS**](https://unlighthouse.dev/learn-lighthouse/cls) [**INP Definition**](https://unlighthouse.dev/glossary/inp) [**TBT Definition**](https://unlighthouse.dev/glossary/tbt) [**INP Analyzer Tool**](https://unlighthouse.dev/tools/inp-analyzer)

[**Animations & Transitions** Eliminate CLS from animations by using compositor-friendly properties like transform and opacity instead of layout-triggering properties.](https://unlighthouse.dev/learn-lighthouse/cls/animations-transitions) [**Long-Running JavaScript** Reduce JavaScript execution time to improve INP. Learn code splitting, web workers, and task chunking to keep the main thread responsive.](https://unlighthouse.dev/learn-lighthouse/inp/long-running-javascript)

**On this page **

- [What is INP?](#what-is-inp)
- [What triggers INP](#what-triggers-inp)
- [Why INP matters](#why-inp-matters)
- [Understanding INP sub-parts](#understanding-inp-sub-parts)
- [Common INP issues](#common-inp-issues)
- [How to measure INP](#how-to-measure-inp)
- [Framework guides](#framework-guides)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Lighthouse Best Practices Guide · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/best-practices
- **Description:** Understand Lighthouse Best Practices audits, fix common security and browser issues, and verify failures across every page template.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Lighthouse Best Practices Guide**

Understand Lighthouse Best Practices audits, fix common security and browser issues, and verify failures across every page template.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)6 min read Published **Jan 18, 2025** Updated **Aug 9, 2026**

Best Practices audits check whether your site follows established web standards for security, browser compatibility, and user experience. Most produce a pass or fail result, though the exact audit set and category scoring can change between Lighthouse versions.

A site can score 100 on Performance and still fail Best Practices because of a single console error or missing HTTPS. These audits catch the fundamentals that are easy to overlook but damage user trust.

## What Best Practices measures

Treat the category score as a summary, then inspect each failed audit. A score alone cannot tell you whether the problem is a harmless deprecation in a third-party script or an insecure request that exposes user data.

These audits fall into three categories:

- **Security** - Protecting users from attacks and data theft.
- **Browser Compatibility** - Ensuring your site works across browsers and devices.
- **User Experience** - Respecting user expectations and avoiding dark patterns.

## Security audits

Security audits verify your site protects users from common attack vectors.

| **Audit** | **What It Checks** | **Why It Matters** |
| --- | --- | --- |
| [**~~Uses HTTPS~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/is-on-https) | Page loaded over secure connection | Prevents man-in-the-middle attacks, required for modern APIs |
| [**~~Redirects HTTP to HTTPS~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/redirects-http) | HTTP requests redirect to HTTPS | Ensures users always land on secure version |

Browsers treat HTTP pages as insecure, and many web platform APIs require a secure context. Redirect every HTTP request to HTTPS, then check for mixed content loaded by scripts, styles, images, and frames.

## Browser compatibility audits

These audits check that your site works correctly across browsers and uses modern web platform features.

| **Audit** | **What It Checks** | **Why It Matters** |
| --- | --- | --- |
| [**~~bfcache eligible~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/bf-cache) | Page can use back/forward cache | Instant back navigation, better UX |
| [**~~Valid charset~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/charset) | Character encoding declared properly | Prevents garbled text, accessibility issues |
| [**~~Valid DOCTYPE~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/doctype) | HTML5 doctype present | Standards mode rendering, predictable behavior |
| [**~~Avoids deprecated APIs~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/deprecations) | No deprecated browser APIs used | Future-proofing, avoiding breaking changes |

The bfcache audit is particularly impactful. When eligible, back/forward navigation is instant; the browser restores the page from memory rather than reloading. Users expect this behavior and notice when it's broken.

## User experience audits

UX audits catch patterns that frustrate users or violate their expectations.

| **Audit** | **What It Checks** | **Why It Matters** |
| --- | --- | --- |
| [**~~No browser errors~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/errors-in-console) | Console free of errors | Errors indicate broken functionality |
| [**~~No geolocation on start~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/geolocation-on-start) | Geolocation not requested on load | Permission requests need user context |
| [**~~No notification on start~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/notification-on-start) | Notifications not requested on load | Same principle; context before permission |
| [**~~Allows paste in passwords~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/paste-preventing-inputs) | Password fields allow pasting | Password managers need paste support |
| [**~~Proper image sizing~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/image-size-responsive) | Images sized appropriately for display | Prevents blurry or wasteful images |
| [**~~Correct aspect ratios~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/image-aspect-ratio) | Images maintain aspect ratio | Prevents distorted images |
| [**~~No DevTools issues~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/inspector-issues) | No issues flagged by DevTools | Catches various browser-detected problems |

The permission audits reflect a broader principle: never ask for permissions without user context. A geolocation prompt on page load feels invasive. The same prompt after clicking "Find stores near me" makes sense.

## Scoring and version changes

Lighthouse calculates the category score from the audits included in that release. Do not hard-code an expected point deduction for one failure. Record the Lighthouse and Chrome versions in CI so a tool upgrade is easy to distinguish from a site regression.

[**~~Lighthouse 13 removed several legacy audits~~**](https://github.com/GoogleChrome/lighthouse/releases/tag/v13.0.0) after moving their guidance into the newer Insights model. When an audit disappears after an upgrade, compare the basic issue and report details before assuming the site fixed it.

## Common failure patterns

**Third-party scripts:** Ad networks, analytics, and widgets often throw console errors or use deprecated APIs. Choose better vendors or load scripts conditionally if you can't fix these.

**Development leftovers:** Uncaught promise rejections and code paths that only fail with production data. Treat plain `**console.log**` output as noise; runtime errors need separate investigation.

**Legacy code:** Old APIs that still work but are deprecated. The site functions, but the audit fails. Refactoring takes time but avoids future breakage.

**Eager permission requests:** Marketing pressure to prompt for notifications immediately. This tanks user trust and fails the audit. Delay permission requests until users demonstrate intent.

## How to diagnose issues

**Chrome DevTools:**

1. Open DevTools, then select the **Console** tab.
2. Reload the page with Preserve log enabled and reproduce the relevant interaction.
3. Check the **Issues** tab for browser-detected problems.
4. Run Lighthouse from the **Lighthouse** tab in a clean profile.
5. Repeat on one URL from each template. A shared layout or third-party script can fail across hundreds of routes.

**Key things to check:**

- Any JavaScript errors in console?
- Any deprecation warnings?
- What permission prompts appear on load?
- Is the page served over HTTPS?
- Does HTTP redirect to HTTPS?

## All Best Practices issues

Quick reference for every audit:

| **Audit** | **Category** | **Fix Guide** |
| --- | --- | --- |
| Uses HTTPS | Security | [**~~Fix~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/is-on-https) |
| Redirects HTTP to HTTPS | Security | [**~~Fix~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/redirects-http) |
| bfcache eligible | Browser | [**~~Fix~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/bf-cache) |
| Valid charset | Browser | [**~~Fix~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/charset) |
| Valid DOCTYPE | Browser | [**~~Fix~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/doctype) |
| Avoids deprecated APIs | Browser | [**~~Fix~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/deprecations) |
| No browser errors | UX | [**~~Fix~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/errors-in-console) |
| No geolocation on start | UX | [**~~Fix~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/geolocation-on-start) |
| No notification on start | UX | [**~~Fix~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/notification-on-start) |
| Allows paste in passwords | UX | [**~~Fix~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/paste-preventing-inputs) |
| Proper image sizing | UX | [**~~Fix~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/image-size-responsive) |
| Correct aspect ratios | UX | [**~~Fix~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/image-aspect-ratio) |
| No DevTools issues | UX | [**~~Fix~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/inspector-issues) |

> [**~~Diagnose your specific issue~~**](https://unlighthouse.dev/learn-lighthouse/best-practices#all-best-practices-issues)

## Test your entire site

The home page might pass Best Practices while blog posts throw console errors. The checkout flow might request permissions inappropriately. Dynamic pages might have image sizing issues that static pages don't.

[**~~Unlighthouse~~**](https://unlighthouse.dev/) scans your entire site and surfaces Best Practices scores for every page. You'll find console errors on obscure pages, permission prompts you forgot about, and deprecated APIs in legacy sections.

The CLI is free and runs locally. Cloud adds scheduled monitoring to catch regressions, such as when a third-party script update breaks your score.

### **Related **

[**Core Web Vitals Overview**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) [**Performance Guide**](https://unlighthouse.dev/learn-lighthouse/lcp) [**Accessibility Guide**](https://unlighthouse.dev/learn-lighthouse/accessibility) [**SEO Guide**](https://unlighthouse.dev/learn-lighthouse/seo) [**Lighthouse Report Viewer**](https://unlighthouse.dev/tools/lighthouse-report-viewer) [**Bulk PageSpeed Test**](https://unlighthouse.dev/tools/bulk-pagespeed)

[**Heading Order** Fix heading order issues in Lighthouse accessibility audits. Ordered headings convey semantic structure for easier navigation.](https://unlighthouse.dev/learn-lighthouse/accessibility/heading-order) [**Back/Forward Cache** Make back button navigation instant with bfcache. Learn common blockers and how to fix them.](https://unlighthouse.dev/learn-lighthouse/best-practices/bf-cache)

**On this page **

- [What Best Practices measures](#what-best-practices-measures)
- [Security audits](#security-audits)
- [Browser compatibility audits](#browser-compatibility-audits)
- [User experience audits](#user-experience-audits)
- [Scoring and version changes](#scoring-and-version-changes)
- [Common failure patterns](#common-failure-patterns)
- [How to diagnose issues](#how-to-diagnose-issues)
- [All Best Practices issues](#all-best-practices-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** PageSpeed Insights API Guide · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api
- **Description:** Complete guide to using the PageSpeed Insights API. Get Lighthouse performance data programmatically with 25,000 free requests per day.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **PageSpeed Insights API Guide**

Complete guide to using the PageSpeed Insights API. Get Lighthouse performance data programmatically with 25,000 free requests per day.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 18, 2025**

The PageSpeed Insights API returns Lighthouse performance data for any URL. Free tier gives you 25,000 requests per day.

## What You Get

Every API response includes:

| **Data** | **Description** |
| --- | --- |
| Performance score | 0-100 Lighthouse score |
| Core Web Vitals | LCP, CLS, TBT lab data |
| Field data | Real Chrome user metrics (when available) |
| Opportunities | Specific optimization suggestions |
| Diagnostics | Detailed performance breakdowns |

The response combines lab data (Lighthouse synthetic tests) with field data from the Chrome User Experience Report when enough real user data exists for that URL.

**Note:** Google is [**~~discontinuing CrUX field data~~**](https://developers.google.com/speed/docs/insights/release_notes) in the PSI API. For field data, consider using the [**~~CrUX API~~**](https://developer.chrome.com/docs/crux/guides/crux-api) directly.

## Quick Start

Test any URL with a single curl command:

```bash
curl "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=https://example.com&key=YOUR_API_KEY"
```

The API returns JSON with everything Lighthouse captures. No authentication beyond the API key.

## When to Use the PSI API

**Good for:**

- Spot-checking individual URLs programmatically
- Integrating performance scores into dashboards
- CI checks on critical landing pages
- Monitoring specific URLs over time

**Limitations:**

- Single URL per request
- Rate limited (\~240 requests per minute)
- No crawling - you must provide URLs
- Lab data only for new/low-traffic URLs

## API vs CLI vs Unlighthouse

| **Feature** | **PSI API** | **Lighthouse CLI** | **Unlighthouse** |
| --- | --- | --- | --- |
| URLs per request | 1 | 1 | Entire site |
| Rate limit | \~240/min | None | None |
| Infrastructure | Google servers | Your machine | Your machine |
| Cost | Free (25k/day) | Free | Free CLI |
| Field data | Yes | No | No |
| URL discovery | Manual | Manual | Automatic crawl |

The PSI API is useful when you need field data or want to avoid running Lighthouse locally. For site-wide testing, the single-URL limitation becomes impractical.

## How It Works

PSI runs Lighthouse on Google's servers from several data centers (including Oregon, South Carolina, Netherlands, and Taiwan). PSI automatically chooses the location based on your IP, which can affect score consistency for sites without a CDN.

- **Mobile tests** simulate a Moto G4 on a slow 4G connection with CPU throttling ([**~~source~~**](https://developers.google.com/speed/docs/insights/v5/about))
- **Desktop tests** run on a fast wired connection with no throttling
- **Lighthouse version:** Currently uses Lighthouse 13.0 - PWA category removed ([**~~release notes~~**](https://developers.google.com/speed/docs/insights/release_notes))

Scores can [**~~vary ±5 points~~**](https://developers.google.com/web/tools/lighthouse/variability) between runs due to network conditions and server load. For accurate monitoring, run multiple tests and use the median.

## Response Structure

Key paths in the JSON response:

```text
lighthouseResult.categories.performance.score → 0-1 (multiply by 100)
lighthouseResult.audits['largest-contentful-paint'].numericValue → LCP in ms
lighthouseResult.audits['cumulative-layout-shift'].numericValue → CLS score
lighthouseResult.audits['total-blocking-time'].numericValue → TBT in ms
loadingExperience.metrics → Field data (real users)
originLoadingExperience.metrics → Origin-level field data
```

The `**loadingExperience**` object contains real user metrics from CrUX. If the URL doesn't have enough traffic, this will be empty and you'll only get lab data.

## Request Parameters

| **Parameter** | **Required** | **Description** |
| --- | --- | --- |
| `**url**` | Yes | URL to analyze |
| `**key**` | Yes | Your API key |
| `**strategy**` | No | `**desktop**` (default) or `**mobile**` |
| `**category**` | No | `**performance**`, `**accessibility**`, `**seo**`, `**best-practices**` (filter to reduce response size) |
| `**locale**` | No | Locale for the report (e.g., `**en_US**`) |

Request multiple categories by repeating the parameter:

```bash
curl "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=https://example.com&key=YOUR_KEY&category=performance&category=accessibility"
```

**Tip:** Full responses can be large (up to several MBs) as they include the complete Lighthouse JSON. [**~~Filtering by category~~**](https://developers.google.com/speed/docs/insights/v5/reference/pagespeedapi/runpagespeed#parameters) reduces response size significantly.

For origin-level CrUX data instead of URL-specific, use the [`**origin:**`**~~ prefix~~**](https://developers.google.com/speed/docs/insights/v5/get-started):

```bash
curl "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=origin:https://example.com&key=YOUR_KEY"
```

## Getting Started

1. **[**~~Get your API key~~**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/get-api-key)**: 2-minute setup in Google Cloud Console
2. **Choose your language**: [**~~Node.js~~**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/node-example) or [**~~Python~~**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/python-example)
3. **Scale up**: [**~~Bulk testing guide~~**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/bulk-testing)
4. **Handle limits**: [**~~Rate limit strategies~~**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/rate-limits)

## Skip the Complexity

Testing URLs one at a time doesn't scale. Building queue systems, handling rate limits, and managing retries adds complexity that isn't your core product.

Unlighthouse crawls your entire site and runs Lighthouse on every page automatically. No API keys, no rate limits, no queue management.

```bash
npx unlighthouse --site https://your-site.com
```

For historical tracking and scheduled scans, [**~~Unlighthouse Cloud~~**](https://unlighthouse.dev/cloud) handles everything.

[Try Unlighthouse Cloud](https://unlighthouse.dev/)

### **Related **

[**Get API Key**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/get-api-key) [**Node.js Example**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/node-example) [**Python Example**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/python-example) [**Bulk Testing Guide**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/bulk-testing) [**Rate Limits**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/rate-limits) [**PageSpeed Insights vs Unlighthouse**](https://unlighthouse.dev/tools/pagespeed-insights-performance) [**JSON Size Analyzer**](https://unlighthouse.dev/tools/json-size) [**PSI vs Lighthouse Comparison**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-vs-lighthouse)

[**Troubleshooting** Fix common Lighthouse CI issues: Chrome launch failures, score variance, shallow clone errors, upload problems, and more.](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/troubleshooting) [**Get API Key** Step-by-step guide to getting a free PageSpeed Insights API key from Google Cloud Console. Setup takes 2 minutes.](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/get-api-key)

**On this page **

- [What You Get](#what-you-get)
- [Quick Start](#quick-start)
- [When to Use the PSI API](#when-to-use-the-psi-api)
- [API vs CLI vs Unlighthouse](#api-vs-cli-vs-unlighthouse)
- [How It Works](#how-it-works)
- [Response Structure](#response-structure)
- [Request Parameters](#request-parameters)
- [Getting Started](#getting-started)
- [Skip the Complexity](#skip-the-complexity)

---

- **Page:** Lighthouse Accessibility Audit Guide · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/accessibility
- **Description:** Master web accessibility with Lighthouse. Learn how accessibility audits work, why they matter for users and SEO, and how to fix common issues.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Lighthouse Accessibility Audit Guide**

Master web accessibility with Lighthouse. Learn how accessibility audits work, why they matter for users and SEO, and how to fix common issues.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)9 min read Published **Jan 18, 2025**

Web accessibility determines whether people with disabilities can use your site. This includes users who are blind, deaf, have motor impairments, cognitive disabilities, or temporary limitations like a broken arm.

Lighthouse tests accessibility using [**~~axe-core~~**](https://github.com/dequelabs/axe-core), the industry-standard accessibility testing engine. Each audit is binary: pass or fail. Unlike performance metrics with thresholds, accessibility either works for users or it does not.

The overall accessibility score represents the percentage of passed audits. A score of 85 means 85% of applicable audits passed.

## Why accessibility matters

### Real users depend on it

Over [**~~1 billion people worldwide live with disabilities~~**](https://www.who.int/news-room/fact-sheets/detail/disability-and-health). In the US, [**~~26% of adults have some type of disability~~**](https://www.cdc.gov/disability-and-health/articles-documents/disability-impacts-all-of-us-infographic.html). This is a significant portion of your potential audience.

How users interact with your site:

- **Screen reader users** navigate by headings, links, and landmarks. If your heading hierarchy skips from h1 to h4, they lose context. If links say "click here" without context, they have no idea where they lead.
- **Keyboard-only users** tab through interactive elements. If a button cannot receive focus or a modal traps them, your site becomes unusable.
- **Low-vision users** rely on sufficient color contrast. Light gray text on white backgrounds is invisible to them.
- **Motor-impaired users** may use voice control or switches. Tiny touch targets and timed interactions create barriers.

Accessibility failures do not just inconvenience people. They lock them out.

### Legal requirements

Web accessibility is increasingly mandated by law:

| **Region** | **Law** | **Requirement** |
| --- | --- | --- |
| United States | ADA, Section 508 | Public accommodations must be accessible |
| European Union | European Accessibility Act | Digital services must meet WCAG 2.1 AA by 2025 |
| United Kingdom | Equality Act 2010 | Service providers must make reasonable adjustments |
| Canada | AODA | Ontarian organizations must meet WCAG 2.0 AA |
| Australia | DDA | Discrimination includes inaccessible websites |

[**~~The number of website accessibility lawsuits remains high, with thousands filed annually in federal court~~**](https://www.w3.org/WAI/business-case/). Plaintiffs typically target violations detectable by automated tools; these are the same issues Lighthouse flags.

### SEO overlap: The "proxy signal" effect

Google has stated that accessibility scores are an *indirect* ranking factor. Accessibility features act as "proxy signals" for User Experience (UX) and content quality, which *are* ranking factors.

| **Accessibility Feature** | **SEO Signal Proxy** | **Business Impact** |
| --- | --- | --- |
| **Headings (H1-H6)** | **Passage Ranking** | Helps Google index specific answers within long content for Featured Snippets. |
| **Link Names** | **Internal Link Equity** | Descriptive anchors pass topical authority to linked pages, boosting their ranking potential. |
| **Alt Text** | **Visual Search** | Powers Google Images and Google Lens, opening new acquisition channels. |
| **Captions/Transcripts** | **Video Indexing** | Makes video content searchable and indexable, capturing long-tail traffic. |

#### **Future proofing: mobile-first & AI**

As search evolves towards AI-driven answers (SGE) and strict Mobile-First Indexing, semantic structure becomes critical. LLMs and crawlers rely on the Accessibility Tree to understand content hierarchy. If your content is hidden from screen readers (e.g., inaccessible accordions), search engines may devalue or ignore it.

## How Lighthouse scores accessibility

Lighthouse runs axe-core against your page and evaluates dozens of rules. Each applicable rule either passes or fails. The score formula:

```text
Score = (Passed Audits / Total Applicable Audits) * 100
```

What you need to know:

- **Binary results**: Each audit is pass/fail. There is no "partial credit."
- **Weighted scoring**: Some audits carry more weight based on user impact.
- **Not applicable**: If an audit does not apply (no images on page = no image-alt check), it does not affect your score.
- **Automated limitations**: Lighthouse catches 30-50% of accessibility issues. Manual testing is essential.

A perfect 100 does not mean your site is fully accessible. It means you passed all automated checks. Screen reader testing, keyboard navigation testing, and usability testing with disabled users reveal issues automation misses.

## Common accessibility issues

These are the most frequently failing audits across websites:

### Names and labels

| **Issue** | **Impact** | **Fix Complexity** |
| --- | --- | --- |
| [**~~Missing image alt text~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/image-alt) | High | Low |
| [**~~Links without discernible names~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/link-name) | High | Low |
| [**~~Buttons without accessible names~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/button-name) | High | Low |
| [**~~Form inputs without labels~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/label) | High | Low |
| [**~~Frame/iframe missing title~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/frame-title) | Medium | Low |

### ARIA issues

| **Issue** | **Impact** | **Fix Complexity** |
| --- | --- | --- |
| Invalid ARIA roles | High | Medium |
| [**~~Missing required ARIA attributes~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/aria-required-attr) | High | Medium |
| Invalid ARIA attribute values | High | Medium |
| ARIA hidden on body | Critical | Low |
| Duplicate ARIA IDs | High | Medium |

### Color and contrast

| **Issue** | **Impact** | **Fix Complexity** |
| --- | --- | --- |
| [**~~Insufficient color contrast~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/color-contrast) | High | Medium |
| Links not distinguishable from text | Medium | Low |

### Document structure

| **Issue** | **Impact** | **Fix Complexity** |
| --- | --- | --- |
| [**~~Missing document title~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/document-title) | High | Low |
| [**~~Missing HTML lang attribute~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/html-has-lang) | High | Low |
| Invalid lang attribute | Medium | Low |
| [**~~Skipped heading levels~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/heading-order) | Medium | Low |
| Empty headings | Medium | Low |

### Navigation

| **Issue** | **Impact** | **Fix Complexity** |
| --- | --- | --- |
| [**~~No skip link or landmark~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/bypass) | Medium | Low |
| [**~~Tabindex greater than 0~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/tabindex) | Medium | Low |
| Duplicate access keys | Low | Low |

### Tables

| **Issue** | **Impact** | **Fix Complexity** |
| --- | --- | --- |
| Table cells missing headers | High | Medium |
| Invalid th scope | Medium | Medium |

> [**~~Diagnose your specific issue~~**](https://unlighthouse.dev/learn-lighthouse/accessibility#common-accessibility-issues)

## How to test accessibility

### Lighthouse (automated)

Run Lighthouse in Chrome DevTools:

1. Open DevTools (F12)
2. Go to **Lighthouse** tab
3. Check **Accessibility** category
4. Click **Analyze page load**

Review the failing audits. Each includes the failing elements and a link to documentation.

### Chrome DevTools accessibility panel

For deeper inspection:

1. Open DevTools → **Elements** tab
2. Select an element
3. View **Accessibility** pane in sidebar
4. Check computed accessible name, role, and properties

The accessibility tree shows how assistive technologies interpret your page. If an element is missing from this tree, screen readers cannot find it.

### axe DevTools extension

Install [**~~axe DevTools~~**](https://www.deque.com/axe/devtools/) for more detailed testing than Lighthouse alone. It provides:

- Intelligent guided tests for complex issues
- Best practice violations beyond WCAG
- Issue grouping by component

### Screen reader testing

Automated tools catch syntax issues. Screen reader testing reveals usability issues.

| **Screen Reader** | **Platform** | **Cost** |
| --- | --- | --- |
| NVDA | Windows | Free |
| JAWS | Windows | Licensed |
| VoiceOver | macOS/iOS | Built-in |
| TalkBack | Android | Built-in |

Basic screen reader test:

1. Close your eyes or turn off the monitor
2. Navigate using only keyboard
3. Can you understand the page structure?
4. Can you complete key tasks?

### Keyboard testing

Tab through your page:

- Can you reach all interactive elements?
- Is focus visible at all times?
- Can you operate all controls (buttons, menus, forms)?
- Can you escape from modals?
- Is tab order logical?

If any answer is no, users with motor impairments cannot use that feature.

## Framework considerations

Modern JavaScript frameworks require extra attention for accessibility:

**Client-side routing**: When navigation happens without page reload, screen readers may not announce the new content. Manage focus on route change.

**Dynamic content**: Content added via JavaScript needs appropriate ARIA live regions to announce changes.

**Component libraries**: Third-party UI libraries vary in accessibility quality. Audit them before adoption.

**Virtual DOM**: Framework abstractions can obscure accessibility issues. The rendered HTML is what matters.

## Test your entire site

Checking accessibility page-by-page misses patterns. Your marketing pages might pass while app screens fail. Product pages might be accessible while the checkout flow is not.

Different templates have different issues. An author creating content might leave out alt text. A developer building components might forget ARIA labels.

[**~~Unlighthouse~~**](https://unlighthouse.dev/) scans your entire site and surfaces accessibility scores for every page. You will see which templates have issues, which pages are outliers, and whether fixes work at scale.

The CLI is free and runs locally. Cloud adds scheduled monitoring to catch regressions before users report them.

### **Related **

[**Core Web Vitals Guide**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) [**SEO Guide**](https://unlighthouse.dev/learn-lighthouse/seo) [**Best Practices Guide**](https://unlighthouse.dev/learn-lighthouse/best-practices) [**Lighthouse Report Viewer**](https://unlighthouse.dev/tools/lighthouse-report-viewer) [**Lighthouse Scoring Calculator**](https://unlighthouse.dev/tools/lighthouse-score-calculator) [**CLS Guide**](https://unlighthouse.dev/learn-lighthouse/cls)

[**PSI vs Lighthouse** Why your Lighthouse score differs from PageSpeed Insights. Understand lab vs field data, scoring differences, and when to use each tool.](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-vs-lighthouse) [**aria-hidden-focus** Learn how to fix aria-hidden-focus issues in Lighthouse accessibility audits](https://unlighthouse.dev/learn-lighthouse/accessibility/aria-hidden-focus)

**On this page **

- [Why accessibility matters](#why-accessibility-matters)
- [How Lighthouse scores accessibility](#how-lighthouse-scores-accessibility)
- [Common accessibility issues](#common-accessibility-issues)
- [How to test accessibility](#how-to-test-accessibility)
- [Framework considerations](#framework-considerations)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Lighthouse SEO Audit: All 8 Checks Explained &amp; How to Fix · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/seo
- **Description:** Pass every Lighthouse SEO audit. Crawlability, canonical, meta description, robots.txt, hreflang, status codes — each check explained with fixes and examples.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Lighthouse SEO Audit: All 8 Checks Explained & How to Fix**

Pass every Lighthouse SEO audit. Crawlability, canonical, meta description, robots.txt, hreflang, status codes — each check explained with fixes and examples.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)6 min read Published **Jan 18, 2025**

**Lighthouse runs 8 technical SEO checks: viewport meta tag, document title, meta description, HTTP status code, link text, crawlable links, robots.txt validity, and hreflang.** Each audit is pass/fail. A single failure drops your SEO score significantly. This guide covers every check and how to fix it.

Lighthouse SEO audits check whether search engines can find, crawl, and understand your pages. Core Web Vitals measure user experience; SEO audits are binary pass-or-fail checks.

**Important distinction:** [**~~Google doesn't use Lighthouse scores for rankings~~**](https://developers.google.com/search/docs/appearance/page-experience#lighthouse). John Mueller confirmed they use Core Web Vitals data separately from real users (CrUX), not lab scores. Lighthouse SEO audits are diagnostic tools - they help you find problems, but the score itself isn't a ranking factor.

A page can score 100 on Performance yet be invisible to Google because of a single misconfigured robots directive.

## What Lighthouse SEO Measures

Lighthouse SEO focuses on technical SEO fundamentals - the stuff that makes or breaks whether your content even enters the index. It doesn't evaluate content quality, keyword optimization, or backlinks. Those matter, but they're meaningless if crawlers can't access your pages.

**SEO Score Weight:** The SEO category is equally weighted across all passing audits. One failure drops your score significantly.

## Why SEO Audits Matter

### Crawlability = Visibility

Google can't rank what it can't see. A `**noindex**` directive, broken canonical, or malformed robots.txt removes your page from search entirely. No amount of great content fixes that.

[**~~Google's SEO documentation~~**](https://developers.google.com/search/docs/fundamentals/seo-starter-guide) emphasizes that technical SEO is foundational. Technical issues often prevent pages from being indexed or ranking properly - fix those before worrying about content strategy.

Since [**~~July 5, 2024, mobile-first indexing is 100% universal~~**](https://developers.google.com/search/docs/crawling-indexing/mobile/mobile-sites-mobile-first-indexing) - Google only uses the smartphone crawler. If your mobile version has less content or different robots directives than desktop, that's what gets indexed.

### Indexability Problems are Silent

The frustrating part: you won't know something's wrong. Your site loads fine for users. Analytics looks normal (for the traffic you do get). But Google's crawler sees a brick wall.

Lighthouse catches these invisible issues before they cost you months of lost rankings.

### Compound Effects

One bad canonical implementation affects every page using that template. One misconfigured hreflang breaks international SEO across your entire site. Technical SEO issues scale with your content.

## All SEO Audits

Lighthouse runs 8 SEO audits. Each is pass/fail - no partial scores.

| **Audit** | **What It Checks** | **Why It Matters** |
| --- | --- | --- |
| [**~~Page isn't blocked from indexing~~**](https://unlighthouse.dev/learn-lighthouse/seo/is-crawlable) | `**noindex**` directives, robots.txt blocking | Blocked pages can't appear in search results |
| [**~~Document has a valid ~~**`**rel=canonical**`](https://unlighthouse.dev/learn-lighthouse/seo/canonical) | Canonical URL validity, conflicts | Invalid canonicals confuse Google about the "real" URL |
| [**~~Document has a meta description~~**](https://unlighthouse.dev/learn-lighthouse/seo/meta-description) | Meta description presence | Missing descriptions hurt click-through rates |
| [**~~Document has a valid ~~**`**hreflang**`](https://unlighthouse.dev/learn-lighthouse/seo/hreflang) | Language/region alternate links | Invalid hreflang breaks international targeting |
| [**~~Page has successful HTTP status code~~**](https://unlighthouse.dev/learn-lighthouse/seo/http-status-code) | HTTP 2xx response | 4xx/5xx errors prevent indexing |
| [**~~Links are crawlable~~**](https://unlighthouse.dev/learn-lighthouse/seo/crawlable-anchors) | Anchor href validity | Uncrawlable links block PageRank flow |
| [**~~Links have descriptive text~~**](https://unlighthouse.dev/learn-lighthouse/seo/link-text) | Link anchor text quality | Generic text ("click here") hurts SEO signals |
| [**~~robots.txt is valid~~**](https://unlighthouse.dev/learn-lighthouse/seo/robots-txt) | robots.txt syntax | Malformed robots.txt confuses all crawlers |

### High Priority: Blocking Issues

These audits check whether your page can be indexed at all:

**Page isn't blocked from indexing**, Checks for `**noindex**` in meta tags, X-Robots-Tag headers, or robots.txt disallow rules. Failure means Google won't index the page. Note: [**~~noindex still wastes crawl budget~~**](https://developers.google.com/search/blog/2024/12/crawling-december-resources), Google crawls the page before seeing the tag.

**Page has successful HTTP status code**: Checks for 4xx or 5xx responses. Pages returning errors aren't indexed.

**robots.txt is valid**: Parses your robots.txt for syntax errors. A malformed file might accidentally block your entire site.

### Medium Priority: Ranking Signals

These affect how well your page ranks and appears in results:

**Document has a valid rel=canonical**: Checks for conflicting canonicals, invalid URLs, or relative paths. Wrong canonicals can consolidate ranking to the wrong page.

**Document has a meta description**, Checks presence and content. Missing descriptions mean Google auto-generates snippets, often poorly.

**Links have descriptive text**: Flags generic anchor text like "click here" or "read more." Descriptive text helps Google understand link context.

### Lower Priority: Edge Cases

These matter for specific use cases:

**Document has a valid hreflang**: Only relevant for multi-language sites. Checks for valid language codes and fully-qualified URLs.

**Links are crawlable**: Checks for `**javascript:void(0)**`, empty hrefs, or invalid URLs. Impacts PageRank flow and content discovery.

## How to Measure SEO

### Lighthouse (Per-Page)

Run Lighthouse in Chrome DevTools or via CLI:

```bash
lighthouse https://example.com --only-categories=seo
```

Check the SEO section for failing audits. Click each for specific elements causing failures.

### PageSpeed Insights

Enter your URL at [**~~PageSpeed Insights~~**](https://pagespeed.web.dev/). The SEO section shows both lab results and any field data issues.

### Google Search Console

For production sites, Search Console is the authority:

- **Coverage report** shows indexing status
- **Core Web Vitals** shows real user data
- **URL Inspection** tests specific pages

### Manual Crawler Checks

Test how Googlebot sees your page:

```bash
curl -A "Googlebot" https://example.com/
```

Check response headers for X-Robots-Tag:

```bash
curl -I https://example.com/ | grep -i x-robots
```

## Common SEO Issues by Template Type

Different page types have different failure patterns:

| **Template** | **Common Issues** | **Quick Check** |
| --- | --- | --- |
| **Homepage** | Missing meta description, incorrect canonical | Usually fine |
| **Blog posts** | No canonical, generic link text | Check CMS output |
| **Product pages** | Blocked by robots.txt, 404s for variants | Test URL patterns |
| **Category pages** | Paginated canonical issues, duplicate content | Check pagination |
| **Search results** | Should be noindexed, but often aren't | Verify intentional |
| **User profiles** | Accidental noindex, thin content | Often should be blocked |

## Fixing SEO Issues

Most SEO failures have straightforward fixes:

1. **Identify the scope**: Is it one page or a template affecting thousands?
2. **Check the source**: Is the issue in HTML, headers, or robots.txt?
3. **Fix at the right level**: Template fix vs. per-page override
4. **Verify the fix**: Re-run Lighthouse, check Search Console

→ [**~~See all SEO issues and fixes~~**](https://unlighthouse.dev/learn-lighthouse/seo#all-seo-audits)

## Test Your Entire Site

SEO issues love to hide. Your homepage passes while 500 blog posts have broken canonicals. Your main pages are fine but a template change silently added `**noindex**` to your product catalog.

Testing one URL at a time catches one problem at a time.

[**~~Unlighthouse~~**](https://unlighthouse.dev/) crawls your entire site and runs SEO audits on every page. You'll see exactly which pages fail each audit, which templates are misconfigured, and whether your fixes work at scale.

The CLI is free and runs locally. Cloud adds scheduled monitoring to catch regressions - like when a deploy accidentally breaks your robots.txt.

### **Related **

[**Core Web Vitals Overview**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) [**Bulk Lighthouse Testing**](https://unlighthouse.dev/learn-lighthouse/bulk-lighthouse-testing) [**Best Practices Guide**](https://unlighthouse.dev/learn-lighthouse/best-practices) [**Accessibility Guide**](https://unlighthouse.dev/learn-lighthouse/accessibility) [**Bulk PageSpeed Test**](https://unlighthouse.dev/tools/bulk-pagespeed) [**Lighthouse Scoring Calculator**](https://unlighthouse.dev/tools/lighthouse-score-calculator)

[**Troubleshooting** Fix common issues when running Lighthouse with Playwright: port conflicts, authentication problems, flaky scores, and Chrome version mismatches.](https://unlighthouse.dev/learn-lighthouse/playwright/troubleshooting) [**Canonical URL** Resolve canonical tag errors that cause duplicate content issues and diluted page authority. Learn to implement rel=canonical correctly.](https://unlighthouse.dev/learn-lighthouse/seo/canonical)

**On this page **

- [What Lighthouse SEO Measures](#what-lighthouse-seo-measures)
- [Why SEO Audits Matter](#why-seo-audits-matter)
- [All SEO Audits](#all-seo-audits)
- [How to Measure SEO](#how-to-measure-seo)
- [Common SEO Issues by Template Type](#common-seo-issues-by-template-type)
- [Fixing SEO Issues](#fixing-seo-issues)
- [Test Your Entire Site](#test-your-entire-site)

---

- **Page:** Unlighthouse CLI - Site-Wide Lighthouse · Unlighthouse
- **Source:** https://unlighthouse.dev/guide/getting-started/installation
- **Description:** Install and run Unlighthouse CLI to scan your entire website with Lighthouse. npm, pnpm, and yarn installation options.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Getting Started**

# **Unlighthouse CLI - Site-Wide Lighthouse**

[Copy for LLMs](https://unlighthouse.dev/guide/getting-started/installation.md)

Stop checking pages one at a time. Run a single command and get Lighthouse scores for your entire site in minutes.

```bash
npx unlighthouse --site example.com
```

> Generate an Agent Skill for this package using [**~~skilld~~**](https://github.com/harlan-zw/skilld):
>
> ```bash
> npx skilld add unlighthouse
> ```

That's it. Unlighthouse will crawl your site, find every page, run Lighthouse on each one, and open a dashboard where you can watch results stream in live.

New to Lighthouse? Check the [**~~Core Web Vitals glossary~~**](https://unlighthouse.dev/glossary) for what [**~~LCP~~**](https://unlighthouse.dev/glossary/lcp), [**~~CLS~~**](https://unlighthouse.dev/glossary/cls), and [**~~INP~~**](https://unlighthouse.dev/glossary/inp) actually mean.

## Quick Start

Pick your package manager:

```bash
npx unlighthouse --site https://mysite.com
```

A browser window opens automatically showing your scan progress. Results appear as each page completes—no waiting for the full scan to finish.

### What Happens Behind the Scenes

1. **Discovery** — Unlighthouse reads your sitemap and crawls internal links to find every page
2. **Parallel scanning** — Multiple Chrome instances run Lighthouse audits simultaneously
3. **Live results** — Scores stream to your dashboard as each page completes
4. **Smart sampling** — Similar pages (like blog posts) are sampled to avoid redundant scans

### Requirements

- **Node.js 22.18+**
- **Chrome** — Uses your system Chrome. If missing, downloads Chromium automatically.

### Install Globally (Optional)

If you scan sites frequently:

```bash
npm install -g unlighthouse
unlighthouse --site example.com
```

## Common First Scan Issues

### Nothing happening?

Add `**--debug**` to see what's going on:

```bash
npx unlighthouse --site example.com --debug
```

### WSL Users

Chrome can be tricky in WSL. If you see connection errors, check the [**~~WSL troubleshooting guide~~**](https://unlighthouse.dev/guide/guides/common-errors#connect-econnrefused-127001port).

### Slow scans?

Your first scan downloads route data and warms up Chrome. Subsequent scans use caching and are much faster.

## Configure Your Scan

Create `**unlighthouse.config.ts**` in your project root:

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  site: 'https://example.com',
  scanner: {
    samples: 3, // Run each page 3x and average (more accurate)
    throttle: true, // Simulate real network conditions
    exclude: ['/admin/*', '/api/*'], // Skip these paths
  },
})
```

Now just run `**unlighthouse**` without flags—it reads your config automatically.

See [**~~all configuration options~~**](https://unlighthouse.dev/guide/guides/config).

## What's Next?

- **[**~~CI Integration~~**](https://unlighthouse.dev/integrations/ci)** — Run scans on every deploy, fail builds on performance regressions
- **[**~~Large Sites~~**](https://unlighthouse.dev/guide/recipes/large-sites)** — Scanning thousands of pages efficiently
- **[**~~Authentication~~**](https://unlighthouse.dev/guide/guides/authentication)** — Scan pages behind login

## Get Help

- **[**~~Discord~~**](https://discord.gg/275MBUBvgP)** — Quick questions and community help
- **[**~~GitHub Issues~~**](https://github.com/harlan-zw/unlighthouse/issues)** — Bug reports and feature requests

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/1.getting-started/0.installation.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/getting-started/installation.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/1.getting-started/0.installation.md) on GitHub or provide anonymous feedback below.

### **Related **

[**CLI Integration**](https://unlighthouse.dev/integrations/cli) [**Configuration**](https://unlighthouse.dev/guide/guides/config) [**Core Web Vitals Glossary**](https://unlighthouse.dev/glossary)

[**CLI** Install and run Unlighthouse CLI to scan your entire website with Lighthouse. npm, pnpm, and yarn installation options.](https://unlighthouse.dev/guide/getting-started/unlighthouse-cli) 

**On this page **

- [Quick Start](#quick-start)
- [Common First Scan Issues](#common-first-scan-issues)
- [Configure Your Scan](#configure-your-scan)
- [What's Next?](#whats-next)
- [Get Help](#get-help)

---

- **Page:** PageSpeed Insights vs Lighthouse: What&#x27;s the difference? · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-vs-lighthouse
- **Description:** Why your Lighthouse score differs from PageSpeed Insights. Understand lab vs field data, scoring differences, and when to use each tool.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **PageSpeed Insights vs Lighthouse: What's the difference?**

Why your Lighthouse score differs from PageSpeed Insights. Understand lab vs field data, scoring differences, and when to use each tool.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)6 min read Published **Mar 4, 2026** Updated **Aug 9, 2026**

**PageSpeed Insights runs Lighthouse on Google's servers and shows CrUX field data beside the lab report. Lighthouse CLI runs locally and reports lab data only.** The two Lighthouse scores can differ because PSI and your local run use different hardware, network paths, Chrome versions, and test settings. CrUX does not change the Lighthouse score. It is a separate view of what real Chrome users experienced.

Both tools come from Google. Both give you a 0-100 performance score. Both use the same Lighthouse engine. Here is why their numbers differ, and which one to trust.

## The two tools

**Lighthouse**

Open-source auditing tool. Runs locally in Chrome DevTools, CLI, or CI. **Lab data only**: controlled, reproducible synthetic tests on your machine. You choose device emulation, throttling mode, and network conditions. No Google account needed.

```bash
npx lighthouse https://example.com --output=json
```

Currently on version 13, which [**~~removed the PWA category~~**](https://developer.chrome.com/blog/lighthouse-13-0/).

**PageSpeed Insights**

Google's web tool at [**~~pagespeed.web.dev~~**](https://pagespeed.web.dev). It runs a Lighthouse test on Google's infrastructure and, when the URL has enough traffic, shows real-user metrics from [**~~CrUX~~**](https://developer.chrome.com/docs/crux/) over a rolling 28-day window. Paste a URL and go.

Also runs Lighthouse 13. Provides an [**~~API with 25,000 free requests/day~~**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api).

https://example.com

Elements

Console

Sources

Network

Performance

Lighthouse

Application

Performance

First Contentful Paint

**1.2 s**

Largest Contentful Paint

**2.1 s**

Total Blocking Time

**120 ms**

Cumulative Layout Shift

**0.05**

Speed Index

**2.8 s**

## Key differences

|  | **Lighthouse (CLI/DevTools)** | **PageSpeed Insights** | **Edge** |
| --- | --- | --- | --- |
| **Data type** | Lab only | Lab + field (CrUX) | PSI |
| **Where it runs** | Your machine | Google servers | Lighthouse |
| **INP** | Not measured (TBT proxy) | Real field data from CrUX | PSI |
| **Throttling** | Simulated or applied (your choice) | Simulated only | Lighthouse |
| **Caching** | Cold or warm (configurable) | Always cold cache | Lighthouse |
| **Network** | Your connection (throttled) | Google's network | - |
| **Score consistency** | High (controlled) | Varies (shared infra) | Lighthouse |
| **API access** | Local only | [**~~25k free requests/day~~**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api) | PSI |
| **Site-wide** | One URL at a time | One URL at a time | - |

## Why your scores differ

Expect some variance between PSI and local Lighthouse. Even repeated runs in the same environment can move because the page, network, CPU load, and third-party responses change. Compare medians from several runs made with the same settings before treating a score change as a regression. Here is what causes larger gaps:

### Server location

PSI chooses its own test location and network path. Your local Lighthouse run starts from your machine. If your origin or CDN behaves differently for those paths, [**~~TTFB~~**](https://unlighthouse.dev/glossary/ttfb) and LCP will differ too.

Local Lighthouse connects directly from your machine, which is often on the same network as your server or using a nearby CDN edge.

### Throttling method

PSI uses simulated throttling exclusively - it runs the page at full speed then mathematically adjusts the metrics. Lighthouse CLI lets you choose between simulated and applied (real network) throttling. Applied throttling produces lower scores but more realistic results.

### Hardware differences

Google's servers have different CPU/RAM profiles than your laptop. Simulated throttling tries to normalize this, but CPU-heavy pages (lots of JavaScript parsing) score differently depending on the hardware.

### Caching state

PSI always runs a cold-cache test. Your local Lighthouse often inadvertently benefits from cached service worker responses or browser cache, especially if you've visited the page recently.

### Extensions and background processes

Chrome extensions inject scripts and CSS. Local Lighthouse in DevTools runs in a separate profile, but other browser activity still affects CPU availability. PSI has none of these contamination issues.

## Lab data vs field data

This is the most important distinction between the two tools.

**Lab Data**Lighthouse

**Your Machine**

Chrome DevTools or CLI

**Lighthouse**

Simulated or applied throttling

**Synthetic Score**

Single controlled test

**1 page load**

**Field Data**CrUX / PSI

**Real Chrome Users**

Diverse devices & networks

**CrUX Dataset**

28-day rolling window, P75

**PSI Field Metrics**

Real-world performance

**1000+ visits**

**Lab data** (Lighthouse) tests a single page load under controlled conditions. It's reproducible, fast, and catches regressions - but it represents one synthetic user, not your actual audience.

**Field data** (CrUX in PSI) aggregates real Chrome users visiting your site over a 28-day rolling window. It uses the 75th percentile (P75), catching the experience of users with slow devices and poor connections - not just the median.

|  | **Lab (Lighthouse)** | **Field (CrUX/PSI)** |
| --- | --- | --- |
| **Source** | Simulated page load | Real Chrome users |
| **Sample** | 1 test run | Thousands of visits (P75) |
| **Time window** | Point-in-time | 28-day rolling average |
| **Traffic requirement** | None | \~1,000 page loads in 28 days |
| **INP** | Not available | Yes |
| **Consistency** | High | Varies with real conditions |

A site can score 95 in Lighthouse but show "Poor" LCP in CrUX field data. This happens when real users are on slow mobile networks that lab throttling doesn't fully simulate.

## How Lighthouse scores performance

Both tools use the same scoring weights. Understanding them explains why the same page gets different numbers:

**TBT**Total Blocking Time

**30% weight **

Good ≤200msPoor >600ms

**LCP**Largest Contentful Paint** CWV **

**25% weight **

Good ≤2.5sPoor >4.0s

**CLS**Cumulative Layout Shift** CWV **

**25% weight **

Good ≤0.10Poor >0.25

**FCP**First Contentful Paint

**10% weight **

Good ≤1.8sPoor >3.0s

**SI**Speed Index

**10% weight **

Good ≤3.4sPoor >5.8s

[**~~Total Blocking Time~~**](https://unlighthouse.dev/glossary/tbt) carries the largest weight at 30%, while [**~~Speed Index~~**](https://unlighthouse.dev/glossary/speed-index) contributes 10%. Pages with heavy JavaScript often show the largest score differences because CPU speed changes TBT. Slow visual progress can move Speed Index even when the final LCP element is unchanged.

## INP: the biggest gap between PSI and Lighthouse

Interaction to Next Paint (INP) replaced First Input Delay as a Core Web Vital in March 2024. It measures responsiveness across the **entire page lifecycle**: every tap, click, and keypress.

**Lighthouse cannot measure INP.** It uses Total Blocking Time (TBT) as a lab proxy, but TBT only measures main-thread blockage **during initial load**. A page can achieve 0ms TBT and still fail INP in the field because JavaScript freezes the page when users interact after load. [**~~Read more about the INP vs TBT relationship~~**](https://web.dev/articles/tbt#how-tbt-relates-to-inp).

PSI shows real INP field data from CrUX. This is the single biggest reason to check PSI even if you primarily use Lighthouse CLI - it's the only place you'll see actual interaction responsiveness without adding your own [**~~Real User Monitoring~~**](https://web.dev/articles/vitals-field-measurement-best-practices).

## When to use which

| **Scenario** | **Use** |
| --- | --- |
| **Development** | Lighthouse CLI - fast feedback, consistent scores, CI integration |
| **Production monitoring** | PSI / CrUX - real user data, INP, field metrics |
| **CI/CD checks** | [**~~Lighthouse CI~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci) - automated regression detection |
| **Debugging score drops** | Lighthouse CLI - isolate variables, test specific throttling |
| **Checking INP** | PSI - only source of real INP data without RUM |
| **Site-wide audits** | Unlighthouse - crawl every page, spot patterns across routes |
| **Stakeholder reports** | PSI - field data carries more weight, reflects real users |

## How Unlighthouse helps

Both Lighthouse and PSI test one URL at a time. Performance issues rarely affect one page - a slow font, a heavy third-party script, or a layout shift pattern can be site-wide.

Unlighthouse crawls your entire site and runs Lighthouse on every discovered page. Instead of spot-checking your homepage, you catch the `**/checkout**` page with a 3.2s LCP or the `**/blog**` layout causing CLS on 40 posts.

```bash
npx unlighthouse --site https://your-site.com
```

Combine with PSI for field data on your critical pages, and Lighthouse CI for automated regression checks in your pipeline. Each tool fills a different gap.

[Try Unlighthouse](https://unlighthouse.dev/)

## FAQ

### Why is my PageSpeed Insights score different from Lighthouse?

PSI runs Lighthouse on Google's infrastructure with different hardware, network conditions, and settings from your local machine. CrUX appears separately and does not affect the lab score. Run each setup several times and compare medians under consistent settings.

### Which score should I trust: PSI or Lighthouse?

For production sites with enough traffic: trust PSI's field data. It reflects what real users experience. For development and debugging: trust local Lighthouse, where you control variables and get consistent results.

### Does PageSpeed Insights use Lighthouse?

Yes. PSI runs Lighthouse on Google's servers and adds CrUX field data on top. The lab scores in PSI come from the same Lighthouse engine you run locally.

### Why does my score change every time I run PageSpeed Insights?

Network conditions, server load, page content, and third-party responses vary between runs. Run at least three tests and compare the median. Keep the test URL and device settings unchanged.

### What is field data in PageSpeed Insights?

Field data comes from the Chrome User Experience Report (CrUX): real metrics from eligible Chrome users over the previous 28 days, reported at the 75th percentile. Google does not publish a fixed traffic threshold for URL-level data, so low-traffic URLs may show only origin data or no field data.

### Should I optimize for Lighthouse or PageSpeed Insights?

Optimize for real users. Use Lighthouse to diagnose and fix lab issues during development. Use PSI field data to verify improvements reach your actual audience. Don't chase a perfect 100 - [**~~diminishing returns hit hard above 90~~**](https://developer.chrome.com/docs/lighthouse/performance/performance-scoring).

### Can I get a 100 on PageSpeed Insights?

In lab data, yes. But field data may show issues because real users have diverse devices, network conditions, and geographic locations that lab tests can't replicate. A 100 lab score with "Poor" field CWV means your real users are still suffering.

### **Related **

[**PageSpeed Performance Tool**](https://unlighthouse.dev/tools/pagespeed-insights-performance) [**Lighthouse Report Viewer**](https://unlighthouse.dev/tools/lighthouse-report-viewer) [**Score Calculator**](https://unlighthouse.dev/tools/lighthouse-score-calculator) [**Core Web Vitals Guide**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) [**PSI API Guide**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api) [**LCP Definition**](https://unlighthouse.dev/glossary/lcp)

[**Bulk lighthouse testing** Run Lighthouse on your entire site with Unlighthouse. Limit pages with --maxRoutes, filter by URL pattern, and automate bulk audits.](https://unlighthouse.dev/learn-lighthouse/bulk-lighthouse-testing) [**Accessibility** Master web accessibility with Lighthouse. Learn how accessibility audits work, why they matter for users and SEO, and how to fix common issues.](https://unlighthouse.dev/learn-lighthouse/accessibility)

**On this page **

- [The two tools](#the-two-tools)
- [Key differences](#key-differences)
- [Why your scores differ](#why-your-scores-differ)
- [Lab data vs field data](#lab-data-vs-field-data)
- [How Lighthouse scores performance](#how-lighthouse-scores-performance)
- [INP: the biggest gap between PSI and Lighthouse](#inp-the-biggest-gap-between-psi-and-lighthouse)
- [When to use which](#when-to-use-which)
- [How Unlighthouse helps](#how-unlighthouse-helps)
- [FAQ](#faq)

---

- **Page:** Lighthouse with Playwright: Performance Testing Guide · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/playwright
- **Description:** Run Google Lighthouse audits with Playwright for automated performance, accessibility, and SEO testing. Complete setup guide with code examples.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Lighthouse with Playwright: Performance Testing Guide**

Run Google Lighthouse audits with Playwright for automated performance, accessibility, and SEO testing. Complete setup guide with code examples.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw) Published **Jan 27, 2026** Updated **Aug 9, 2026**

**How do you run Lighthouse with Playwright?** Launch Chromium with `**--remote-debugging-port=9222**`, navigate to the target URL, then pass that port to the `**lighthouse**` npm package. Lighthouse connects via CDP, runs audits, and returns scores plus a full HTML report you can attach to Playwright test results.

Run Lighthouse audits programmatically using [**~~Playwright~~**](https://playwright.dev). This guide uses the Lighthouse Node API directly, so you control the browser, audit settings, and report output.

**Requirements**: [**~~Node.js~~**](https://nodejs.org) 22.19 or newer, Playwright installed. Lighthouse connects via Chrome DevTools Protocol on a remote debugging port.

## What You'll Build

By the end of this guide, you'll have:

- Lighthouse running inside your Playwright test suite
- Performance, accessibility, SEO, and best practices scores
- HTML reports generated automatically
- A foundation for CI/CD integration

## How It Works

Playwright launches Chromium with a remote debugging port. Lighthouse connects to that port and runs its audits on the page Playwright has navigated to.

```text
Playwright → launches Chrome with --remote-debugging-port=9222
Lighthouse → connects to port 9222 → runs audits → returns results
```

This is the same approach the `**playwright-lighthouse**` [**~~npm~~**](https://npmjs.com) package uses internally, but doing it directly gives you more control and fewer dependencies.

## Setup

Install the required packages:

```bash
npm install -D @playwright/test lighthouse
npx playwright install chromium
```

## Basic Integration

Here's a complete working example:

```js
import { writeFileSync } from 'node:fs'
import { chromium } from '@playwright/test'
import lighthouse from 'lighthouse'

const PORT = 9222

async function runLighthouseAudit(url) {
  // Launch Chrome with remote debugging enabled
  const browser = await chromium.launch({
    args: [`--remote-debugging-port=${PORT}`],
  })

  const page = await browser.newPage()
  await page.goto(url, { waitUntil: 'networkidle' })

  // Run Lighthouse audit
  const result = await lighthouse(url, {
    port: PORT,
    output: 'html',
    logLevel: 'error',
  })

  // Save HTML report
  writeFileSync('lighthouse-report.html', result.report)

  // Extract scores
  const { categories } = result.lhr
  console.log('Performance:', Math.round(categories.performance.score * 100))
  console.log('Accessibility:', Math.round(categories.accessibility.score * 100))
  console.log('Best Practices:', Math.round(categories['best-practices'].score * 100))
  console.log('SEO:', Math.round(categories.seo.score * 100))

  await browser.close()
  return result.lhr
}

runLighthouseAudit('https://example.com')
```

## Using with Playwright Test

Integrate into your existing Playwright test suite:

```js
import { chromium, expect, test } from '@playwright/test'
import lighthouse from 'lighthouse'

const PORT = 9222

test.describe('Lighthouse Audits', () => {
  test('homepage meets performance threshold', async () => {
    const browser = await chromium.launch({
      args: [`--remote-debugging-port=${PORT}`],
    })

    const page = await browser.newPage()
    await page.goto('https://example.com', { waitUntil: 'networkidle' })

    const result = await lighthouse('https://example.com', {
      port: PORT,
      logLevel: 'error',
    })

    const perfScore = result.lhr.categories.performance.score * 100

    await browser.close()

    // Assert minimum performance score
    expect(perfScore).toBeGreaterThanOrEqual(80)
  })
})
```

**Important**: Run Lighthouse tests with a single worker (`**--workers=1**`). Multiple concurrent Lighthouse audits on the same debugging port will conflict.

## Advanced: Custom Test Fixture

For a cleaner, reusable pattern, extend Playwright's `**test**` object to create a custom [**~~Fixture~~**](https://playwright.dev/docs/test-fixtures). This abstracts the setup/teardown logic.

```ts
// fixtures/lighthouse.ts
import { writeFileSync } from 'node:fs'
import { test as base, chromium } from '@playwright/test'
import lighthouse from 'lighthouse'

export const test = base.extend({
  lighthouse: async ({ page: _page }, use, testInfo) => {
    const port = 9222
    const browser = await chromium.launch({
      args: [`--remote-debugging-port=${port}`],
    })

    await use(async (url) => {
      const page = await browser.newPage()
      await page.goto(url, { waitUntil: 'networkidle' })

      const result = await lighthouse(url, { port, output: 'html', logLevel: 'error' })
      const score = result.lhr.categories.performance.score * 100

      // Attach report to Playwright test results
      const reportPath = `lighthouse-report-${testInfo.title.replace(/\s+/g, '-')}.html`
      writeFileSync(reportPath, result.report)
      await testInfo.attach('lighthouse-report', { path: reportPath, contentType: 'text/html' })

      await page.close()
      return score
    })

    await browser.close()
  }
})

export { expect } from '@playwright/test'
```

**Usage in tests:**

```ts
import { expect, test } from './fixtures/lighthouse'

test('homepage core web vitals', async ({ lighthouse }) => {
  const score = await lighthouse('https://example.com')
  expect(score).toBeGreaterThanOrEqual(90)
})
```

## Soft Assertions

Use [`**expect.soft**`](https://playwright.dev/docs/test-assertions#soft-assertions) to prevent a single metric failure from terminating the entire test execution. This is useful when auditing multiple pages or metrics.

```js
const { categories } = result.lhr

// Test continues even if performance fails
expect.soft(categories.performance.score).toBeGreaterThan(0.9)
expect.soft(categories.accessibility.score).toBeGreaterThan(0.9)
expect.soft(categories.seo.score).toBeGreaterThan(0.9)
```

## Configuration Options

Customize the audit with Lighthouse flags:

```js
const result = await lighthouse(url, {
  port: PORT,
  output: ['html', 'json'], // Multiple output formats
  logLevel: 'error',
  onlyCategories: ['performance', 'accessibility'], // Skip SEO/best-practices
  formFactor: 'desktop', // 'mobile' (default) or 'desktop'
  throttling: {
    cpuSlowdownMultiplier: 1, // Disable CPU throttling
  },
  screenEmulation: {
    disabled: true, // Use actual viewport
  },
})
```

### Common Configuration Presets

**Mobile (default):**

```js
const mobileConfig = {
  formFactor: 'mobile',
  screenEmulation: { mobile: true, width: 412, height: 823 },
  throttling: { cpuSlowdownMultiplier: 4 }
}
```

**Desktop:**

```js
const desktopConfig = {
  formFactor: 'desktop',
  screenEmulation: { mobile: false, width: 1350, height: 940 },
  throttling: { cpuSlowdownMultiplier: 1 }
}
```

## Extracting Specific Metrics

Access individual Core Web Vitals and other metrics:

```js
const { audits } = result.lhr

// Core Web Vitals
const lcp = audits['largest-contentful-paint'].numericValue // ms
const cls = audits['cumulative-layout-shift'].numericValue // score
const tbt = audits['total-blocking-time'].numericValue // ms (proxy for INP)

// Other useful metrics
const fcp = audits['first-contentful-paint'].numericValue
const speedIndex = audits['speed-index'].numericValue

console.log(`LCP: ${lcp}ms, CLS: ${cls}, TBT: ${tbt}ms`)
```

## When to Use Direct Integration vs Alternatives

| **Approach** | **Best For** | **Trade-offs** |
| --- | --- | --- |
| **Direct integration** (this guide) | Full control, minimal dependencies | More setup code |
| **playwright-lighthouse** package | Quick setup | Thin wrapper, less maintained |
| **Unlighthouse** | Site-wide audits | Automatic crawling, no per-page control |
| **Lighthouse CI** | CI/CD pipelines | Built for automation, historical tracking |

For testing individual pages in your test suite, direct integration works well. For auditing an entire site, [**~~Unlighthouse~~**](https://unlighthouse.dev/guide/getting-started/installation) crawls automatically and tests every page:

```bash
npx unlighthouse --site https://example.com
```

## Playwright vs Puppeteer for Lighthouse

Both tools drive Chromium through CDP, so either can host a Lighthouse audit. Use Playwright when the audit belongs in an existing Playwright test suite. Lighthouse's own authenticated-page documentation uses Puppeteer, which is a good fit for a standalone audit script.

| **Feature** | **Playwright** | **Puppeteer** |
| --- | --- | --- |
| Test runner | Built in (`**@playwright/test**`) | Bring your own (Jest, Mocha) |
| Auth setup | `**storageState**` and fixtures | Scripted browser profile or cookies |
| Parallel workers | Built into Playwright Test | Bring your own runner |
| TypeScript types | Included | Included |

Picking Playwright means your Lighthouse audits live alongside E2E tests, share fixtures, and run on the same CI workers:

```ts
// Playwright: Lighthouse shares the same fixture system as E2E tests
import { test } from './fixtures/lighthouse'

test('pricing page performance', async ({ lighthouse, page }) => {
  await page.goto('/pricing')
  const score = await lighthouse(page.url())
  expect(score).toBeGreaterThanOrEqual(85)
})
```

## Running Multiple Pages in Parallel

Playwright Test's worker model runs multiple audits concurrently, provided each worker uses a unique debugging port. Sharing port 9222 across workers causes `**Target closed**` errors.

```ts
// playwright.config.ts
import { defineConfig } from '@playwright/test'

export default defineConfig({
  workers: 4, // 4 parallel Lighthouse audits
  fullyParallel: true,
})
```

Generate a per-worker port inside the fixture so audits never collide:

```ts
// fixtures/lighthouse.ts
import { test as base, chromium } from '@playwright/test'
import lighthouse from 'lighthouse'

export const test = base.extend({
  lighthouse: async (_, use, testInfo) => {
    // Each worker gets a unique port
    const port = 9222 + testInfo.workerIndex

    const browser = await chromium.launch({
      args: [`--remote-debugging-port=${port}`],
    })

    await use(async (url: string) => {
      const page = await browser.newPage()
      await page.goto(url, { waitUntil: 'networkidle' })
      const result = await lighthouse(url, { port, logLevel: 'error' })
      await page.close()
      return result.lhr
    })

    await browser.close()
  },
})
```

Drive the audits from a parameterised test to fan out across pages:

```ts
import { expect, test } from './fixtures/lighthouse'

const urls = [
  '/',
  '/pricing',
  '/docs',
  '/blog',
]

for (const url of urls) {
  test(`audit ${url}`, async ({ lighthouse }) => {
    const lhr = await lighthouse(`https://example.com${url}`)
    expect(lhr.categories.performance.score).toBeGreaterThan(0.8)
  })
}
```

## Typed Results with TypeScript

The `**lighthouse**` package ships its own types. Import them to get autocomplete on categories, audits, and numeric values.

```ts
import type { Flags, Result } from 'lighthouse'
import lighthouse from 'lighthouse'

interface AuditScores {
  performance: number
  accessibility: number
  bestPractices: number
  seo: number
  lcp: number
  cls: number
  tbt: number
}

async function runTypedAudit(url: string, port: number): Promise<AuditScores> {
  const flags: Flags = {
    port,
    logLevel: 'error',
    output: 'json',
  }

  const runnerResult = await lighthouse(url, flags)
  if (!runnerResult)
    throw new Error('Lighthouse returned no result')

  const lhr: Result = runnerResult.lhr

  return {
    performance: Math.round((lhr.categories.performance.score ?? 0) * 100),
    accessibility: Math.round((lhr.categories.accessibility.score ?? 0) * 100),
    bestPractices: Math.round((lhr.categories['best-practices'].score ?? 0) * 100),
    seo: Math.round((lhr.categories.seo.score ?? 0) * 100),
    lcp: lhr.audits['largest-contentful-paint'].numericValue ?? 0,
    cls: lhr.audits['cumulative-layout-shift'].numericValue ?? 0,
    tbt: lhr.audits['total-blocking-time'].numericValue ?? 0,
  }
}
```

For custom config presets, type the config object with `**LH.Config**`:

```ts
import type { Config } from 'lighthouse'

const desktopConfig: Config = {
  extends: 'lighthouse:default',
  settings: {
    formFactor: 'desktop',
    screenEmulation: { mobile: false, width: 1350, height: 940, deviceScaleFactor: 1, disabled: false },
    throttling: { cpuSlowdownMultiplier: 1, rttMs: 40, throughputKbps: 10 * 1024 },
  },
}
```

## 2026 compatibility notes

Lighthouse 13 requires Node.js 22.19 or newer and ships as ESM. Current [**~~Playwright installation guidance~~**](https://playwright.dev/docs/intro) supports maintained Node.js 22, 24, and 26 releases. Use an ESM test project and keep Playwright's browser install in sync with the package version recorded by your lockfile.

```json
{
  "type": "module",
  "engines": {
    "node": ">=22.19.0"
  },
  "devDependencies": {
    "@playwright/test": "^1.62.0",
    "lighthouse": "^13.0.1"
  }
}
```

Lighthouse cannot measure INP in a synthetic page load because INP needs real interactions across a page visit. Keep [**~~Total Blocking Time~~**](https://unlighthouse.dev/glossary/tbt) as the lab diagnostic, then verify [**~~INP~~**](https://unlighthouse.dev/glossary/inp) with CrUX or your own real-user monitoring.

```ts
const tbt = lhr.audits['total-blocking-time']?.numericValue
console.log(`TBT: ${tbt ?? 'unavailable'}ms`)
```

Do not compare scores across a Lighthouse or Chromium upgrade as if the test environment stayed fixed. Record tool versions with each CI result, then establish a new baseline after upgrading.

## FAQ

### Can playwright-lighthouse work with Playwright Test?

Yes. The `**playwright-lighthouse**` npm package wraps the same CDP pattern shown above, exposing a `**playAudit()**` helper. Pass your Playwright `**page**` and a port:

```ts
import { test } from '@playwright/test'
import { playAudit } from 'playwright-lighthouse'

test('audit with wrapper', async ({ page }) => {
  await page.goto('https://example.com')
  await playAudit({
    page,
    port: 9222,
    thresholds: { performance: 80, accessibility: 90 },
  })
})
```

The wrapper is thinner than the direct approach, so you lose control over fixtures and worker ports. For parallel suites, prefer the fixture pattern above.

### Why use Playwright instead of puppeteer-lighthouse?

Playwright gives you a built-in test runner, `**storageState**` auth, sharding, and TypeScript-first APIs. Puppeteer-lighthouse works, but you write the test use yourself. If you already run Playwright for E2E, adding Lighthouse as a fixture reuses your existing worker configuration and CI pipeline.

```ts
// One config, both E2E and Lighthouse audits
export default defineConfig({
  projects: [
    { name: 'e2e', testMatch: /.*\.spec\.ts/ },
    { name: 'lighthouse', testMatch: /.*\.lh\.ts/, workers: 2 },
  ],
})
```

### How do I export Lighthouse results in Playwright?

[**~~Export the Lighthouse report~~**](https://unlighthouse.dev/guide/guides/generating-static-reports), then use `**testInfo.attach()**` to include HTML and JSON output in the Playwright HTML report. Attached files appear under each test result:

```ts
test('export lighthouse report', async ({ lighthouse }, testInfo) => {
  const result = await lighthouse('https://example.com')

  // Attach HTML report
  await testInfo.attach('lighthouse.html', {
    body: result.report,
    contentType: 'text/html',
  })

  // Attach JSON for downstream tooling
  await testInfo.attach('lighthouse.json', {
    body: JSON.stringify(result.lhr, null, 2),
    contentType: 'application/json',
  })
})
```

Open the JSON in the [**~~Lighthouse Report Viewer~~**](https://unlighthouse.dev/tools/lighthouse-report-viewer) to inspect audits visually without regenerating.

### Does this work with Playwright's WebKit or firefox projects?

No. Lighthouse requires Chrome DevTools Protocol, which only Chromium supports. Keep Lighthouse audits on a dedicated `**chromium**` project in `**playwright.config.ts**`, while E2E suites can still run across all three engines.

```ts
projects: [
  { name: 'chromium-lighthouse', use: { browserName: 'chromium' } },
  { name: 'webkit-e2e', use: { browserName: 'webkit' } },
  { name: 'firefox-e2e', use: { browserName: 'firefox' } },
]
```

## Common Issues

Running into problems? See [**~~Troubleshooting~~**](https://unlighthouse.dev/learn-lighthouse/playwright/troubleshooting) for solutions to:

- Port conflicts and "address already in use" errors
- Authentication state not persisting
- Flaky or inconsistent scores
- Chrome/Chromium version mismatches

## Next Steps

[Authenticated Pages](https://unlighthouse.dev/learn-lighthouse/playwright/authentication)

**Authenticated Pages**

Run Lighthouse on pages behind login.

[CI/CD Integration](https://unlighthouse.dev/learn-lighthouse/playwright/ci-cd)

**CI/CD Integration**

Automate audits in GitHub Actions.

[Troubleshooting](https://unlighthouse.dev/learn-lighthouse/playwright/troubleshooting)

**Troubleshooting**

Fix common integration issues.

### **Related **

[**Core Web Vitals Guide**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) [**Lighthouse CI**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci) [**Bulk Lighthouse Testing**](https://unlighthouse.dev/learn-lighthouse/bulk-lighthouse-testing) [**Unlighthouse CLI**](https://unlighthouse.dev/integrations/cli) [**Lighthouse Report Viewer**](https://unlighthouse.dev/tools/lighthouse-report-viewer)

[**Rate Limits** Handle PSI API quotas without breaking your integration. Rate limit detection, retry strategies, and quota monitoring.](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/rate-limits) [**Authentication** Run Lighthouse audits on pages behind login. Learn how to preserve authentication state when Lighthouse opens a new browser context.](https://unlighthouse.dev/learn-lighthouse/playwright/authentication)

**On this page **

- [What You'll Build](#what-youll-build)
- [How It Works](#how-it-works)
- [Setup](#setup)
- [Basic Integration](#basic-integration)
- [Using with Playwright Test](#using-with-playwright-test)
- [Advanced: Custom Test Fixture](#advanced-custom-test-fixture)
- [Soft Assertions](#soft-assertions)
- [Configuration Options](#configuration-options)
- [Extracting Specific Metrics](#extracting-specific-metrics)
- [When to Use Direct Integration vs Alternatives](#when-to-use-direct-integration-vs-alternatives)
- [Playwright vs Puppeteer for Lighthouse](#playwright-vs-puppeteer-for-lighthouse)
- [Running Multiple Pages in Parallel](#running-multiple-pages-in-parallel)
- [Typed Results with TypeScript](#typed-results-with-typescript)
- 2026 compatibility notes
- [FAQ](#faq)
- [Common Issues](#common-issues)
- [Next Steps](#next-steps)

---

- **Page:** Bulk lighthouse testing &amp; --maxRoutes config · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/bulk-lighthouse-testing
- **Description:** Run Lighthouse on your entire site with Unlighthouse. Limit pages with --maxRoutes, filter by URL pattern, and automate bulk audits.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Bulk lighthouse testing & --maxRoutes config**

Run Lighthouse on your entire site with Unlighthouse. Limit pages with --maxRoutes, filter by URL pattern, and automate bulk audits.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)5 min read Published **Jan 12, 2025**

## `**--maxRoutes**` CLI flag: default 200, override with one command

Use `**--maxRoutes**` to raise the per-scan page limit (default is 200):

```bash
npx unlighthouse --site https://example.com --max-routes 2000
```

The flag accepts any positive integer. Pass `**-1**` to disable the limit and scan every URL Unlighthouse discovers. This is the fix if your bulk scan is stopping at 200 pages.

## Run Lighthouse on every page, not just the homepage

Standard Lighthouse tools test one page at a time. But your site has hundreds, maybe thousands, of pages, and the [**~~2024 Web Almanac~~**](https://almanac.httparchive.org/en/2024/performance) added secondary page analysis because **homepage performance is not representative of the entire site**.

**Your homepage might score 100.** What about:

- Product pages with heavy images?
- Blog posts with embedded videos?
- Category pages with infinite scroll?
- User-generated content pages?

Each page type has different performance characteristics.

## The solution: Unlighthouse

Unlighthouse crawls your site and runs Lighthouse on every page automatically.

```bash
npx unlighthouse --site https://your-site.com
```

## How it works

1. **Crawl**: Discovers all pages from your sitemap and internal links
2. **Audit**: Runs Lighthouse on each page in parallel
3. **Report**: Interactive report sorted by worst scores

## Installation

No installation required. Use npx:

```bash
npx unlighthouse --site https://your-site.com
```

Or install globally:

```bash
npm install -g unlighthouse
unlighthouse --site https://your-site.com
```

## Configuration

Create `**unlighthouse.config.ts**`:

```ts
export default {
  site: 'https://your-site.com',
  scanner: {
    // Crawl settings
    maxRoutes: 200,
    samples: 1,
  },
  lighthouse: {
    // Lighthouse settings
    throttling: {
      cpuSlowdownMultiplier: 4,
    },
  },
}
```

## Common options

| **Option** | **Description** | **Default** |
| --- | --- | --- |
| `**--site**` | URL to scan | Required |
| `**--urls**` | Specific URLs to test | All discovered |
| `**--samples**` | Runs per URL | 1 |
| `**--throttle**` | Simulate slow connection | true |

## Filtering pages

Test specific sections:

```bash
npx unlighthouse --site https://your-site.com --urls "/blog/**"

npx unlighthouse --site https://your-site.com --exclude "/admin/**"
```

## Reading results

The report shows:

- **Score distribution**: How many pages are good/needs work/poor
- **Worst pages**: Sorted by score, fix these first
- **Issue breakdown**: Common problems across your site

## Understanding lab vs field data

Google [**~~uses field data (CrUX) for search ranking~~**](https://developers.google.com/search/docs/appearance/core-web-vitals), not lab scores from Lighthouse.

| **Aspect** | **Lab Data (Lighthouse)** | **Field Data (CrUX)** |
| --- | --- | --- |
| Source | Simulated tests | Real user visits |
| Used for ranking | No | Yes |
| Best for | Debugging issues | Measuring actual UX |
| Update frequency | Immediate | [**~~28-day rolling average~~**](https://developer.chrome.com/docs/crux/methodology) |

Lab testing with Unlighthouse helps you **find and fix issues**. Monitor field data to verify improvements reached real users.

## Lighthouse scoring method

[**~~Lighthouse performance scoring~~**](https://developer.chrome.com/docs/lighthouse/performance/performance-scoring) weights metrics differently:

| **Metric** | **Weight** |
| --- | --- |
| Total Blocking Time (TBT) | 30% |
| Largest Contentful Paint (LCP) | 25% |
| Cumulative Layout Shift (CLS) | 25% |
| First Contentful Paint (FCP) | 10% |
| Speed Index | 10% |

Scores are derived from [**~~real website performance data on HTTP Archive~~**](https://developer.chrome.com/docs/lighthouse/performance/performance-scoring):

- 0-49: Poor (red)
- 50-89: Needs Improvement (orange)
- 90-100: Good (green)

## Reducing score variability

Lighthouse scores vary between runs. Follow [**~~Google's guidance~~**](https://developers.google.com/web/tools/lighthouse/variability):

- **Run multiple times**: The median of 5 runs is twice as stable as 1 run
- **Use consistent hardware**: Don't run concurrent tests on the same machine
- **Isolate from third-parties**: External scripts add variance
- **Scale horizontally**: Run on multiple smaller instances rather than one large one

Unlighthouse defaults to running multiple samples and averaging for stable results.

## CI/CD integration

Run on every deploy to catch regressions:

```yaml
name: Lighthouse Audit
on: [push]

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Unlighthouse
        run: npx unlighthouse-ci --site ${{ env.SITE_URL }}
```

Set performance budgets to fail builds when scores drop:

```ts
// unlighthouse.config.ts
const config2 = {
  site: 'https://your-site.com',
  ci: {
    budget: {
      performance: 80,
      accessibility: 90,
    },
  },
}
```

For CI/CD automation with performance budgets, see the [**~~Lighthouse CI guide~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci) or platform-specific guides for [**~~GitHub Actions~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/github-actions) and [**~~GitLab CI~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/gitlab-ci).

## Alternatives comparison

How Unlighthouse compares to other tools:

| **Tool** | **Bulk Testing** | **Pricing** | **Notes** |
| --- | --- | --- | --- |
| **Unlighthouse** | Unlimited pages | Free (CLI) | Open source, self-hosted |
| PageSpeed Insights | 1 page/request | Free | [**~~25,000 requests/day API limit~~**](https://developers.google.com/speed/docs/insights/v5/get-started) |
| DebugBear | 10,000/mo | $99/mo | Managed service |
| Calibre | 5 sites | $150/mo | Managed service |
| SpeedCurve | Varies | $20-500/mo | RUM + synthetic |

## Current web performance stats

Context for your scores from [**~~HTTP Archive 2024~~**](https://almanac.httparchive.org/en/2024/performance):

| **Metric** | **Mobile Pass Rate** | **Desktop Pass Rate** |
| --- | --- | --- |
| Core Web Vitals (all 3) | 48% | 54% |
| LCP | 59% | 72% |
| CLS | 79% | 72% |
| INP | 74% | 97% |

If you're beating these numbers, you're ahead of most of the web.

## Best practices

1. **Test representative pages**: Don't just test the homepage
2. **Run multiple samples**: Average results for stability
3. **Test on realistic hardware**: Use CPU throttling to simulate mobile
4. **Monitor trends**: One-time audits aren't enough
5. **Fix worst pages first**: Greatest impact for least effort
6. **Validate with field data**: Lab scores don't affect ranking

## Next steps

1. Run your first scan: `**npx unlighthouse --site https://your-site.com**`
2. Fix the worst pages first
3. [**~~Set up CI/CD~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/github-actions) to catch regressions

### **Related **

[**Core Web Vitals Guide**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) [**Lighthouse CI**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci) [**LCP Finder**](https://unlighthouse.dev/tools/lcp-finder) [**CLS Debugger**](https://unlighthouse.dev/tools/cls-debugger) [**INP Analyzer**](https://unlighthouse.dev/tools/inp-analyzer) [**Bulk PageSpeed Tool**](https://unlighthouse.dev/tools/bulk-pagespeed) [**Fix LCP**](https://unlighthouse.dev/learn-lighthouse/lcp#common-lcp-issues) [**Fix CLS**](https://unlighthouse.dev/learn-lighthouse/cls#common-cls-issues) [**Fix INP**](https://unlighthouse.dev/learn-lighthouse/inp#common-inp-issues)

[**Core web vitals guide** Master Core Web Vitals - Google's page experience metrics. Learn LCP, CLS, INP thresholds, how to measure them, and fixes that improve rankings and conversions.](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) [**PSI vs Lighthouse** Why your Lighthouse score differs from PageSpeed Insights. Understand lab vs field data, scoring differences, and when to use each tool.](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-vs-lighthouse)

**On this page **

- [--maxRoutes CLI flag: default 200, override with one command](#maxroutes-cli-flag-default-200-override-with-one-command)
- [Run Lighthouse on every page, not just the homepage](#run-lighthouse-on-every-page-not-just-the-homepage)
- [The solution: Unlighthouse](#the-solution-unlighthouse)
- [How it works](#how-it-works)
- [Installation](#installation)
- [Configuration](#configuration)
- [Common options](#common-options)
- [Filtering pages](#filtering-pages)
- [Reading results](#reading-results)
- [Understanding lab vs field data](#understanding-lab-vs-field-data)
- [Lighthouse scoring method](#lighthouse-scoring-method)
- [Reducing score variability](#reducing-score-variability)
- [CI/CD integration](#cicd-integration)
- [Alternatives comparison](#alternatives-comparison)
- [Current web performance stats](#current-web-performance-stats)
- [Best practices](#best-practices)
- [Next steps](#next-steps)

---

- **Page:** Configuration · Unlighthouse
- **Source:** https://unlighthouse.dev/guide/guides/config
- **Description:** Configure Unlighthouse for your specific needs using configuration files and inline options.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Guides**

# **Configuration**

[Copy for LLMs](https://unlighthouse.dev/guide/guides/config.md)

Most scans work without any config. But when you need control—excluding paths, adjusting concurrency, setting up auth—here's how.

## The Config File

Create `**unlighthouse.config.ts**` in your project root:

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  site: 'https://example.com',
  scanner: {
    exclude: ['/admin/*', '/api/*'],
  },
})
```

Now run `**unlighthouse**` without flags. It picks up your config automatically.

The import is optional—skip it if you have resolution issues. The config still works.

## Config File Location

Unlighthouse looks for these files in order:

- `**unlighthouse.config.ts**`
- `**unlighthouse.config.js**`
- `**unlighthouse.config.mjs**`

Or specify one explicitly:

```bash
unlighthouse --config-file ./configs/production.config.ts
```

## Common Configs

### Skip Paths You Don't Care About

```ts
export default defineUnlighthouseConfig({
  site: 'https://example.com',
  scanner: {
    exclude: [
      '/api/*', // API routes
      '/admin/*', // Admin pages
      '/*.pdf', // PDF files
      '/amp/*', // AMP versions
    ],
  },
})
```

Or scan *only* specific paths:

```ts
export default defineUnlighthouseConfig({
  scanner: {
    include: ['/products/*', '/blog/*'], // Only these
  },
})
```

### Desktop Instead of Mobile

Default is mobile. Switch to desktop:

```ts
export default defineUnlighthouseConfig({
  scanner: {
    device: 'desktop',
  },
})
```

### More Accurate Scores

Lighthouse scores vary between runs. For reliable numbers:

```ts
export default defineUnlighthouseConfig({
  scanner: {
    samples: 3, // Run 3x per page, average the results
    throttle: true, // Simulate real network (slower but realistic)
  },
  puppeteerClusterOptions: {
    maxConcurrency: 1, // One at a time (less CPU contention)
  },
})
```

Trade-off: Much slower scans. Use for CI assertions, not development.

### Protected Sites (Auth)

```ts
export default defineUnlighthouseConfig({
  // Basic auth
  auth: {
    username: process.env.AUTH_USER,
    password: process.env.AUTH_PASS,
  },
  // Cookie auth
  cookies: [
    { name: 'session', value: process.env.SESSION_TOKEN, domain: '.example.com' },
  ],
})
```

See [**~~full authentication guide~~**](https://unlighthouse.dev/guide/guides/authentication).

### CI Performance Budgets

Fail your build if scores drop:

```ts
export default defineUnlighthouseConfig({
  ci: {
    budget: {
      'performance': 80,
      'accessibility': 90,
      'best-practices': 80,
      'seo': 90,
    },
    buildStatic: true, // Generate shareable HTML report
  },
})
```

## Advanced

### Customize Lighthouse Directly

Pass options straight to Lighthouse:

```ts
export default defineUnlighthouseConfig({
  lighthouseOptions: {
    onlyCategories: ['performance', 'accessibility'], // Skip SEO/best-practices
    skipAudits: ['uses-http2'], // Ignore specific audits
    throttlingMethod: 'devtools',
  },
})
```

### React to Scan Events

```ts
export default defineUnlighthouseConfig({
  hooks: {
    'task-complete': (path, report) => {
      if (report.score.performance < 0.5) {
        console.warn(`⚠️ ${path} scored ${report.score.performance}`)
      }
    },
    'worker-finished': () => {
      console.log('All done!')
    },
  },
})
```

### Environment-Based Config

```ts
export default defineUnlighthouseConfig(() => {
  const isProd = process.env.NODE_ENV === 'production'

  return {
    site: isProd ? 'https://mysite.com' : 'http://localhost:3000',
    scanner: {
      samples: isProd ? 3 : 1,
      throttle: isProd,
    },
  }
})
```

## Full Reference

See [**~~Config Reference~~**](https://unlighthouse.dev/api-doc/config) for every option with types and defaults.

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/0.config.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/guides/config.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/0.config.md) on GitHub or provide anonymous feedback below.

### **Related **

[**Config Reference**](https://unlighthouse.dev/api-doc/config) [**Debugging**](https://unlighthouse.dev/guide/guides/debugging) [**CLI Integration**](https://unlighthouse.dev/integrations/cli)

[**How It Works** Learn how Unlighthouse automatically discovers pages, runs Lighthouse audits in parallel, and generates site-wide performance reports.](https://unlighthouse.dev/guide/getting-started/how-it-works) [**Debugging** Debug and troubleshoot Unlighthouse scans using logging, browser inspection, and diagnostic tools.](https://unlighthouse.dev/guide/guides/debugging)

**On this page **

- [The Config File](#the-config-file)
- [Config File Location](#config-file-location)
- [Common Configs](#common-configs)
- [Advanced](#advanced)
- [Full Reference](#full-reference)

---

- **Page:** How Unlighthouse Works · Unlighthouse
- **Source:** https://unlighthouse.dev/guide/getting-started/how-it-works
- **Description:** Learn how Unlighthouse automatically discovers pages, runs Lighthouse audits in parallel, and generates site-wide performance reports.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Getting Started**

# **How Unlighthouse Works**

[Copy for LLMs](https://unlighthouse.dev/guide/getting-started/how-it-works.md)

Unlighthouse automates the entire site audit process: it finds all your pages, runs Lighthouse on each one in parallel, then shows you aggregated results in a real-time dashboard.

## How It Starts

### 1. Setup

First, Unlighthouse loads your config file using the [**~~c12~~**](https://github.com/unjs/c12) package. This supports TypeScript config files and gives you a global `**defineUnlighthouseConfig**` function for type support:

```ts
const unlighthouse = await createUnlighthouse(config)
```

#### **Browser Workers**

Unlighthouse creates a pool of Chrome browsers using [**~~puppeteer-cluster~~**](https://github.com/thomasdondorf/puppeteer-cluster):

- Opens multiple Chrome instances
- Each one can scan a different page
- Runs scans in parallel to go faster

### 2. Report Site Setup

Unlighthouse starts a local web server so you can see the results:

```ts
// Create server for the UI client
const { server, app } = await createServer()
await unlighthouse.setServerContext({
  url: server.url,
  server: server.server,
  app
})
```

#### **API**

The [**~~unrouted~~**](https://github.com/harlan-zw/unrouted) API handles:

- Sending scan updates to your browser
- Serving Lighthouse reports
- Managing the scanning process

#### **Web App**

A [**~~Vite~~**](https://github.com/vitejs/vite) web app that:

- Shows scan progress in real-time
- Displays all the Lighthouse scores
- Lets you filter and explore results

### 3. The Actual Scanning

#### **When It Starts**

Unlighthouse can start in two ways:

```ts
// CLI mode - starts immediately
unlighthouse.start()
```

#### **Finding Your Pages**

Unlighthouse finds pages to scan in a few ways:

1. **Route Files**: Reads your framework's route files (like Next.js pages)
2. **Robots.txt**: Checks your robots.txt file for sitemap links
3. **Sitemap.xml**: Gets all URLs from your sitemap
4. **Crawling**: If no sitemap, it starts from your homepage and follows links

Having a sitemap.xml makes scanning much faster and finds more pages.

#### **What Happens to Each Page**

For every URL it finds, Unlighthouse does two things:

##### Step 1: Quick HTML Check

- Makes a simple HTTP request to get the HTML
- Grabs basic info like title, meta tags
- Looks for more links to scan

##### Step 2: Full Lighthouse Scan

- Opens the page in Chrome
- Runs all the Lighthouse tests (including [**~~Core Web Vitals~~**](https://unlighthouse.dev/glossary) like [**~~LCP~~**](https://unlighthouse.dev/glossary/lcp), [**~~CLS~~**](https://unlighthouse.dev/glossary/cls), [**~~INP~~**](https://unlighthouse.dev/glossary/inp))
- Saves the report as HTML and JSON files

#### **Live Updates**

While scanning, the report page updates in real-time:

- Shows how many pages are done
- Updates the progress bar
- Shows results as soon as each page finishes

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/1.getting-started/how-it-works.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/getting-started/how-it-works.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/1.getting-started/how-it-works.md) on GitHub or provide anonymous feedback below.

### **Related **

[**URL Discovery**](https://unlighthouse.dev/guide/guides/url-discovery) [**Configuration**](https://unlighthouse.dev/guide/guides/config) [**Core Web Vitals Glossary**](https://unlighthouse.dev/glossary)

[**Integrations** Integrate Unlighthouse into your existing build tools, frameworks, and CI/CD pipelines for automated Lighthouse testing.](https://unlighthouse.dev/guide/getting-started/integrations) [**Configuration** Configure Unlighthouse for your specific needs using configuration files and inline options.](https://unlighthouse.dev/guide/guides/config)

---

- **Page:** unlighthouse-ci: Bulk Lighthouse CI for Entire Sites · Unlighthouse
- **Source:** https://unlighthouse.dev/integrations/ci
- **Description:** Run unlighthouse-ci on every deploy. Auto-discovers every URL, runs Lighthouse on all of them in parallel, enforces a single budget. Works in GitHub Actions, GitLab CI, any pipeline.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Integrations**

# **unlighthouse-ci: Bulk Lighthouse CI for Entire Sites**

[Copy for LLMs](https://unlighthouse.dev/integrations/ci.md)

## Run `**unlighthouse-ci**` in your pipeline

The `**unlighthouse-ci**` binary runs Lighthouse on every page of your site and fails your CI build if any score drops below a budget:

```bash
npm install -g @unlighthouse/cli puppeteer
unlighthouse-ci --site https://staging.example.com --budget 80
```

Exit code 1 = budget failed. Exit code 0 = all pages passed. That's the entire contract. Wire this single command into GitHub Actions, GitLab CI, CircleCI, or any pipeline that runs bash.

## Why Unlighthouse CI?

|  | **Google LHCI** | **Unlighthouse CI** |
| --- | --- | --- |
| **Setup** | Complex config, URL manifest | One command |
| **Pages** | Manual list | Auto-discovers entire site |
| **Budgets** | Per-page config | Single threshold for all pages |
| **Reports** | JSON/HTML | Interactive dashboard, JSON, CSV |

## Basic Usage

```bash
# Scan site, fail if any page < 75
unlighthouse-ci --site example.com --budget 75

# Generate static HTML report
unlighthouse-ci --site example.com --build-static

# Both: budget check + report
unlighthouse-ci --site example.com --budget 75 --build-static
```

## Already Using LHCI Server?

Keep your existing infrastructure—Unlighthouse uploads to LHCI servers:

```bash
unlighthouse-ci --site example.com \
  --reporter lighthouseServer \
  --lhci-host https://lhci.yourcompany.com \
  --lhci-build-token $LHCI_TOKEN
```

## Installation for CI

CI environments need Chrome. Install puppeteer alongside the CLI:

```bash
npm install -g @unlighthouse/cli puppeteer
```

Puppeteer downloads a compatible Chromium binary automatically.

## Performance Budgets

### Simple: One Number

```bash
# Fail if ANY category on ANY page < 75
unlighthouse-ci --site example.com --budget 75
```

### Per-Category Budgets

More control in your config:

```ts
// unlighthouse.config.ts
export default defineUnlighthouseConfig({
  site: 'https://example.com',
  ci: {
    budget: {
      'performance': 70, // Performance can be lower
      'accessibility': 95, // Accessibility must be high
      'best-practices': 80,
      'seo': 90,
    },
  },
})
```

Run with just:

```bash
unlighthouse-ci
```

## Report Formats

| **Format** | **Use Case** | **Flag** |
| --- | --- | --- |
| `**json**` | Simple scores for CI parsing | `**--reporter json**` |
| `**jsonExpanded**` | Full metrics breakdown | `**--reporter jsonExpanded**` |
| `**csv**` | Spreadsheet analysis | `**--reporter csv**` |
| `**csvExpanded**` | Full data in CSV | `**--reporter csvExpanded**` |
| `**lighthouseServer**` | Upload to LHCI server | `**--reporter lighthouseServer**` |

```bash
# Generate CSV for stakeholders
unlighthouse-ci --site example.com --reporter csvExpanded
```

## Static Reports

Generate a shareable HTML dashboard:

```bash
unlighthouse-ci --site example.com --build-static
```

Output goes to `**.unlighthouse/**`. Upload that folder to any static host.

**Live examples:**

- [**~~inspect.unlighthouse.dev~~**](https://inspect.unlighthouse.dev/)
- [**~~vue-demo.unlighthouse.dev~~**](https://vue-demo.unlighthouse.dev/)

## Configuration

Configuring the CLI can be done either through the CI arguments or through a config file.

### CI Options

| **Options** | |
| --- | --- |
| `**-v, --version**` | Display version number. |
| `**--site <url>**` | Host URL to scan. |
| `**--root <path>**` | Define the project root. Useful for changing where the config is read from or setting up sampling. |
| `**--config-file <path>**` | Path to config file. |
| `**--output-path <path>**` | Path to save the contents of the client and reports to. |
| `**--budget <budget>**` | Budget (1-100), the minimum score which can pass. |
| `**--reporter <reporter>**` | The report to generate from results. Options: csv, csvExpanded, json, jsonExpanded, lighthouseServer or false. Default: jsonSimple. |
| `**--lhci-host <lhci-host>**` | URL of your LHCI server. |
| `**--lhci-build-token <lhci-build-token>**` | LHCI build token, used to add data. |
| `**--lhci-auth <lhci-auth>**` | Basic auth for your LHCI server. |
| `**--build-static**` | Build a static website for the reports which can be uploaded. |
| `**--cache**` | Enable the caching. |
| `**--no-cache**` | Disable the caching. |
| `**--desktop**` | Simulate device as desktop. |
| `**--mobile**` | Simulate device as mobile. |
| `**--user-agent <user-agent>**` | Specify a top-level user agent all requests will use. |
| `**--router-prefix <path>**` | The URL path prefix for the client and API to run from. |
| `**--throttle**` | Enable the throttling. |
| `**--samples <samples>**` | Specify the amount of samples to run. |
| `**--sitemaps <sitemaps>**` | Comma separated list of sitemaps to use for scanning. Providing these will override any in robots.txt. |
| `**--urls <urls>**` | Specify explicit relative paths to scan as a comma-separated list, disabling the link crawler. |
| `**--exclude-urls <urls>**` | Relative paths (string or regex) to exclude as a comma-separated list. |
| `**--include-urls <urls>**` | Relative paths (string or regex) to include as a comma-separated list. |
| `**--enable-javascript**` | When inspecting the HTML wait for the javascript to execute. Useful for SPAs. |
| `**--disable-javascript**` | When inspecting the HTML, don't wait for the javascript to execute. |
| `**--enable-i18n-pages**` | Enable scanning pages which use x-default. |
| `**--disable-i18n-pages**` | Disable scanning pages which use x-default. |
| `**--disable-robots-txt**` | Disables the robots.txt crawling. |
| `**--disable-sitemap**` | Disables the sitemap.xml crawling. |
| `**--disable-dynamic-sampling**` | Disables the sampling of paths. |
| `**--extra-headers <headers>**` | Extra headers to send with the request. Example: --extra-headers foo=bar,bar=foo |
| `**--cookies <cookies>**` | Cookies to send with the request. Example: --cookies foo=bar;bar=foo |
| `**--auth <auth>**` | Basic auth to send with the request. Example: --auth username:password |
| `**--default-query-params <params>**` | Default query params to send with the request. Example: --default-query-params foo=bar,bar=foo |
| `**-d, --debug**` | Debug. Enable debugging in the logger. |
| `**-h, --help**` | Display available CLI options |

### Config File

If you want to configure Unlighthouse, you can create a `**unlighthouse.config.ts**` file in your cwd.

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  site: 'example.com',
  debug: true,
  scanner: {
    device: 'desktop',
  },
})
```

See the [**~~Configuration~~**](#configuration) section for more details and the guides.

## GitHub Actions & Netlify Example

This example is for GitHub Actions and deploys a static client build to Netlify.

```yml
name: Assertions and static report

on:
  workflow_dispatch:

jobs:
  demo:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Dependencies
        run: npm install -g @unlighthouse/cli puppeteer netlify-cli

      - name: Unlighthouse assertions and client
        run: unlighthouse-ci --site <your-site> --budget 75 --build-static

      - name: Deploy
        run: netlify deploy --dir=.unlighthouse --prod --message="New Release Deploy from GitHub Actions"
        env:
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
```

## GitLab CI Example

```yaml
# .gitlab-ci.yml
lighthouse-audit:
  image: node:22
  script:
    - npm install -g @unlighthouse/cli puppeteer
    - unlighthouse-ci --site $SITE_URL --budget 75
  artifacts:
    paths:
      - .unlighthouse/
    expire_in: 1 week
```

## CircleCI Example

```yaml
# .circleci/config.yml
version: 2.1
jobs:
  lighthouse:
    docker:
      - image: cimg/node:22.18.0-browsers
    steps:
      - checkout
      - run: npm install -g @unlighthouse/cli
      - run: unlighthouse-ci --site $SITE_URL --budget 75 --build-static
      - store_artifacts:
          path: .unlighthouse
```

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/2.integrations/1.ci.md)

[Markdown For LLMs](https://unlighthouse.dev/integrations/ci.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/2.integrations/1.ci.md) on GitHub or provide anonymous feedback below.

### **Related **

[**CLI Integration**](https://unlighthouse.dev/integrations/cli) [**Static Reports**](https://unlighthouse.dev/guide/guides/generating-static-reports) [**Core Web Vitals Guide**](https://unlighthouse.dev/glossary)

[**CLI** Scan your entire website with Lighthouse from the command line. Alternative to lighthouse CLI that audits all pages automatically.](https://unlighthouse.dev/integrations/cli) [**Nuxt** Integrate Lighthouse audits directly into your Nuxt development workflow with automatic route discovery.](https://unlighthouse.dev/integrations/nuxt)

**On this page **

- [Run unlighthouse-ci in your pipeline](#run-unlighthouse-ci-in-your-pipeline)
- [Why Unlighthouse CI?](#why-unlighthouse-ci)
- [Basic Usage](#basic-usage)
- [Already Using LHCI Server?](#already-using-lhci-server)
- [Installation for CI](#installation-for-ci)
- [Performance Budgets](#performance-budgets)
- [Report Formats](#report-formats)
- [Static Reports](#static-reports)
- [Configuration](#configuration)
- [GitHub Actions & Netlify Example](#github-actions-netlify-example)
- [GitLab CI Example](#gitlab-ci-example)
- [CircleCI Example](#circleci-example)

---

- **Page:** Nuxt Integration · Unlighthouse
- **Source:** https://unlighthouse.dev/integrations/nuxt
- **Description:** Integrate Lighthouse audits directly into your Nuxt development workflow with automatic route discovery.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Integrations**

# **Nuxt Integration**

[Copy for LLMs](https://unlighthouse.dev/integrations/nuxt.md)

**Deprecated**: This integration will be removed in v1.0. Use [**~~CLI~~**](https://unlighthouse.dev/integrations/cli) or [**~~CI~~**](https://unlighthouse.dev/integrations/ci) instead. See [**~~deprecation notice~~**](https://unlighthouse.dev/integration-deprecations).

Lighthouse auditing during Nuxt development with automatic route discovery and HMR support.

## Install

```bash
yarn add -D @unlighthouse/nuxt
```

### Git ignore reports

Unlighthouse will save your reports in `**outputDir**` (`**.unlighthouse**` by default), it's recommended you .gitignore these files.

```shell
.unlighthouse
```

## Usage

To begin using Unlighthouse, you'll need to add the module to `**buildModules**`.

When you run your Nuxt app, it will give you the URL of client, only once you visit the client will Unlighthouse start.

### Nuxt 3

```js
import { defineNuxtConfig } from 'nuxt3'

export default defineNuxtConfig({
  modules: [
    '@unlighthouse/nuxt',
  ],
})
```

### Nuxt 2

```js
export default {
  buildModules: [
    '@unlighthouse/nuxt',
  ],
}
```

Type support can be added by adding the `**@unlighthouse/nuxt**` module to your `**plugins**`. Nuxt v3 will automatically add type support.

```json
{
  "compilerOptions": {
    "types": [
      "@unlighthouse/nuxt"
    ]
  }
}
```

## Configuration

You can either configure Unlighthouse via the `**unlighthouse**` key in your Nuxt config, or you can provide a `**unlighthouse.config.ts**` file in the root directory.

### Example

```js
export default {
  unlighthouse: {
    scanner: {
      // simulate a desktop device
      device: 'desktop',
    }
  }
}
```

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/2.integrations/3.nuxt.md)

[Markdown For LLMs](https://unlighthouse.dev/integrations/nuxt.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/2.integrations/3.nuxt.md) on GitHub or provide anonymous feedback below.

### **Related **

[**CLI Integration**](https://unlighthouse.dev/integrations/cli) [**Deprecation Notice**](https://unlighthouse.dev/integration-deprecations) [**Configuration**](https://unlighthouse.dev/guide/guides/config)

[**CI/CD** Run unlighthouse-ci on every deploy. Auto-discovers every URL, runs Lighthouse on all of them in parallel, enforces a single budget. Works in GitHub Actions, GitLab CI, any pipeline.](https://unlighthouse.dev/integrations/ci) [**Vite** Integrate Lighthouse audits into your Vite development server with automatic route discovery and HMR support.](https://unlighthouse.dev/integrations/vite)

**On this page **

- [Install](#install)
- [Usage](#usage)
- [Configuration](#configuration)

---

- **Page:** Webpack Integration · Unlighthouse
- **Source:** https://unlighthouse.dev/integrations/webpack
- **Description:** Add Lighthouse auditing to webpack-based projects with development server integration and HMR support.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Integrations**

# **Webpack Integration**

[Copy for LLMs](https://unlighthouse.dev/integrations/webpack.md)

**Deprecated**: This integration will be removed in v1.0. Use [**~~CLI~~**](https://unlighthouse.dev/integrations/cli) or [**~~CI~~**](https://unlighthouse.dev/integrations/ci) instead. See [**~~deprecation notice~~**](https://unlighthouse.dev/integration-deprecations).

Lighthouse auditing for webpack-based applications during development.

## Install

```bash
yarn add -D @unlighthouse/webpack
```

### Git ignore reports

Unlighthouse will save your reports in `**outputDir**` (`**.unlighthouse**` by default), it's recommended you .gitignore these files.

```shell
.unlighthouse
```

## Usage

To begin using Unlighthouse, you'll need to add extend your webpack configuration.

When you run your webpack app, it will give you the URL of client, only once you visit the client will Unlighthouse start.

### webpack.config.js example

```js
import Unlighthouse from '@unlighthouse/webpack'

export default {
  // ...
  plugins: [
    Unlighthouse({
      // config
    }),
  ],
}
```

### CJS example

```js
const Unlighthouse = require('@unlighthouse/webpack')

export default {
  // ...
  plugins: [
    Unlighthouse({
      // config
    }),
  ],
}
```

## Configuration

You can either configure Unlighthouse via the plugin, or you can provide a [**~~config file~~**](https://unlighthouse.dev/guide/guides/config) in the root directory.

### Example

```js
import Unlighthouse from '@unlighthouse/webpack'

export default {
  // ...
  plugins: [
    Unlighthouse({
      scanner: {
        // simulate a desktop device
        device: 'desktop',
      }
    }),
  ],
}
```

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/2.integrations/webpack.md)

[Markdown For LLMs](https://unlighthouse.dev/integrations/webpack.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/2.integrations/webpack.md) on GitHub or provide anonymous feedback below.

### **Related **

[**CLI Integration**](https://unlighthouse.dev/integrations/cli) [**Deprecation Notice**](https://unlighthouse.dev/integration-deprecations) [**Configuration**](https://unlighthouse.dev/guide/guides/config)

[**Vite** Integrate Lighthouse audits into your Vite development server with automatic route discovery and HMR support.](https://unlighthouse.dev/integrations/vite) [**Config Reference** Complete reference for all Unlighthouse configuration options including types, defaults, and usage examples.](https://unlighthouse.dev/api-doc/config)

**On this page **

- [Install](#install)
- [Usage](#usage)
- [Configuration](#configuration)

---

- **Page:** Vite Integration · Unlighthouse
- **Source:** https://unlighthouse.dev/integrations/vite
- **Description:** Integrate Lighthouse audits into your Vite development server with automatic route discovery and HMR support.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Integrations**

# **Vite Integration**

[Copy for LLMs](https://unlighthouse.dev/integrations/vite.md)

**Deprecated**: This integration will be removed in v1.0. Use [**~~CLI~~**](https://unlighthouse.dev/integrations/cli) or [**~~CI~~**](https://unlighthouse.dev/integrations/ci) instead. See [**~~deprecation notice~~**](https://unlighthouse.dev/integration-deprecations).

Lighthouse auditing within your Vite dev environment with real-time performance feedback.

## Install

```bash
yarn add -D @unlighthouse/vite
```

### Git ignore reports

Unlighthouse will save your reports in `**outputDir**` (`**.unlighthouse**` by default), it's recommended you .gitignore these files.

```shell
.unlighthouse
```

## Usage

To begin using Unlighthouse, you'll need to add the plugin to `**plugins**`.

When you run your Vite app, it will give you the URL of client, only once you visit the client will Unlighthouse start.

```ts
import Unlighthouse from '@unlighthouse/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    Unlighthouse({
      // config
    })
  ]
})
```

### Providing Route Definitions

If you're using the [**~~vite-plugin-pages~~**](https://github.com/hannoeru/vite-plugin-pages) plugin, you can provide route definitions to Unlighthouse.

You will need to hook into the plugin using the following code.

```ts
import { useUnlighthouse } from 'unlighthouse'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    Pages({
      // ...
      onRoutesGenerated(routes) {
        // tell Unlighthouse about the routes
        const unlighthouse = useUnlighthouse()
        if (unlighthouse?.hooks)
          unlighthouse.hooks.callHook('route-definitions-provided', routes)
      }
    }),
  ]
})
```

## Configuration

You can either configure Unlighthouse via the plugin, or you can provide a [**~~config file~~**](https://unlighthouse.dev/guide/guides/config) file in the root directory.

### Example

```ts
import Unlighthouse from '@unlighthouse/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    Unlighthouse({
      scanner: {
        // simulate a desktop device
        device: 'desktop',
      }
    })
  ]
})
```

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/2.integrations/4.vite.md)

[Markdown For LLMs](https://unlighthouse.dev/integrations/vite.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/2.integrations/4.vite.md) on GitHub or provide anonymous feedback below.

### **Related **

[**CLI Integration**](https://unlighthouse.dev/integrations/cli) [**Deprecation Notice**](https://unlighthouse.dev/integration-deprecations) [**Configuration**](https://unlighthouse.dev/guide/guides/config)

[**Nuxt** Integrate Lighthouse audits directly into your Nuxt development workflow with automatic route discovery.](https://unlighthouse.dev/integrations/nuxt) [**Webpack** Add Lighthouse auditing to webpack-based projects with development server integration and HMR support.](https://unlighthouse.dev/integrations/webpack)

**On this page **

- [Install](#install)
- [Usage](#usage)
- [Configuration](#configuration)

---

- **Page:** Lighthouse CLI for Entire Sites · Unlighthouse
- **Source:** https://unlighthouse.dev/integrations/cli
- **Description:** Scan your entire website with Lighthouse from the command line. Alternative to lighthouse CLI that audits all pages automatically.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Integrations**

# **Lighthouse CLI for Entire Sites**

[Copy for LLMs](https://unlighthouse.dev/integrations/cli.md)

Scan your entire website from the command line with a rich interactive dashboard. Unlike the standard `**lighthouse**` CLI which tests one page at a time, Unlighthouse automatically discovers and audits all your pages.

## Installation

### Global install (recommended for frequent use)

```bash
npm install -g unlighthouse
```

### One-time run (no install)

```bash
npx unlighthouse --site example.com
```

Unlighthouse wraps the [**~~Lighthouse npm package~~**](https://www.npmjs.com/package/lighthouse) to enable site-wide scanning.

## Unlighthouse CLI vs Lighthouse CLI

| **Feature** | **lighthouse CLI** | **unlighthouse CLI** |
| --- | --- | --- |
| Package | `**lighthouse**` | `**unlighthouse**` |
| Pages per run | 1 | Unlimited |
| URL discovery | Manual | Automatic |
| Interactive UI | No | Yes |
| Caching | No | Yes |
| Dynamic sampling | No | Yes |
| CI/CD ready | Manual setup | Built-in |

### When to use Lighthouse CLI

- Single page audits
- Quick manual checks
- Debugging specific pages

### When to use Unlighthouse CLI

- Full site audits
- Pre-launch checks
- Ongoing monitoring
- CI/CD integration

## Usage

Once installed globally you'll have access to Unlighthouse through the `**unlighthouse**` binary.

Run the default scan.

```bash
unlighthouse --site example.com --debug
```

Run without caching, throttle the requests and do 3 samples.

```bash
unlighthouse --site example.com --debug --no-cache --throttle --samples 3
```

## Configuration

Configuring the CLI can be done either through the CLI arguments or through a config file.

See the [**~~Configuration~~**](#configuration) section for more details and the guides.

### CLI Options

| **Options** | |
| --- | --- |
| `**-v, --version**` | Display version number. |
| `**--site <url>**` | Host URL to scan. |
| `**--root <path>**` | Define the project root. Useful for changing where the config is read from or setting up sampling. |
| `**--config-file <path>**` | Path to config file. |
| `**--output-path <path>**` | Path to save the contents of the client and reports to. |
| `**--cache**` | Enable the caching. |
| `**--no-cache**` | Disable the caching. |
| `**--desktop**` | Simulate device as desktop. |
| `**--mobile**` | Simulate device as mobile. |
| `**--user-agent <user-agent>**` | Specify a top-level user agent all requests will use. |
| `**--router-prefix <path>**` | The URL path prefix for the client and API to run from. |
| `**--throttle**` | Enable the throttling. |
| `**--samples <samples>**` | Specify the amount of samples to run. |
| `**--sitemaps <sitemaps>**` | Comma separated list of sitemaps to use for scanning. Providing these will override any in robots.txt. |
| `**--urls <urls>**` | Specify explicit relative paths to scan as a comma-separated list, disabling the link crawler.<br>e.g. `**unlighthouse --site unlighthouse.dev --urls /guide,/api,/config**` |
| `**--exclude-urls <urls>**` | Relative paths (string or regex) to exclude as a comma-separated list. <br>e.g. `**unlighthouse --site unlighthouse.dev --exclude-urls /guide/.*,/api/.***` |
| `**--include-urls <urls>**` | Relative paths (string or regex) to include as a comma-separated list. <br>e.g. `**unlighthouse --site unlighthouse.dev --include-urls /guide/.***` |
| `**--enable-javascript**` | When inspecting the HTML wait for the javascript to execute. Useful for SPAs. |
| `**--disable-javascript**` | When inspecting the HTML, don't wait for the javascript to execute. |
| `**--enable-i18n-pages**` | Enable scanning pages which use x-default. |
| `**--disable-i18n-pages**` | Disable scanning pages which use x-default. |
| `**--disable-robots-txt**` | Disables the robots.txt crawling. |
| `**--disable-sitemap**` | Disables the sitemap.xml crawling. |
| `**--disable-dynamic-sampling**` | Disables the sampling of paths. |
| `**--extra-headers <headers>**` | Extra headers to send with the request. Example: --extra-headers foo=bar,bar=foo |
| `**--cookies <cookies>**` | Cookies to send with the request. Example: --cookies foo=bar;bar=foo |
| `**--auth <auth>**` | Basic auth to send with the request. Example: --auth username:password |
| `**--default-query-params <params>**` | Default query params to send with the request. Example: --default-query-params foo=bar,bar=foo |
| `**-d, --debug**` | Debug. Enable debugging in the logger. |
| `**-h, --help**` | Display available CLI options |

### Config File

If you want to configure Unlighthouse, you can create a `**unlighthouse.config.ts**` file in your cwd.

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  site: 'example.com',
  debug: true,
  scanner: {
    device: 'desktop',
  },
})
```

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/2.integrations/0.cli.md)

[Markdown For LLMs](https://unlighthouse.dev/integrations/cli.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/2.integrations/0.cli.md) on GitHub or provide anonymous feedback below.

### **Related **

[**CI Integration**](https://unlighthouse.dev/integrations/ci) [**Configuration**](https://unlighthouse.dev/guide/guides/config) [**Core Web Vitals Guide**](https://unlighthouse.dev/glossary)

[**SPAs** Configure Unlighthouse to scan single-page applications (SPAs) with client-side routing like React, Vue, and Angular apps.](https://unlighthouse.dev/guide/recipes/spa) [**CI/CD** Run unlighthouse-ci on every deploy. Auto-discovers every URL, runs Lighthouse on all of them in parallel, enforces a single budget. Works in GitHub Actions, GitLab CI, any pipeline.](https://unlighthouse.dev/integrations/ci)

**On this page **

- [Installation](#installation)
- [Unlighthouse CLI vs Lighthouse CLI](#unlighthouse-cli-vs-lighthouse-cli)
- [Usage](#usage)
- [Configuration](#configuration)

---

- **Page:** Lighthouse Speed Index: What It Means, Good Scores &amp; How to Fix · Unlighthouse
- **Source:** https://unlighthouse.dev/glossary/speed-index
- **Description:** Speed Index (SI) measures how fast visible content fills the viewport. Good: ≤3.4s mobile, ≤1.3s desktop. 10% of Lighthouse performance score. Thresholds, tools, fixes.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Glossary**

# **Lighthouse Speed Index: What It Means, Good Scores & How to Fix**

[Copy for LLMs](https://unlighthouse.dev/glossary/speed-index.md)

Speed Index measures how quickly visible content appears in the viewport during a Lighthouse run. Unlike FCP or LCP, which mark individual moments, Speed Index scores the visual progress across the loading sequence. It contributes 10% to the Lighthouse Performance score.

## Thresholds

### Mobile

| **Score** | **Rating** |
| --- | --- |
| ≤ 3.4s | Good |
| 3.4s - 5.8s | Needs Improvement |
| > 5.8s | Poor |

### Desktop

| **Score** | **Rating** |
| --- | --- |
| ≤ 1.3s | Good |
| 1.3s - 2.3s | Needs Improvement |
| > 2.3s | Poor |

## How it works

Lighthouse records video frames during the page load, estimates visual completeness for each frame, then calculates the area above the visual progress curve. A page that paints most of its above-the-fold content early scores better than one that reveals the same content gradually.

Speed Index depends on the emulated viewport and test environment. Mobile and desktop use different scoring curves, which is why their good thresholds differ. Compare runs only when viewport, Chrome version, throttling, and page state match.

## Speed Index vs other metrics

| **Metric** | **What it answers** |
| --- | --- |
| [**~~FCP~~**](https://unlighthouse.dev/glossary/fcp) | When did the first content appear? |
| [**~~LCP~~**](https://unlighthouse.dev/glossary/lcp) | When did the main content element appear? |
| Speed Index | How quickly did the visible viewport fill in? |

Two pages can share the same LCP while having different Speed Index values. A useful header and article text painted before a late hero can improve visual progress. A blank screen that reveals everything at once may have the same LCP but a worse Speed Index.

## What makes Speed Index slow

- Render-blocking CSS/JavaScript
- Large above-the-fold images
- Web font loading delays
- Client-side rendering
- Blank loading screens that hide ready content
- Main-thread tasks that delay style, layout, or paint

## How to improve Speed Index

1. Make critical content available in the initial HTML.
2. Inline or prioritize the small amount of CSS needed above the fold.
3. Preload only the confirmed LCP image or critical font, then check the network waterfall for competition.
4. Give images explicit dimensions and responsive sources.
5. Remove startup JavaScript or defer work that does not affect the first viewport.

Start with the Lighthouse diagnostics attached to the slow run. A Speed Index value alone cannot tell you whether CSS, images, fonts, or JavaScript caused the delay.

## Limits of Speed Index

Speed Index is based on pixels, not meaning. A large background color can look visually complete while useful text remains missing. Carousels and loading animations can also change many pixels without helping the user.

It is a synthetic metric for the initial viewport, not a Core Web Vital and not a measure of interaction responsiveness. Use it to explain visual loading in lab tests, then check [**~~LCP~~**](https://unlighthouse.dev/glossary/lcp), [**~~CLS~~**](https://unlighthouse.dev/glossary/cls), and [**~~INP~~**](https://unlighthouse.dev/glossary/inp) in field data.

## Measure speed index

- Lighthouse in Chrome DevTools
- [**~~PageSpeed Insights~~**](https://pagespeed.web.dev/) lab metrics
- WebPageTest, which introduced the metric
- [**~~Unlighthouse Bulk PageSpeed Test~~**](https://unlighthouse.dev/tools/bulk-pagespeed) for comparing routes across a site

Use the [**~~Lighthouse Score Calculator~~**](https://unlighthouse.dev/tools/lighthouse-score-calculator) to see how the 10% Speed Index weight affects the Performance score. Optimize the page, not the calculator: a lower Speed Index should come from content appearing sooner for users.

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/speed-index.md)

[Markdown For LLMs](https://unlighthouse.dev/glossary/speed-index.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/speed-index.md) on GitHub or provide anonymous feedback below.

### **Related **

[**First Contentful Paint (FCP)**](https://unlighthouse.dev/glossary/fcp) [**Largest Contentful Paint (LCP)**](https://unlighthouse.dev/glossary/lcp) [**Lighthouse Score Calculator**](https://unlighthouse.dev/tools/lighthouse-score-calculator) [**Fix Render-Blocking Resources**](https://unlighthouse.dev/learn-lighthouse/lcp/render-blocking-resources)

[**LCP** LCP measures loading performance. Learn what it is, thresholds, and how to improve your score.](https://unlighthouse.dev/glossary/lcp) [**TBT** TBT measures main thread blocking during load. Learn what it is, thresholds, and how to reduce blocking time.](https://unlighthouse.dev/glossary/tbt)

**On this page **

- [Thresholds](#thresholds)
- [How it works](#how-it-works)
- [Speed Index vs other metrics](#speed-index-vs-other-metrics)
- [What makes Speed Index slow](#what-makes-speed-index-slow)
- [How to improve Speed Index](#how-to-improve-speed-index)
- [Limits of Speed Index](#limits-of-speed-index)
- [Measure speed index](#measure-speed-index)

---

- **Page:** What is time to first byte (TTFB)? · Unlighthouse
- **Source:** https://unlighthouse.dev/glossary/ttfb
- **Description:** TTFB measures server response time. Learn what it is, thresholds, and how to optimize it.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Glossary**

# **What is time to first byte (TTFB)?**

[Copy for LLMs](https://unlighthouse.dev/glossary/ttfb.md)

Time to First Byte (TTFB) measures how long until the browser receives the first byte from the server. It's a foundational metric - nothing can render until this completes.

## Thresholds

| **Metric** | **Good** | **Needs Improvement** | **Poor** |
| --- | --- | --- | --- |
| **Core Web Vitals** | ≤ 800ms | 800ms - 1800ms | > 1800ms |
| **Lighthouse Audit** | < 600ms | 600ms - 1200ms | > 1200ms |

Aim for a field score of 800 milliseconds or less at the 75th percentile to pass the [**~~Google threshold~~**](https://web.dev/articles/ttfb). However, the Lighthouse audit requires a server response time under **600ms** to pass the lab check.

## What TTFB includes

- Redirect time
- DNS lookup
- TCP connection
- TLS negotiation
- Server processing time

Sites with poor [**~~LCP~~**](https://unlighthouse.dev/glossary/lcp) have an [**~~average TTFB of 2,270ms~~**](https://almanac.httparchive.org/en/2024/performance) - nearly consuming the entire 2.5s LCP budget.

## Why it matters

TTFB is the starting point for all other metrics. High TTFB delays [**~~FCP~~**](https://unlighthouse.dev/glossary/fcp), [**~~LCP~~**](https://unlighthouse.dev/glossary/lcp), and everything else. For SPAs, fast TTFB is especially critical since client-side rendering adds more time.

## Common issues

- Slow server processing / database queries
- No caching (regenerating cacheable responses)
- Geographic distance without CDN
- Too many redirects

## Improve TTFB

- Use a CDN
- Enable caching at all levels
- Optimize backend code
- Use HTTP/2 or HTTP/3
- Minimize redirects

## Measure TTFB

- Chrome DevTools Network panel ("Waiting for server response")
- [**~~PageSpeed Insights~~**](https://pagespeed.web.dev/)
- WebPageTest waterfall

TTFB directly impacts [**~~LCP~~**](https://unlighthouse.dev/glossary/lcp), a Core Web Vital. Slow TTFB makes good LCP nearly impossible.

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/ttfb.md)

[Markdown For LLMs](https://unlighthouse.dev/glossary/ttfb.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/ttfb.md) on GitHub or provide anonymous feedback below.

### **Related **

[**First Contentful Paint (FCP)**](https://unlighthouse.dev/glossary/fcp) [**Largest Contentful Paint (LCP)**](https://unlighthouse.dev/glossary/lcp) [**LCP Guide**](https://unlighthouse.dev/learn-lighthouse/lcp)

[**TBT** TBT measures main thread blocking during load. Learn what it is, thresholds, and how to reduce blocking time.](https://unlighthouse.dev/glossary/tbt) [**TTI (Deprecated)** TTI measured page interactivity but was deprecated in Lighthouse 10. Learn what replaced it.](https://unlighthouse.dev/glossary/tti)

**On this page **

- [Thresholds](#thresholds)
- [What TTFB includes](#what-ttfb-includes)
- [Why it matters](#why-it-matters)
- [Common issues](#common-issues)
- [Improve TTFB](#improve-ttfb)
- [Measure TTFB](#measure-ttfb)

---

- **Page:** Fix Slow Server Response (TTFB) for Better LCP · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/lcp/slow-server-response
- **Description:** Reduce server response time to improve LCP. Learn CDN setup, caching strategies, database optimization, and edge computing solutions.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Slow Server Response (TTFB) for Better LCP**

Reduce server response time to improve LCP. Learn CDN setup, caching strategies, database optimization, and edge computing solutions.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)8 min read Published **Jan 18, 2025**

Server response time is the [**~~leading cause of poor LCP~~**](https://web.dev/blog/common-misconceptions-lcp). Sites with poor LCP have an average TTFB of 2,270ms - consuming nearly all of the 2.5s budget before a single byte reaches the browser.

**LCP**Largest Contentful Paint** CWV **

**25% weight **

Good ≤2.5sPoor >4.0s

## What's the problem?

Time to First Byte (TTFB) measures the duration between the browser requesting a page and receiving the first byte of the response. Lighthouse flags this as "Reduce initial server response time" when your document takes longer than **600ms** to respond.

The real-world thresholds for Core Web Vitals are: **Good under 800ms**, Needs Improvement between 800-1800ms, and Poor above 1800ms. However, for a high Lighthouse score, you should aim for **under 600ms**.

Every millisecond of server delay directly adds to your LCP. If your server takes 2 seconds to respond, you've already consumed 80% of your LCP budget before the browser even begins parsing HTML. The cascade effect is brutal: no HTML means no CSS discovery, no CSS means no render, and no render means no LCP.

The problem compounds across geographic distances. A user in Singapore requesting a page from a Virginia server experiences 250ms+ of network latency each way. Add database queries, server-side rendering, and cold starts, and you're looking at TTFB measurements that dwarf everything else in your performance waterfall.

## How to identify this issue

### Chrome DevTools

1. Open DevTools (F12) and navigate to the Network tab
2. Hard reload the page (Ctrl+Shift+R / Cmd+Shift+R)
3. Click on the first HTML document request
4. Examine the Timing breakdown - look for "Waiting for server response"
5. Anything above **600ms** will trigger a Lighthouse audit failure; above **800ms** fails the Core Web Vitals "Good" threshold.

### Command line

```bash
curl -w "TTFB: %{time_starttransfer}s\n" -o /dev/null -s https://your-site.com

for i in {1..5}; do curl -w "%{time_starttransfer}\n" -o /dev/null -s https://your-site.com; done

curl -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTTFB: %{time_starttransfer}s\n" -o /dev/null -s https://your-site.com
```

### Lighthouse indicators

Lighthouse reports "Reduce initial server response time" under Diagnostics when the root document exceeds the **600ms** threshold. The audit shows the actual response time and calculates potential savings toward FCP and LCP metrics.

## The fix

### Primary: deploy a CDN with edge caching

A CDN eliminates geographic latency by serving cached content from servers close to your users. This single change typically reduces TTFB by 100-500ms for global audiences.

```nginx
/*
  Cache-Control: public, max-age=3600, s-maxage=3600
```

```js
// Vercel edge caching via headers
export const config = {
  runtime: 'edge',
}

export default function handler(req) {
  return new Response(html, {
    headers: {
      'Cache-Control': 'public, s-maxage=3600, stale-while-revalidate=86400',
    },
  })
}
```

For dynamic content, use `**stale-while-revalidate**` to serve cached content immediately while refreshing in the background:

```http
Cache-Control: public, max-age=60, stale-while-revalidate=3600
```

### Secondary: optimize database queries

Slow database queries are the hidden TTFB killer. A single unindexed query can add 500ms+ to every page load.

```sql
-- Find slow queries in PostgreSQL
SELECT query, calls, mean_time, total_time
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;

-- Add indexes for common patterns
CREATE INDEX idx_posts_user_published
ON posts(user_id, published_at)
WHERE status = 'published';
```

```js
// Use connection pooling - critical for serverless
import { Pool } from 'pg'

const pool = new Pool({
  max: 20,
  idleTimeoutMillis: 30000,
  connectionTimeoutMillis: 2000,
})
```

### Tertiary: edge computing for dynamic content

When you can't cache HTML, move your compute closer to users with edge functions.

```js
// Cloudflare Workers - global edge deployment
export default {
  async fetch(request, env) {
    const data = await env.KV.get('page-data', 'json')
    return new Response(renderPage(data), {
      headers: { 'Content-Type': 'text/html' },
    })
  }
}
```

```js
// Vercel Edge Functions
export const config = { runtime: 'edge' }

export default async function handler(req) {
  const data = await fetch('https://api.example.com/data')
  return new Response(renderTemplate(await data.json()))
}
```

## Why this works

TTFB reduction creates a direct 1:1 improvement in LCP because the browser cannot begin any rendering work until HTML arrives. Reducing TTFB from 600ms to 200ms gives the browser an extra 400ms to download CSS, discover images, and paint the LCP element. CDNs solve the physics problem (speed of light latency), while caching solves the compute problem (server processing time). Together, they address the two largest contributors to slow server response.

### Technical SEO bonus: crawl budget

Improving TTFB doesn't just help users; it helps Googlebot index your site.

- **Crawl Budget:** Google allocates a specific time/resource budget to crawl your site.
- **The Connection:** Faster server response = Googlebot crawls more pages in the same amount of time.
- **The Result:** Faster discovery of new content and updates.

> *"If the site is fast, we can crawl more. If the site is slow, we crawl less." - *[**~~Google Search Central~~**](https://developers.google.com/search/docs/crawling-indexing/large-site-managing-crawl-budget)

## Framework-specific solutions

**Next.js**: Use App Router with automatic streaming. Deploy to [**~~Vercel~~**](https://vercel.com) for built-in edge caching. Configure `**generateStaticParams**` for static generation. Add ISR with `**revalidate**` for dynamic content that changes infrequently.

```ts
export const revalidate = 3600 // ISR every hour
```

**Nuxt**: Configure `**routeRules**` for per-route caching strategies. Use `**prerenderRoutes**` for static paths. Deploy to [**~~Cloudflare~~**](https://cloudflare.com) or Vercel for edge rendering. Enable `**experimental.componentIslands**` for partial hydration.

```ts
export default defineNuxtConfig({
  routeRules: {
    '/blog/**': { swr: 3600 },
    '/': { prerender: true },
  },
})
```

## Verify the fix

After implementing changes:

1. Clear all caches (CDN, server, browser)
2. Run the curl command from multiple geographic locations
3. Use WebPageTest with test locations matching your user base
4. Run Lighthouse and confirm the "Reduce initial server response time" audit passes
5. Monitor Real User Monitoring (RUM) data for TTFB improvements over 24-48 hours

**Expected improvement**: Reducing TTFB from 2000ms to 400ms should improve LCP by approximately 1600ms, often the difference between failing and passing Core Web Vitals.

## Common mistakes

**Over-caching personalized content**: Caching user-specific pages at the CDN edge causes users to see each other's data. Use `**Cache-Control: private**` for authenticated pages, or implement edge-side personalization with cookies.

**Ignoring cold starts**: Serverless functions can add 500ms+ on cold start. Monitor cold start frequency separately from average TTFB. Use provisioned concurrency or edge functions with faster cold starts.

**Missing cache invalidation**: Aggressive caching without proper invalidation serves stale content. Implement cache tags or surrogate keys for targeted purging when content updates.

## Related issues

TTFB problems often compound with other LCP issues:

- [**~~Render-Blocking Resources~~**](https://unlighthouse.dev/learn-lighthouse/lcp/render-blocking-resources) - Both delay the critical rendering path
- [**~~Redirects~~**](https://unlighthouse.dev/learn-lighthouse/lcp/redirects) - Each redirect adds another full TTFB cycle
- [**~~Client-Side Rendering~~**](https://unlighthouse.dev/learn-lighthouse/lcp/client-side-rendering) - SSR with slow TTFB is still slow

## Test your entire site

TTFB varies across pages - your homepage may be fast while product pages with database queries are slow. Run a complete scan to identify which routes have server response problems before they impact real users.

[Scan Your Site with Unlighthouse](https://unlighthouse.dev/)

### **Related **

[**LCP Overview**](https://unlighthouse.dev/learn-lighthouse/lcp) [**All LCP Issues**](https://unlighthouse.dev/learn-lighthouse/lcp#common-lcp-issues) [**LCP Definition**](https://unlighthouse.dev/glossary/lcp) [**LCP Finder Tool**](https://unlighthouse.dev/tools/lcp-finder) [**TTFB Checker Tool**](https://unlighthouse.dev/tools/ttfb-checker)

[**LCP** LCP measures when the main content loads. Good score: ≤2.5s mobile. Fix slow LCP with image optimization, TTFB improvements, and render-blocking resource removal.](https://unlighthouse.dev/learn-lighthouse/lcp) [**Total Byte Weight** How to reduce total page weight and avoid enormous network payloads that slow down your Largest Contentful Paint.](https://unlighthouse.dev/learn-lighthouse/lcp/total-byte-weight)

**On this page **

- [What's the problem?](#whats-the-problem)
- [How to identify this issue](#how-to-identify-this-issue)
- [The fix](#the-fix)
- [Why this works](#why-this-works)
- [Framework-specific solutions](#framework-specific-solutions)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Eliminate Render-Blocking Resources: Lighthouse Audit Fix · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/lcp/render-blocking-resources
- **Description:** How to eliminate render-blocking CSS and JavaScript in the Lighthouse audit. Async/defer scripts, critical CSS extraction, font loading, and Next.js optimizeCss config.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Eliminate Render-Blocking Resources: Lighthouse Audit Fix**

How to eliminate render-blocking CSS and JavaScript in the Lighthouse audit. Async/defer scripts, critical CSS extraction, font loading, and Next.js optimizeCss config.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)8 min read Published **Jan 18, 2025**

Render-blocking resources prevent the browser from painting anything - even when your LCP element is fully downloaded and ready. The median website loads 7 render-blocking resources totaling 100KB+, adding 500-1500ms to LCP on typical mobile connections.

**LCP**Largest Contentful Paint** CWV **

**25% weight **

Good ≤2.5sPoor >4.0s

## What's the problem?

Browsers follow a strict rule: no pixels appear on screen until all render-blocking resources finish loading. CSS is render-blocking by default because the browser needs styles to know what to paint. Synchronous JavaScript is parser-blocking, which halts HTML processing until the script executes.

The impact is severe. Your LCP image might download in 200ms, but if 300KB of CSS is still loading, users see nothing. The browser has the content; it refuses to display it. This creates an invisible delay that compounds with every additional blocking resource in the critical path.

Lighthouse flags this as "Eliminate render-blocking resources" and calculates the potential time savings. The audit identifies CSS files loaded in the `**<head>**` without `**media**` attributes and JavaScript files without `**async**` or `**defer**`. Each blocking resource in the chain extends the time before First Contentful Paint and LCP.

## How to identify this issue

### Chrome DevTools

1. Open DevTools (F12) and go to the Performance tab
2. Click Record, then reload the page
3. Look at the Main thread flame chart
4. Long pink/purple bars before "First Paint" indicate blocking resources
5. The Network waterfall shows which resources block rendering with a vertical blue line

### Command line

```bash
npx lighthouse https://your-site.com --only-audits=render-blocking-resources --output=json | jq '.audits["render-blocking-resources"]'

curl -sI https://your-site.com/styles.css | grep -i content-length
```

### Lighthouse indicators

Look for "Eliminate render-blocking resources" under Opportunities. Lighthouse shows:

- Each blocking URL
- Transfer size in bytes
- Wasted time in milliseconds

The audit calculates savings based on how much faster FCP and LCP could occur if resources loaded asynchronously.

## The fix

### Primary: async/defer scripts

Never load JavaScript synchronously in the `**<head>**` unless necessary.

```html
<!-- Before: blocking -->
<head>
  <script src="analytics.js"></script>
  <script src="app.js"></script>
</head>

<!-- After: non-blocking -->
<head>
  <script src="analytics.js" async></script>
  <script src="app.js" defer></script>
</head>
```

**Choosing between `**async**` and `**defer**`:**

```html
<!-- async: downloads in parallel, executes immediately when ready -->
<!-- Use for independent scripts like analytics, ads -->
<script src="analytics.js" async></script>

<!-- defer: downloads in parallel, executes after HTML parsing, maintains order -->
<!-- Use for app code that depends on DOM or other scripts -->
<script src="vendor.js" defer></script>
<script src="app.js" defer></script>
```

For inline scripts that can run later:

```html
<script>
  // Defer execution until after DOMContentLoaded
  document.addEventListener('DOMContentLoaded', () => {
    initializeNonCriticalFeatures()
  })
</script>
```

### Secondary: critical CSS extraction

Extract only the CSS needed for above-the-fold content and inline it directly in the HTML.

```html
<head>
  <!-- Critical CSS inlined -->
  <style>
    /* Only styles for above-the-fold content */
    :root { --primary: #0066cc; }
    body { margin: 0; font-family: system-ui; }
    .header { height: 60px; background: var(--primary); }
    .hero { padding: 2rem; }
    .hero-image { width: 100%; height: auto; }
  </style>

  <!-- Full CSS loaded asynchronously -->
  <link rel="preload" href="styles.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
  <noscript><link rel="stylesheet" href="styles.css"></noscript>
</head>
```

Automate critical CSS extraction:

```bash
npx critical https://your-site.com --inline --minify > index-critical.html

npm install critters-webpack-plugin --save-dev
```

```js
// webpack.config.js
import Critters from 'critters-webpack-plugin'

export default {
  plugins: [
    new Critters({
      preload: 'swap',
      inlineThreshold: 0,
    }),
  ],
}
```

### Tertiary: font loading strategy

Web fonts can block text rendering for up to 3 seconds on slow connections. Use `**font-display: swap**` to show fallback text immediately.

```css
@font-face {
  font-family: 'Custom Font';
  src: url('/fonts/custom.woff2') format('woff2');
  font-display: swap;
}
```

Preload critical fonts:

```html
<head>
  <link rel="preload" href="/fonts/custom.woff2" as="font" type="font/woff2" crossorigin>
</head>
```

For Google Fonts, add the `**display=swap**` parameter:

```html
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap" rel="stylesheet">
```

### Bonus: split large CSS files

Break monolithic CSS into route-specific chunks:

```html
<!-- Load base styles everywhere -->
<link rel="stylesheet" href="base.css">

<!-- Load page-specific styles only where needed -->
<link rel="stylesheet" href="product-page.css" media="print" onload="this.media='all'">
```

```js
// Dynamic CSS loading in JavaScript
document.getElementById('modal-trigger').addEventListener('click', () => {
  import('./modal.css')
  showModal()
})
```

## Why this works

Eliminating render-blocking resources allows the browser to start painting immediately after it processes critical CSS. The browser no longer waits for external stylesheets or JavaScript before displaying content. With async/defer scripts, JavaScript downloads in parallel without blocking HTML parsing. With inlined critical CSS, the browser has everything it needs to paint above-the-fold content in the initial HTML response. This removes artificial delays between resource availability and visual rendering.

## Framework-specific solutions

### Next.js optimizecss

**Next.js**: The framework automatically code-splits JavaScript by route. For CSS, use CSS Modules or styled-jsx for component-scoped styles. Enable experimental `**optimizeCss**` in `**next.config.js**` for automatic critical CSS extraction.

```js
// next.config.js
const config2 = {
  experimental: {
    optimizeCss: true,
  },
}
```

**Nuxt**: Enable inline SSR styles for automatic critical CSS. Use component-level styles with `**<style scoped>**`. Configure font loading with `**@nuxt/fonts**` for optimal font-display settings.

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    inlineSSRStyles: true,
  },
  fonts: {
    defaults: {
      display: 'swap',
    },
  },
})
```

## Verify the fix

After implementing changes:

1. Run Lighthouse and check that "Eliminate render-blocking resources" shows 0 items or passes
2. Open Performance tab - First Paint should occur earlier in the timeline
3. Verify no layout shift from font loading (check CLS score)
4. Test with network throttling (Slow 3G) to see real-world impact
5. Compare before/after screenshots at key time intervals using WebPageTest filmstrip

**Expected improvement**: Removing 200KB of render-blocking CSS and deferring 100KB of JavaScript typically saves 300-800ms on LCP for 4G mobile connections.

## Common mistakes

**Inlining too much CSS**: Critical CSS should be 14KB or less (fits in first TCP roundtrip). Inline only above-the-fold styles; load the rest asynchronously. Excessive inline CSS increases HTML size and hurts TTFB.

**Breaking functionality with defer**: Some legacy scripts expect synchronous execution and access to DOM elements that haven't parsed yet. Test thoroughly after adding `**defer**`. Use `**DOMContentLoaded**` listeners instead of relying on script position.

**Missing fallback fonts**: Using `**font-display: swap**` without specifying fallback fonts causes layout shift when custom fonts load. Define fallback font stacks that closely match your custom font metrics:

```css
font-family: 'Custom Font', system-ui, -apple-system, sans-serif;
```

## Related issues

Render-blocking resources often combine with other LCP problems:

- [**~~Slow Server Response~~**](https://unlighthouse.dev/learn-lighthouse/lcp/slow-server-response) - Both delay the critical rendering path
- [**~~Resource Load Delay~~**](https://unlighthouse.dev/learn-lighthouse/lcp/resource-load-delay) - Blocking resources delay discovery of LCP elements
- [**~~Large Images~~**](https://unlighthouse.dev/learn-lighthouse/lcp/large-images) - Even optimized images wait for blocking resources

## Test your entire site

Different page templates have different blocking resources. Your blog might inline critical CSS while your product pages load three external stylesheets. Run a complete audit to find render-blocking issues across every template.

[Scan Your Site with Unlighthouse](https://unlighthouse.dev/)

### **Related **

[**LCP Overview**](https://unlighthouse.dev/learn-lighthouse/lcp) [**All LCP Issues**](https://unlighthouse.dev/learn-lighthouse/lcp#common-lcp-issues) [**LCP Definition**](https://unlighthouse.dev/glossary/lcp) [**Bulk PageSpeed Test**](https://unlighthouse.dev/tools/bulk-pagespeed) [**Speed Index**](https://unlighthouse.dev/glossary/speed-index)

[**LCP Best Practices 2026** A practical 2026 LCP playbook using Lighthouse 13 Insights, Priority Hints, early resource discovery, modern images, and field data.](https://unlighthouse.dev/learn-lighthouse/lcp/best-practices-2026) [**Prioritize LCP Image** Add fetchpriority='high' and preload your LCP image. 85% of sites miss this — one attribute can cut LCP by 100-400ms.](https://unlighthouse.dev/learn-lighthouse/lcp/prioritize-lcp-image)

**On this page **

- [What's the problem?](#whats-the-problem)
- [How to identify this issue](#how-to-identify-this-issue)
- [The fix](#the-fix)
- [Why this works](#why-this-works)
- [Framework-specific solutions](#framework-specific-solutions)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Preload &amp; Prioritize Your LCP Image · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/lcp/prioritize-lcp-image
- **Description:** Add fetchpriority='high' and preload your LCP image. 85% of sites miss this — one attribute can cut LCP by 100-400ms.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Preload & Prioritize Your LCP Image**

Add fetchpriority='high' and preload your LCP image. 85% of sites miss this — one attribute can cut LCP by 100-400ms.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)6 min read Published **Jan 18, 2025**

Only [**~~15% of sites use fetchpriority="high"~~**](https://almanac.httparchive.org/en/2024/performance) on their LCP image - up from 0.03% in 2022. The other 85% leave performance on the table.

## What's the problem?

When browsers load a page, they prioritize resources based on type and position. Images start with low priority by default. Your hero image, the most important visual element, competes with analytics scripts, third-party widgets, and other low-priority requests.

The browser doesn't know which image is your LCP element until it calculates layout. By then, precious milliseconds are wasted. The "Prioritize LCP image" audit fires when Lighthouse detects your LCP image could have loaded faster with explicit prioritization.

This audit specifically checks two things: whether the LCP image has `**fetchpriority="high"**` applied, and whether the image is discoverable in the initial HTML (not loaded via JavaScript or CSS).

## How to identify this issue

### Chrome DevTools

1. Open DevTools (F12) → Performance tab
2. Record a page load
3. Find your LCP marker in the timeline
4. Look at the Network section - when did the LCP image request start?
5. If there's a gap between HTML arrival and image request, prioritization helps

### Lighthouse

Look for: "Prioritize LCP image" in the Opportunities section. The audit shows:

- Which image is your LCP element
- Whether you've applied fetchpriority
- Whether the image is discoverable from HTML

### Quick check

View page source. Search for your hero image. Check:

- Does it have `**fetchpriority="high"**`?
- Is the URL in the HTML, or set by JavaScript/CSS?

## The fix

### Primary solution: add fetchpriority="high"

The simplest fix. Tell the browser this image matters.

```html
<!-- Before: browser guesses priority -->
<img src="hero.webp" alt="Hero image">

<!-- After: explicit high priority -->
<img src="hero.webp" fetchpriority="high" alt="Hero image">
```

This single attribute can reduce LCP by 100-400ms on typical pages.

### Secondary solution: preload the LCP image

When the image URL isn't immediately discoverable (e.g., set by CSS background), preload it.

```html
<head>
  <link
    rel="preload"
    href="/images/hero.webp"
    as="image"
    fetchpriority="high"
  >
</head>
```

For responsive images with srcset:

```html
<link
  rel="preload"
  as="image"
  href="/images/hero.webp"
  imagesrcset="
    /images/hero-400.webp 400w,
    /images/hero-800.webp 800w,
    /images/hero-1200.webp 1200w
  "
  imagesizes="100vw"
  fetchpriority="high"
>
```

### Make the image discoverable

Move LCP images from CSS/JavaScript to HTML.

```html
<!-- Before: image URL hidden in CSS (not discoverable) -->
<div class="hero" style="background-image: url(hero.webp)"></div>

<!-- After: image in HTML (immediately discoverable) -->
<img src="hero.webp" class="hero-img" fetchpriority="high" alt="Hero">
```

```jsx
// Before: image URL set after component mounts
function Hero() {
  const [heroSrc, setHeroSrc] = useState(null)
  useEffect(() => {
    setHeroSrc('/hero.webp')
  }, [])
  return <img src={heroSrc} />
}

// After: image URL known at render time
function HeroNew() {
  return <img src="/hero.webp" fetchPriority="high" alt="Hero" />
}
```

### Complete example

```html
<head>
  <!-- Preload for earliest possible discovery -->
  <link
    rel="preload"
    href="/images/hero.webp"
    as="image"
    fetchpriority="high"
    imagesrcset="
      /images/hero-400.webp 400w,
      /images/hero-800.webp 800w
    "
    imagesizes="100vw"
  >
</head>
<body>
  <img
    src="/images/hero.webp"
    srcset="
      /images/hero-400.webp 400w,
      /images/hero-800.webp 800w
    "
    sizes="100vw"
    fetchpriority="high"
    loading="eager"
    decoding="async"
    width="1200"
    height="600"
    alt="Descriptive alt text"
  >
</body>
```

## Why this works

The browser's resource scheduler assigns priority to each request. By default:

- Scripts: High
- Stylesheets: Highest
- Images in viewport: Low → Medium (after layout)
- Images outside viewport: Low

`**fetchpriority="high"**` overrides this. The browser:

1. Sees the image immediately in HTML
2. Knows it's high priority before layout calculation
3. Starts downloading sooner, potentially in parallel with critical CSS

Preload goes further - it starts the request during HTML parsing, before the browser even reaches the `**<img>**` tag.

The combination of discoverable HTML + fetchpriority + preload can eliminate 500ms+ of resource load delay.

## Framework-specific solutions

**Next.js**

Use the `**priority**` prop on `**next/image**`. This adds both fetchpriority and preload automatically:

```jsx
import Image from 'next/image'

// priority adds fetchpriority="high" and preloads the image
export function HeroImage() {
  return (
    <Image
      src="/hero.jpg"
      width={1200}
      height={600}
      priority
      alt="Hero"
    />
  )
}
```

Only use `**priority**` on above-the-fold images - typically the LCP image.

**Nuxt**

Use `**preload**` prop on `**NuxtImg**` to generate a preload link:

```html
<NuxtImg
  src="/hero.jpg"
  width="1200"
  height="600"
  preload
  alt="Hero"
/>
```

For manual control with `**useHead**`:

```ts
useHead({
  link: [{
    rel: 'preload',
    href: '/images/hero.webp',
    as: 'image',
    fetchpriority: 'high'
  }]
})
```

**React**

Add `**fetchPriority**` (camelCase in JSX) directly to your img:

```jsx
<img
  src="/hero.webp"
  fetchPriority="high"
  loading="eager"
  alt="Hero"
/>
```

For preload, add to your HTML head or use a head management library like react-helmet.

## Verify the fix

After implementing:

1. **Network tab**: Filter by "Img". LCP image should show "High" in Priority column
2. **Elements tab**: Check that fetchpriority="high" is present on the LCP image
3. **Performance tab**: Record and verify the LCP image request starts earlier
4. **Lighthouse**: The "Prioritize LCP image" audit should pass

**Expected improvement:** 100-500ms reduction in LCP, depending on page complexity and network conditions.

## Common mistakes

### Preloading the wrong image

Preload hints are powerful but wasteful if used incorrectly.

```html
<!-- Wrong: preloading a below-fold image -->
<link rel="preload" href="/product-gallery.webp" as="image">

<!-- Right: only preload the actual LCP image -->
<link rel="preload" href="/hero.webp" as="image" fetchpriority="high">
```

### Too many high-priority images

If everything is high priority, nothing is.

```html
<!-- Wrong: multiple high-priority images -->
<img src="hero.webp" fetchpriority="high" alt="">
<img src="logo.webp" fetchpriority="high" alt="">
<img src="banner.webp" fetchpriority="high" alt="">

<!-- Right: only the LCP image gets high priority -->
<img src="hero.webp" fetchpriority="high" alt="">
<img src="logo.webp" alt="">
<img src="banner.webp" alt="">
```

### Preload with incorrect attributes

Missing or wrong attributes cause double downloads.

```html
<!-- Wrong: missing 'as' attribute -->
<link rel="preload" href="/hero.webp">

<!-- Wrong: mismatched srcset -->
<link rel="preload" as="image" imagesrcset="hero-800.webp 800w">
<img srcset="hero-400.webp 400w, hero-800.webp 800w"> <!-- Different srcset! -->

<!-- Right: matching attributes -->
<link rel="preload" as="image"
  imagesrcset="hero-400.webp 400w, hero-800.webp 800w"
  imagesizes="100vw">
<img srcset="hero-400.webp 400w, hero-800.webp 800w" sizes="100vw">
```

### Dynamic LCP images without server-side logic

If your LCP image varies per page, you need server-side rendering to set the correct preload.

```html
<!-- Wrong: hardcoded preload on dynamic pages -->
<link rel="preload" href="/default-hero.webp" as="image">
<!-- But this page's LCP is actually /product-42-hero.webp -->

<!-- Right: dynamic preload matching actual LCP -->
<link rel="preload" href="/product-42-hero.webp" as="image">
```

## Related issues

Often appears alongside:

- [**~~Large Images~~**](https://unlighthouse.dev/learn-lighthouse/lcp/large-images) - Prioritizing a 2MB image still means downloading 2MB
- [**~~Lazy-Loading Above Fold~~**](https://unlighthouse.dev/learn-lighthouse/lcp/lazy-loading-above-fold) - Don't combine fetchpriority="high" with loading="lazy"
- [**~~Render-Blocking Resources~~**](https://unlighthouse.dev/learn-lighthouse/lcp/render-blocking-resources) - Even with priority, blocking CSS delays render

## Test your entire site

Different pages have different LCP elements. Your homepage might use a hero image while product pages use product photos. [**~~Unlighthouse~~**](https://unlighthouse.dev/) scans your entire site and identifies which pages are missing LCP image prioritization.

### **Related **

[**LCP Overview**](https://unlighthouse.dev/learn-lighthouse/lcp) [**All LCP Issues**](https://unlighthouse.dev/learn-lighthouse/lcp#common-lcp-issues) [**LCP Definition**](https://unlighthouse.dev/glossary/lcp) [**LCP Finder Tool**](https://unlighthouse.dev/tools/lcp-finder)

[**Render-Blocking Resources** How to eliminate render-blocking CSS and JavaScript in the Lighthouse audit. Async/defer scripts, critical CSS extraction, font loading, and Next.js optimizeCss config.](https://unlighthouse.dev/learn-lighthouse/lcp/render-blocking-resources) [**Resource Load Delay** How to reduce resource load delay by preloading LCP resources and prioritizing critical assets.](https://unlighthouse.dev/learn-lighthouse/lcp/resource-load-delay)

**On this page **

- [What's the problem?](#whats-the-problem)
- [How to identify this issue](#how-to-identify-this-issue)
- [The fix](#the-fix)
- [Why this works](#why-this-works)
- [Framework-specific solutions](#framework-specific-solutions)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Don&#x27;t Lazy-Load Your LCP Image · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/lcp/lcp-lazy-loaded
- **Description:** Remove loading='lazy' from hero images. Lazy-loading your LCP image adds 500ms+ delay. Fix with eager loading and fetchpriority='high'.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Don't Lazy-Load Your LCP Image**

Remove loading='lazy' from hero images. Lazy-loading your LCP image adds 500ms+ delay. Fix with eager loading and fetchpriority='high'.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)5 min read Published **Jan 18, 2025**

[**~~10% of pages lazy-load their LCP image~~**](https://almanac.httparchive.org/en/2024/performance). This single mistake can add 500ms+ to your LCP.

## What's the problem?

`**loading="lazy"**` is a performance optimization - for images below the fold. It tells browsers to defer downloading images until they're near the viewport. This saves bandwidth and speeds up initial load.

But your LCP image is already in the viewport. It's the first thing users see. Lazy-loading it creates this sequence:

1. Browser parses HTML, sees `**loading="lazy"**`, skips the image
2. Browser downloads CSS, JavaScript, other resources
3. Browser calculates layout
4. Browser realizes the image is in viewport
5. **Now** browser starts downloading the image
6. LCP fires after unnecessary delay

The "Largest Contentful Paint image was lazily loaded" audit catches this anti-pattern. It's one of the easiest LCP issues to fix - remove an attribute.

### The anti-pattern

This happens constantly with hero images:

```html
<!-- The classic mistake: lazy-loading the hero -->
<section class="hero">
  <img
    src="hero.webp"
    loading="lazy"  <!-- This destroys your LCP -->
    alt="Welcome to our site"
  >
</section>
```

While some developers apply `**loading="lazy"**` to every image as a "best practice," it is a targeted optimization for below-the-fold content only.

## How to identify this issue

### Chrome DevTools

1. Open Elements panel (F12)
2. Find your LCP image (usually the largest visible image)
3. Check if it has `**loading="lazy"**`

### Lighthouse

The audit is explicit: "Largest Contentful Paint image was lazily loaded"

It tells you:

- Which element is your LCP
- That it has `**loading="lazy"**` (or equivalent JavaScript lazy-loading)

### Performance panel

1. Record a page load
2. Find the LCP marker
3. Look at when the LCP image request started
4. Large gap after HTML = likely lazy-load issue

### Quick check

View page source, search for your hero image URL, check for `**loading="lazy"**`.

## The fix

### Primary solution: remove loading="lazy"

```html
<!-- Before: lazy-loaded LCP image -->
<img src="hero.webp" loading="lazy" alt="Hero">

<!-- After: default eager loading -->
<img src="hero.webp" alt="Hero">
```

That's it. `**loading="eager"**` is the default. You don't need to specify it.

### Add fetchpriority for maximum impact

While you're at it, tell the browser this image is critical:

```html
<img
  src="hero.webp"
  fetchpriority="high"
  alt="Hero"
>
```

### Complete pattern: above vs below fold

```html
<!-- Above the fold: LCP image -->
<header>
  <img
    src="hero.webp"
    fetchpriority="high"
    decoding="async"
    width="1200"
    height="600"
    alt="Hero"
  >
</header>

<!-- Below the fold: lazy load these -->
<section class="products">
  <img src="product-1.webp" loading="lazy" alt="Product 1">
  <img src="product-2.webp" loading="lazy" alt="Product 2">
  <img src="product-3.webp" loading="lazy" alt="Product 3">
</section>
```

### Fix JavaScript lazy-loading libraries

If you use a library like lazysizes, vanilla-lazyload, or lozad, exclude above-fold images.

```html
<!-- Before: library lazy-loads everything -->
<img data-src="hero.webp" class="lazyload" alt="Hero">

<!-- After: real src, no lazy class -->
<img src="hero.webp" fetchpriority="high" alt="Hero">
```

```js
// If using Intersection Observer directly
const observer = new IntersectionObserver(loadImage)

// Don't observe the hero image
document.querySelectorAll('img[data-src]').forEach((img) => {
  if (!img.closest('.hero')) {
    observer.observe(img)
  }
})
```

### Fix native lazy-loading applied globally

Common mistake: CSS or JavaScript that adds lazy loading to all images.

```js
// Wrong: blanket lazy-loading
document.querySelectorAll('img').forEach((img) => {
  img.loading = 'lazy'
})

// Right: skip above-fold images
document.querySelectorAll('img').forEach((img) => {
  if (!img.hasAttribute('fetchpriority')) {
    img.loading = 'lazy'
  }
})
```

## Why this works

Native lazy-loading uses the browser's own heuristics to determine when to load images. When you add `**loading="lazy"**`:

1. The browser delays the fetch until it calculates the layout
2. It checks if the image is within a "distance threshold" of the viewport
3. Only then does it start the download

For images already visible, this adds latency:

- Layout calculation time (50-200ms)
- Intersection Observer overhead (10-50ms)
- Network request queuing

Removing lazy-loading means the browser starts downloading immediately during HTML parsing - exactly what you want for critical content.

The combination of removing lazy-load and adding fetchpriority can improve LCP by 200-800ms on image-heavy pages.

## Framework-specific solutions

**Next.js**

`**next/image**` lazy-loads by default. Use `**priority**` to override:

```jsx
// Wrong: lazy by default
export const HeroImageLazy = () => <Image src="/hero.jpg" alt="Hero" width={1200} height={600} />

// Right: priority disables lazy loading
export const HeroImagePriority = () => <Image src="/hero.jpg" alt="Hero" width={1200} height={600} priority />
```

The `**priority**` prop:

- Sets loading="eager"
- Adds fetchpriority="high"
- Creates a preload hint

Only use on the LCP image. One image per page should have `**priority**`.

**Nuxt**

`**NuxtImg**` and `**NuxtPicture**` lazy-load by default. Override with `**loading="eager"**`:

```html
<!-- Wrong: lazy by default -->
<NuxtImg src="/hero.jpg" alt="Hero" />

<!-- Right: eager loading for LCP -->
<NuxtImg
  src="/hero.jpg"
  alt="Hero"
  loading="eager"
  preload
/>
```

The `**preload**` prop adds a link rel="preload" for even faster loading.

**React**

Watch for lazy-loading libraries and HOCs:

```jsx
// Wrong: react-lazy-load-image-component on LCP
import { LazyLoadImage } from 'react-lazy-load-image-component'

export const LazyHero = () => <LazyLoadImage src="/hero.jpg" />

// Right: regular img for LCP
export const RealHero = () => <img src="/hero.jpg" fetchPriority="high" alt="Hero" />

// Use lazy-loading library only for below-fold
export const LazyProduct = () => <LazyLoadImage src="/product.jpg" />
```

**WordPress**

WordPress adds `**loading="lazy"**` to all images by default since 5.5. For LCP images:

```php
// Option 1: Remove lazy from specific images
add_filter('wp_img_tag_add_loading_attr', function($value, $image, $context) {
  if (strpos($image, 'hero') !== false) {
    return false;
  }
  return $value;
}, 10, 3);

// Option 2: Disable on featured images
add_filter('wp_img_tag_add_loading_attr', function($value, $image, $context) {
  if ($context === 'the_content' && is_singular()) {
    return false; // Let theme control loading
  }
  return $value;
}, 10, 3);
```

## Verify the fix

After implementing:

1. **Elements panel**: LCP image should NOT have `**loading="lazy"**`
2. **Network tab**: LCP image should start downloading early (not waiting for layout)
3. **Lighthouse**: "Largest Contentful Paint image was lazily loaded" warning should be gone
4. **Performance panel**: LCP image request should start sooner in the waterfall

**Expected improvement:** 100-500ms depending on image size and page complexity.

## Common mistakes

### Only removing the attribute

Removing `**loading="lazy"**` helps, but combine with `**fetchpriority="high"**` for maximum impact.

```html
<!-- Okay: removed lazy -->
<img src="hero.webp" alt="Hero">

<!-- Better: eager + priority -->
<img src="hero.webp" fetchpriority="high" alt="Hero">
```

### Cms or theme overriding your fix

Your CMS or theme might re-add lazy loading. Test the rendered HTML, not just your source.

```bash
curl -s https://yoursite.com | grep -A2 'hero.webp'
```

### Build tools adding lazy loading

Some build tools or plugins add lazy loading automatically. Check your build config.

```js
// webpack.config.js or similar
// Look for image optimization plugins that add loading="lazy"
```

### Forgetting mobile

Mobile layout might have a different LCP image than desktop. Test both.

```html
<!-- Desktop LCP might be hero-desktop.webp -->
<!-- Mobile LCP might be hero-mobile.webp -->
<!-- Both need eager loading -->
<picture>
  <source media="(max-width: 768px)" srcset="hero-mobile.webp">
  <img src="hero-desktop.webp" fetchpriority="high" alt="Hero">
</picture>
```

## Related issues

Often appears alongside:

- [**~~Prioritize LCP Image~~**](https://unlighthouse.dev/learn-lighthouse/lcp/prioritize-lcp-image) - The positive version of this fix
- [**~~Large Images~~**](https://unlighthouse.dev/learn-lighthouse/lcp/large-images) - An eagerly-loaded 2MB image is still slow
- [**~~Client-Side Rendering~~**](https://unlighthouse.dev/learn-lighthouse/lcp/client-side-rendering) - JavaScript-rendered images have similar discovery delays

## Test your entire site

Different page templates have different lazy-loading behavior. Your blog posts might be fine while product pages lazy-load heroes. [**~~Unlighthouse~~**](https://unlighthouse.dev/) scans your entire site and identifies every page with lazy-loaded LCP images.

### **Related **

[**LCP Overview**](https://unlighthouse.dev/learn-lighthouse/lcp) [**All LCP Issues**](https://unlighthouse.dev/learn-lighthouse/lcp#common-lcp-issues) [**LCP Definition**](https://unlighthouse.dev/glossary/lcp) [**LCP Finder Tool**](https://unlighthouse.dev/tools/lcp-finder)

[**Client-Side Rendering** How to improve LCP by using server-side rendering or pre-rendering instead of client-side rendering.](https://unlighthouse.dev/learn-lighthouse/lcp/client-side-rendering) [**Large Images** Optimize LCP images with responsive srcset, modern formats like WebP and AVIF, and proper compression. Reduce image size without losing quality.](https://unlighthouse.dev/learn-lighthouse/lcp/large-images)

**On this page **

- [What's the problem?](#whats-the-problem)
- [How to identify this issue](#how-to-identify-this-issue)
- [The fix](#the-fix)
- [Why this works](#why-this-works)
- [Framework-specific solutions](#framework-specific-solutions)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** What is total blocking time (TBT)? · Unlighthouse
- **Source:** https://unlighthouse.dev/glossary/tbt
- **Description:** TBT measures main thread blocking during load. Learn what it is, thresholds, and how to reduce blocking time.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Glossary**

# **What is total blocking time (TBT)?**

[Copy for LLMs](https://unlighthouse.dev/glossary/tbt.md)

Total Blocking Time (TBT) is a Lighthouse lab metric. It adds up the blocking portions of long main-thread tasks between [**~~First Contentful Paint~~**](https://unlighthouse.dev/glossary/fcp) and Time to Interactive. TBT contributes **30%** of the Lighthouse Performance score.

## Thresholds

| **Score** | **Rating** |
| --- | --- |
| ≤ 200ms | Good |
| 200ms - 600ms | Needs Improvement |
| > 600ms | Poor |

## How Lighthouse calculates TBT

Any main-thread task longer than 50 milliseconds is a long task. Only the time beyond the first 50 milliseconds counts toward TBT:

- 70ms task → 20ms blocking time
- 250ms task → 200ms blocking time
- 30ms task → 0ms (under threshold)

For example, three tasks lasting 70ms, 250ms, and 30ms contribute 20ms + 200ms + 0ms, for a TBT of 220ms. The browser cannot promptly handle input while a long task occupies the main thread.

## TBT vs INP

| **Metric** | **When** | **Type** |
| --- | --- | --- |
| TBT | Startup, between FCP and TTI | Synthetic lab metric |
| [**~~INP~~**](https://unlighthouse.dev/glossary/inp) | User interactions throughout a visit | Field metric |

TBT is useful when a slow startup is likely to hurt responsiveness. It cannot measure INP because a Lighthouse run does not reproduce real interactions across a full visit. A page can have low TBT and poor INP when a menu, editor, or checkout action starts heavy work later.

## Why it matters

TBT has the largest weight in the Lighthouse Performance score. High TBT also points to startup work that can delay input, rendering, and hydration. Fixing it often improves several metrics, but the Lighthouse score is still a lab result from one controlled run.

## What causes high TBT

- Large JavaScript bundles
- Unoptimized third-party scripts
- Heavy framework hydration
- Repeated synchronous layout and style calculations
- Large JSON parsing or client-side rendering work

## How to diagnose TBT

Open the Chrome DevTools Performance panel and record a reload. Long tasks appear with red markers in the main-thread track. Expand the busiest task, then follow its call tree back to your code or a third-party script.

Lighthouse also groups related work into diagnostics. Start with JavaScript execution time, main-thread work, third parties, and unused JavaScript. The top-level TBT number tells you the size of the problem; the trace tells you what to change.

## How to reduce TBT

1. Remove code that does not need to run during startup.
2. Load route-specific and below-the-fold features later.
3. Split necessary work into smaller tasks so the browser can handle input and paint between chunks.
4. Move CPU-heavy pure computation to a Web Worker when it does not need DOM access.
5. Delay or remove third-party scripts, then measure their cost again.

Do not split work blindly. More scheduling overhead can make total completion slower. Fix the largest trace entries first and rerun the same test several times.

## Measure TBT

- Lighthouse in Chrome DevTools
- [**~~PageSpeed Insights~~**](https://pagespeed.web.dev/) (lab data section)
- WebPageTest

Use the same device, throttling, Chrome version, and URL when comparing builds. CPU speed has a large effect on TBT, so scores from a laptop and a shared CI runner are not directly comparable.

TBT is a lab metric. Verify responsiveness with [**~~INP~~**](https://unlighthouse.dev/glossary/inp) from CrUX or your own real-user monitoring.

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/tbt.md)

[Markdown For LLMs](https://unlighthouse.dev/glossary/tbt.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/tbt.md) on GitHub or provide anonymous feedback below.

### **Related **

[**Interaction to Next Paint (INP)**](https://unlighthouse.dev/glossary/inp) [**First Contentful Paint (FCP)**](https://unlighthouse.dev/glossary/fcp) [**INP Guide**](https://unlighthouse.dev/learn-lighthouse/inp)

[**Speed Index** Speed Index (SI) measures how fast visible content fills the viewport. Good: ≤3.4s mobile, ≤1.3s desktop. 10% of Lighthouse performance score. Thresholds, tools, fixes.](https://unlighthouse.dev/glossary/speed-index) [**TTFB** TTFB measures server response time. Learn what it is, thresholds, and how to optimize it.](https://unlighthouse.dev/glossary/ttfb)

**On this page **

- [Thresholds](#thresholds)
- [How Lighthouse calculates TBT](#how-lighthouse-calculates-tbt)
- [TBT vs INP](#tbt-vs-inp)
- [Why it matters](#why-it-matters)
- [What causes high TBT](#what-causes-high-tbt)
- [How to diagnose TBT](#how-to-diagnose-tbt)
- [How to reduce TBT](#how-to-reduce-tbt)
- [Measure TBT](#measure-tbt)

---

- **Page:** Fix Web Fonts Causing Layout Shifts (FOIT&#x2F;FOUT) · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/cls/web-fonts-causing-foit
- **Description:** How to prevent layout shifts from web font loading using font-display, preloading, and fallback metrics.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Web Fonts Causing Layout Shifts (FOIT/FOUT)**

How to prevent layout shifts from web font loading using font-display, preloading, and fallback metrics.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)6 min read Published **Jan 12, 2025**

Text resizes when custom fonts load, shifting surrounding content. [**~~Only 11% of pages preload web fonts~~**](https://almanac.httparchive.org/en/2024/performance) to prevent this.

## What's the problem?

When a web font loads, text rendered with the fallback font gets re-rendered with the new font. If the fonts have different metrics (size, line-height, letter-spacing), the text changes size and shifts surrounding content.

**FOIT (Flash of Invisible Text):** Text is hidden until font loads, then appears - can cause shift if layout changes.

**FOUT (Flash of Unstyled Text):** Fallback font shows first, then swaps to custom font - causes shift if metrics differ.

## How to identify this issue

### Chrome DevTools

1. Network tab → filter by "Font"
2. Throttle to "Slow 3G"
3. Reload and watch for text reflow

### Visual test

Disable caching (DevTools → Network → Disable cache) and reload. Watch the text as fonts load.

## The fix

### 1. use font-display: optional

The safest option for CLS - uses fallback permanently if font doesn't load fast:

```css
@font-face {
  font-family: 'CustomFont';
  src: url('font.woff2') format('woff2');
  font-display: optional; /* No layout shift guaranteed */
}
```

**How `**font-display**` values work:**

| **Value** | **Behavior** | **CLS Risk** |
| --- | --- | --- |
| `**auto**` | Browser decides | High |
| `**block**` | Hide text up to 3s, then swap | Medium |
| `**swap**` | Show fallback immediately, swap when ready | High |
| `**fallback**` | Short block (100ms), then fallback, swap if fast | Low |
| `**optional**` | short block, no swap if slow | None |

### 2. match fallback font metrics

Adjust your fallback font to match the custom font's metrics:

```css
@font-face {
  font-family: 'Adjusted Fallback';
  src: local('Arial');
  size-adjust: 105%;
  ascent-override: 95%;
  descent-override: 22%;
  line-gap-override: 0%;
}

body {
  font-family: 'CustomFont', 'Adjusted Fallback', sans-serif;
}
```

Use tools to generate these values:

- [**~~Fontaine~~**](https://github.com/unjs/fontaine) - Automatic fallback generation
- [**~~Font Style Matcher~~**](https://meowni.ca/font-style-matcher/) - Visual comparison tool

### 3. preload critical fonts

Tell the browser to download fonts early:

```html
<link
  rel="preload"
  href="/fonts/custom.woff2"
  as="font"
  type="font/woff2"
  crossorigin
>
```

**Important:** Browsers require the `**crossorigin**` attribute even for same-origin fonts to avoid downloading the font twice.

### 4. self-host fonts

Google Fonts and other CDNs add extra connection time. Self-hosting is faster:

```css
/* Instead of Google Fonts link */
@font-face {
  font-family: 'Inter';
  src: url('/fonts/inter.woff2') format('woff2');
  font-display: optional;
}
```

Download fonts from [**~~Google Webfonts Helper~~**](https://gwfh.mranftl.com/fonts) or the font provider.

### 5. subset fonts

Only include characters you need:

```bash
pyftsubset font.ttf --text="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789" --output-file=font-subset.woff2 --flavor=woff2
```

Smaller font files load faster, reducing the window for layout shifts.

## Framework-specific solutions

**Next.js**

Use `**next/font**` for automatic optimization and zero CLS:

```jsx
import { Inter } from 'next/font/google'

const inter = Inter({
  subsets: ['latin'],
  display: 'optional',
})

export default function Layout({ children }) {
  return (
    <html className={inter.className}>
      <body>{children}</body>
    </html>
  )
}
```

`**next/font**` automatically:

- Self-hosts fonts
- Generates fallback metrics
- Preloads fonts

**Nuxt**

Use `**@nuxt/fonts**` for automatic optimization:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
  fonts: {
    families: [
      { name: 'Inter', provider: 'google' }
    ]
  }
})
```

Or use Fontaine for fallback metrics:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxtjs/fontaine']
})
```

**Vue/Vite**

Use `**vite-plugin-fonts**` or Fontaine:

```ts
// vite.config.ts
import { FontaineTransform } from 'fontaine'

export default {
  plugins: [
    FontaineTransform.vite({
      fallbacks: ['Arial', 'sans-serif']
    })
  ]
}
```

## Verify the fix

After implementing:

1. Throttle network to Slow 3G
2. Reload with cache disabled
3. Watch for text reflow - there should be none
4. Compare CLS scores before/after

**Expected improvement:** Fixing font CLS can improve your score by 0.05-0.2 depending on how much text you have.

## Common mistakes

- **Forgetting crossorigin on preload**: Causes double download.
- **Too many font weights**: Each weight is a separate file. Only load what you use.
- **Using font-display: swap without fallback matching**: Swap guarantees a shift unless fallbacks match.

## Related issues

Often appears alongside:

- [**~~Unsized Images~~**](https://unlighthouse.dev/learn-lighthouse/cls/unsized-images) - Multiple small shifts add up
- [**~~Dynamic Content~~**](https://unlighthouse.dev/learn-lighthouse/cls/dynamic-content-injection) - Fonts loading in dynamic content

## Test your entire site

Font loading behavior can vary by page. [**~~Unlighthouse~~**](https://unlighthouse.dev/) scans your entire site and identifies pages with font-related CLS.

### **Related **

[**CLS Overview**](https://unlighthouse.dev/learn-lighthouse/cls) [**All CLS Issues**](https://unlighthouse.dev/learn-lighthouse/cls#common-cls-issues) [**CLS Definition**](https://unlighthouse.dev/glossary/cls) [**CLS Debugger Tool**](https://unlighthouse.dev/tools/cls-debugger)

[**Large Layout Shifts** Diagnose and fix layout shifts caused by CSS reflow, font-size changes, unsized media, web fonts, and injected iframes. Reduce your CLS score.](https://unlighthouse.dev/learn-lighthouse/cls/layout-shifts) [**Dynamic Content** Stop cookie banners, notifications, and lazy-loaded content from causing layout shifts with space reservation and transforms.](https://unlighthouse.dev/learn-lighthouse/cls/dynamic-content-injection)

**On this page **

- [What's the problem?](#whats-the-problem)
- [How to identify this issue](#how-to-identify-this-issue)
- [The fix](#the-fix)
- [Framework-specific solutions](#framework-specific-solutions)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix Client-Side Rendering for Better LCP · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/lcp/client-side-rendering
- **Description:** How to improve LCP by using server-side rendering or pre-rendering instead of client-side rendering.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Client-Side Rendering for Better LCP**

How to improve LCP by using server-side rendering or pre-rendering instead of client-side rendering.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)6 min read Published **Jan 12, 2025**

When content only appears after JavaScript runs, LCP is delayed until the JS downloads, parses, executes, and renders. This can add seconds to LCP.

## What's the problem?

Client-side rendering (CSR) means the server sends a minimal HTML shell, and JavaScript builds the actual content in the browser.

**The LCP timeline with CSR:**

1. Download HTML shell (fast)
2. Download JavaScript bundle (slow)
3. Parse and execute JavaScript (slow)
4. Fetch data from API (slow)
5. Render content (finally, LCP fires)

**With server-side rendering:**

1. Download HTML with content already included (LCP fires)

## How to identify this issue

### View page source

1. Right-click → "View Page Source"
2. Search for your main content text
3. If you can't find it, you're using client-side rendering

### Lighthouse

Look for:

- High "Total Blocking Time"
- Large "JavaScript execution time"
- LCP element rendered by JavaScript (shown in audit details)

### Chrome DevTools

1. Disable JavaScript: Settings → Debugger → Disable JavaScript
2. Reload the page
3. If your content disappears, it's client-side rendered

## The fix

### 1. use server-side rendering (SSR)

Render HTML on the server so content is available immediately.

```jsx
// Next.js - automatic SSR with App Router
export default async function Page() {
  const data = await fetchData() // Runs on server

  return <Content data={data} /> // HTML sent to browser
}
```

```html
<!-- Nuxt - automatic SSR -->
<script setup>
const { data } = await useFetch('/api/content')
</script>

<template>
  <Content :data="data" />
</template>
```

### 2. use static site generation (SSG)

Pre-render pages at build time for the fastest possible LCP.

```jsx
// Next.js - static generation
export async function generateStaticParams() {
  const posts = await getPosts()
  return posts.map(post => ({ slug: post.slug }))
}

export default async function Page({ params }) {
  const post = await getPost(params.slug)
  return <Article post={post} />
}
```

```ts
// Nuxt - static generation
export default defineNuxtConfig({
  routeRules: {
    '/blog/**': { prerender: true }
  }
})
```

### 3. streaming SSR

Send HTML progressively so users see content before the entire page is ready.

```jsx
// Next.js App Router - automatic streaming
import { Suspense } from 'react'

export default function Page() {
  return (
    <>
      <Header />
      {' '}
      {/* Sent immediately */}
      <HeroImage />
      {' '}
      {/* LCP element - sent immediately */}
      <Suspense fallback={<Loading />}>
        <SlowContent />
        {' '}
        {/* Streamed later */}
      </Suspense>
    </>
  )
}
```

### 4. hybrid approach

If you must use CSR for some parts, make sure the LCP element is in the initial HTML.

```jsx
// LCP element server-rendered, interactive parts client-rendered
export default function Page() {
  return (
    <>
      {/* Server-rendered, appears immediately */}
      <img src="/hero.jpg" alt="Hero" />
      <h1>Page Title</h1>

      {/* Client-rendered, but not LCP */}
      <InteractiveWidget />
    </>
  )
}
```

### 5. inline critical data

If you need data for the LCP element, inline it in the HTML.

```html
<script id="initial-data" type="application/json">
  {"hero": {"title": "Welcome", "image": "/hero.jpg"}}
</script>

<script>
  // No network request needed for initial render
  const data = JSON.parse(document.getElementById('initial-data').textContent)
</script>
```

## Framework-specific solutions

**Next.js**

Use App Router (default SSR) or Pages Router with `**getServerSideProps**`/`**getStaticProps**`. Never use `**useEffect**` for LCP content.

**Nuxt**

Nuxt defaults to SSR. Use `**useFetch**` or `**useAsyncData**` (not `**$fetch**` in `**onMounted**`) for data that affects LCP.

**React (SPA)**

Consider migrating to [**~~Next.js~~**](https://nextjs.org), [**~~Remix~~**](https://remix.run), or [**~~Astro~~**](https://astro.build). For pure React SPAs, pre-render critical pages with tools like `**react-snap**`.

**Vue (SPA)**

Consider migrating to Nuxt. For pure Vue SPAs, use `**vite-plugin-ssr**` or pre-render with `**vite-ssg**`.

## Verify the fix

After implementing:

1. View Page Source - content should be visible
2. Disable JavaScript - content should still appear
3. Run Lighthouse - LCP should improve significantly

**Expected improvement:** Moving from CSR to SSR can improve LCP by 1-3 seconds.

## Common mistakes

- **Hydration mismatch**: Server and client must render the same content. Mismatches cause re-renders and can hurt LCP.
- **Blocking on non-critical data**: Only wait for data needed for LCP. Load other data after.
- **Large server bundles**: SSR with huge dependencies increases TTFB. Keep server code lean.

## Trade-offs

| **Approach** | **LCP** | **Interactivity** | **Complexity** |
| --- | --- | --- | --- |
| CSR | Poor | Fast after load | Simple |
| SSR | Good | Delayed (hydration) | Medium |
| SSG | Best | Delayed (hydration) | Medium |
| Streaming SSR | Good | Progressive | Higher |

## Related issues

Often appears alongside:

- [**~~Slow Server Response~~**](https://unlighthouse.dev/learn-lighthouse/lcp/slow-server-response) - SSR adds server processing time
- [**~~Large Images~~**](https://unlighthouse.dev/learn-lighthouse/lcp/large-images) - Still need to optimize images with SSR

## Test your entire site

Some pages may use CSR while others use SSR. [**~~Unlighthouse~~**](https://unlighthouse.dev/) scans your entire site and identifies pages with client-side rendering issues.

### **Related **

[**LCP Overview**](https://unlighthouse.dev/learn-lighthouse/lcp) [**All LCP Issues**](https://unlighthouse.dev/learn-lighthouse/lcp#common-lcp-issues) [**LCP Definition**](https://unlighthouse.dev/glossary/lcp) [**LCP Finder Tool**](https://unlighthouse.dev/tools/lcp-finder)

[**Resource Load Delay** How to reduce resource load delay by preloading LCP resources and prioritizing critical assets.](https://unlighthouse.dev/learn-lighthouse/lcp/resource-load-delay) [**LCP Lazy Loaded** Remove loading='lazy' from hero images. Lazy-loading your LCP image adds 500ms+ delay. Fix with eager loading and fetchpriority='high'.](https://unlighthouse.dev/learn-lighthouse/lcp/lcp-lazy-loaded)

**On this page **

- [What's the problem?](#whats-the-problem)
- [How to identify this issue](#how-to-identify-this-issue)
- [The fix](#the-fix)
- [Framework-specific solutions](#framework-specific-solutions)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Trade-offs](#trade-offs)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** What is interaction to next paint (INP)? · Unlighthouse
- **Source:** https://unlighthouse.dev/glossary/inp
- **Description:** INP measures responsiveness. Learn what it is, thresholds, and how to improve interaction speed.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Glossary**

# **What is interaction to next paint (INP)?**

[Copy for LLMs](https://unlighthouse.dev/glossary/inp.md)

Loading demo...

Interaction to Next Paint (INP) measures how quickly your page responds to user interactions. It [**~~replaced FID as a Core Web Vital~~**](https://web.dev/blog/inp-cwv-march-12) in March 2024 and is a Google ranking factor.

## Thresholds

| **Score** | **Rating** |
| --- | --- |
| ≤ 200ms | Good |
| 200ms - 500ms | Needs Improvement |
| > 500ms | Poor |

Aim for a score of 200 milliseconds or less at the 75th percentile of page loads to pass the [**~~Google threshold~~**](https://web.dev/articles/inp).

## INP vs FID

FID only measured the first interaction's input delay. INP measures all interactions throughout the page lifecycle, including processing time and rendering. Since [**~~90% of user time is spent after page load~~**](https://web.dev/articles/inp), INP better reflects actual experience.

## Why it matters

While [**~~93% of sites had good FID~~**](https://web.dev/blog/inp-cwv), only [**~~74% have good INP~~**](https://almanac.httparchive.org/en/2024/performance). Users expect instant feedback - slow interactions make sites feel broken.

## Common issues

- Long-running JavaScript blocking main thread
- Heavy event handlers
- Third-party scripts (analytics, ads)
- Hydration delays in SPAs

## Measure INP

- [**~~Core Web Vitals Checker~~**](https://unlighthouse.dev/tools/cwv-checker) - test any page
- [**~~PageSpeed Insights~~**](https://pagespeed.web.dev/) (field data)
- Search Console Core Web Vitals report
- Web Vitals Chrome extension
- [**~~TBT~~**](https://unlighthouse.dev/glossary/tbt) as lab proxy

→ [**~~Complete INP guide~~**](https://unlighthouse.dev/learn-lighthouse/inp)

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/inp.md)

[Markdown For LLMs](https://unlighthouse.dev/glossary/inp.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/inp.md) on GitHub or provide anonymous feedback below.

### **Related **

[**INP Guide**](https://unlighthouse.dev/learn-lighthouse/inp) [**Core Web Vitals Checker**](https://unlighthouse.dev/tools/cwv-checker) [**Largest Contentful Paint (LCP)**](https://unlighthouse.dev/glossary/lcp) [**Cumulative Layout Shift (CLS)**](https://unlighthouse.dev/glossary/cls)

[**FCP** FCP measures when the first content renders. Learn what it is, thresholds, and how to improve it.](https://unlighthouse.dev/glossary/fcp) [**LCP** LCP measures loading performance. Learn what it is, thresholds, and how to improve your score.](https://unlighthouse.dev/glossary/lcp)

**On this page **

- [Thresholds](#thresholds)
- [INP vs FID](#inp-vs-fid)
- [Why it matters](#why-it-matters)
- [Common issues](#common-issues)
- [Measure INP](#measure-inp)

---

- **Page:** Fix Total Blocking Time for Better INP · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/inp/total-blocking-time
- **Description:** Reduce TBT to improve your Lighthouse performance score. TBT measures main thread blocking - the lab proxy for real-world INP.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Total Blocking Time for Better INP**

Reduce TBT to improve your Lighthouse performance score. TBT measures main thread blocking - the lab proxy for real-world INP.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)7 min read Published **Jan 18, 2025**

TBT accounts for 30% of your Lighthouse performance score. That's the largest weight of any single metric. A site with great LCP, CLS, and FCP can still score 70 if TBT is in the red.

Good TBT is 200ms or less on mobile. Poor is above 600ms. Desktop thresholds are tighter: 150ms good, 350ms poor. Most sites fall somewhere in the "needs improvement" zone.

**TBT**Total Blocking Time

**30% weight **

Good ≤200msPoor >600ms

## What's the problem?

TBT measures the invisible: time when the page looks ready but can't respond to user input.

**The calculation is specific.** Lighthouse identifies every task on the main thread between First Contentful Paint and Time to Interactive. For each task exceeding 50ms, it counts only the time *above* 50ms as blocking time. A 70ms task contributes 20ms to TBT. A 200ms task contributes 150ms.

```text
Task duration: 70ms  → TBT contribution: 20ms  (70 - 50)
Task duration: 200ms → TBT contribution: 150ms (200 - 50)
Task duration: 45ms  → TBT contribution: 0ms   (under threshold)
```

**Why this matters for real users:** TBT is a lab metric. You won't see it in field data. But it strongly correlates with INP (Interaction to Next Paint), the Core Web Vital that measures real interaction responsiveness. Fix TBT in the lab, and INP improves in the field.

**The 50ms threshold exists because** human perception research shows responses under 100ms feel instant. At 50ms task length, the browser has 50ms remaining in that 100ms window to process user input and update the screen.

## How TBT relates to INP

INP measures actual user interactions in the field. TBT measures potential for blocking during controlled lab conditions.

They target the same basic issue: main thread availability. But they measure differently:

| **Aspect** | **TBT (Lab)** | **INP (Field)** |
| --- | --- | --- |
| When measured | Page load to TTI | Entire session |
| Data source | Lighthouse simulation | Real user monitoring |
| Interactions | None (task timing) | Clicks, taps, keypresses |
| Threshold (good) | ≤200ms | ≤200ms |

**A site can have good TBT and bad INP** if the blocking happens after initial load (lazy-loaded features, SPA navigation, dynamic content).

**A site can have bad TBT and good INP** if users don't interact during the blocking period, or if the blocking tasks are CPU-throttled in Lighthouse more than real devices experience.

### The "TBT trap": lab vs field

Optimizing TBT to 0 in the lab is a great goal, but a green Lighthouse score alone won't guarantee green Field data. This is the **"TBT Trap"**.

- **The Phase Mismatch:** TBT measures the *loading* phase (until Time to Interactive). INP measures the *entire lifespan*. If your heavy JavaScript runs when a user opens a modal 2 minutes later, TBT won't see it, but INP will fail.
- **The "Budget Stacking" Effect:** A 50ms task seems fine for a 200ms INP target. But if you have *four* 50ms tasks back-to-back, and a user clicks during the first one, the browser might queue the input until the fourth one finishes. Suddenly, your "safe" 50ms tasks stack up to a 200ms+ delay.

Fix both. TBT catches load-time issues. INP catches runtime issues.

## How to identify

### Lighthouse report

TBT appears in the Metrics section with a score from 0-100. Expand the "Diagnostics" section to find:

- **Avoid long main-thread tasks** - Lists the longest tasks by duration
- **Reduce JavaScript execution time** - Shows script-by-script execution time
- **Minimize main-thread work** - Breaks down time by category (script, style, layout)

### Chrome DevTools performance panel

1. Open DevTools → Performance tab
2. Enable CPU throttling (4x slowdown) to match Lighthouse conditions
3. Record a page load
4. Look at the "Total Blocking Time" in the summary
5. Examine the Main thread for tasks with red corners (>50ms)

### Webpagetest

Run a test with "Capture Blocking Time" enabled. The waterfall view highlights long tasks, and the filmstrip shows exactly when the page was unresponsive.

## The fix

### 1. break up long tasks

The most direct fix: no task should exceed 50ms.

```js
// Before: 300ms blocking task
function processAllData(items) {
  return items.map(transform).filter(validate).sort(compare)
}

// After: yields every 50ms of work
async function processAllDataModern(items) {
  const results = []
  let startTime = performance.now()

  for (const item of items) {
    results.push(transform(item))

    // Yield if we've been working for 40ms
    if (performance.now() - startTime > 40) {
      await scheduler.yield()
      startTime = performance.now()
    }
  }

  return results.filter(validate).sort(compare)
}
```

For simpler cases, chunk your work:

```js
async function processInChunks(items, chunkSize = 100) {
  for (let i = 0; i < items.length; i += chunkSize) {
    const chunk = items.slice(i, i + chunkSize)
    processChunk(chunk)
    await new Promise(resolve => setTimeout(resolve, 0))
  }
}
```

### 2. defer non-critical JavaScript

Scripts that don't affect initial render should load after the page is interactive.

```html
<!-- Before: blocks parsing -->
<script src="analytics.js"></script>
<script src="chat-widget.js"></script>

<!-- After: loads after HTML parsing -->
<script src="analytics.js" defer></script>
<script src="chat-widget.js" defer></script>
```

For third-party scripts you don't control:

```js
// Load after page is idle
function loadWhenIdle(src) {
  if ('requestIdleCallback' in window) {
    requestIdleCallback(() => {
      const script = document.createElement('script')
      script.src = src
      document.body.appendChild(script)
    })
  }
  else {
    setTimeout(() => {
      const script = document.createElement('script')
      script.src = src
      document.body.appendChild(script)
    }, 2000)
  }
}

loadWhenIdle('https://cdn.chat-widget.com/widget.js')
```

### 3. remove unused code

Every kilobyte of JavaScript adds parse and compile time, even if the code never runs.

**Find unused code with Coverage tool:**

1. DevTools → More tools → Coverage
2. Click record, load page, interact
3. Red bars indicate unused bytes

**Tree-shake aggressively:**

```js
// Before: imports entire library
import _ from 'lodash'

// After: imports single function
import debounce from 'lodash/debounce'

const result = _.debounce(fn, 300)
const debouncedResult = debounce(fn, 300)
```

**Audit your dependencies:**

```bash
npx depcheck # Find unused dependencies
npx bundlephobia <package-name> # Check bundle size impact
```

Replace heavy libraries with lighter alternatives:

- moment.js (300KB) → date-fns (tree-shakeable) or dayjs (2KB)
- lodash (70KB) → native methods or individual imports
- axios (13KB) → fetch API

### 4. optimize third-party scripts

Third-party scripts often contribute 50%+ of TBT. You don't control their code, but you control when and how they load.

**Audit third-party impact:**

```js
// Log third-party task durations
const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (entry.duration > 50) {
      console.log(`Long task: ${entry.duration}ms`, entry.attribution)
    }
  }
})
observer.observe({ entryTypes: ['longtask'] })
```

**Strategies:**

- Load below the fold scripts on scroll, not on page load
- Use `**loading="lazy"**` for iframe embeds
- Self-host critical third-party scripts to control delivery
- Use resource hints ( `**preconnect**`) for scripts you can't delay

```html
<!-- Preconnect to third-party origins -->
<link rel="preconnect" href="https://www.googletagmanager.com">
<link rel="preconnect" href="https://www.google-analytics.com">
```

### 5. web workers for heavy computation

Move CPU-intensive work off the main thread entirely.

```js
// main.js
const worker = new Worker('data-processor.js')

function analyzeData(data) {
  return new Promise((resolve) => {
    worker.postMessage(data)
    worker.onmessage = e => resolve(e.data)
  })
}

// data-processor.js (runs on separate thread)
globalThis.onmessage = (e) => {
  const result = heavyComputation(e.data)
  globalThis.postMessage(result)
}
```

Candidates for Web Workers:

- JSON parsing of large payloads
- Image/video processing
- Data sorting and filtering
- Cryptographic operations
- Search indexing

## Framework-specific solutions

**Next.js**

Use React Server Components (App Router) to eliminate client-side JavaScript:

```jsx
// app/products/page.js - Server Component by default
// No JavaScript sent to client for this component
export default async function ProductsPage() {
  const products = await fetchProducts()
  return <ProductList products={products} />
}
```

For client components, use `**Suspense**` boundaries:

```jsx
import { Suspense } from 'react'

export default function Page() {
  return (
    <>
      <Header />
      <Suspense fallback={<ProductsSkeleton />}>
        <Products />
      </Suspense>
    </>
  )
}
```

**Nuxt**

Use `**<ClientOnly>**` to defer non-critical hydration:

```html
<template>
  <main>
    <CriticalContent />
    <ClientOnly>
      <NonCriticalWidget />
      <template #fallback>
        <WidgetPlaceholder />
      </template>
    </ClientOnly>
  </main>
</template>
```

Lazy-load components with the `**Lazy**` prefix:

```html
<template>
  <!-- Only loads when component enters viewport -->
  <LazyHeavyChart v-if="chartVisible" :data="chartData" />
</template>
```

**React**

Use `**React.lazy()**` for route-level code splitting:

```jsx
import { lazy, Suspense } from 'react'

const AdminDashboard = lazy(() => import('./AdminDashboard'))

function App() {
  return (
    <Suspense fallback={<Loading />}>
      <Routes>
        <Route path="/admin" element={<AdminDashboard />} />
      </Routes>
    </Suspense>
  )
}
```

## Verify the fix

1. **Run Lighthouse multiple times.** TBT varies between runs due to CPU timing. Take the median of 3-5 runs.
2. **Test with CPU throttling.** DevTools → Performance → CPU: 4x slowdown matches Lighthouse mobile simulation.
3. **Check the task breakdown.** After optimization, no single task should exceed 50ms in the Performance panel.

**Expected improvement:** Reducing a single 600ms task to six 100ms tasks can drop TBT from 550ms to 300ms (each 100ms task contributes 50ms instead of one task contributing 550ms).

## Common mistakes

**Focusing only on your code.** Third-party scripts often dominate TBT. Profile before optimizing.

**Over-deferring critical scripts.** Deferring everything delays interactivity. Interactive elements need their JavaScript loaded and executed.

**Testing only on fast devices.** TBT measures blocking on throttled CPU. A task that runs in 40ms on your M1 Mac runs in 160ms on a throttled mobile simulation.

**Ignoring hydration.** SSR frameworks still need to hydrate. That hydration JavaScript contributes to TBT like any other script.

## Related issues

Often appears alongside:

- [**~~Long-Running JavaScript~~**](https://unlighthouse.dev/learn-lighthouse/inp/long-running-javascript) - Individual tasks causing blocking
- [**~~Third-Party Scripts~~**](https://unlighthouse.dev/learn-lighthouse/inp/third-party-scripts) - External scripts adding to TBT
- [**~~Hydration Issues~~**](https://unlighthouse.dev/learn-lighthouse/inp/hydration-issues) - Framework initialization blocking

## Test your entire site

TBT varies across pages. A fast homepage with a slow checkout flow still frustrates users. [**~~Unlighthouse~~**](https://unlighthouse.dev/) audits your entire site and ranks pages by TBT impact.

### **Related **

[**INP Overview**](https://unlighthouse.dev/learn-lighthouse/inp) [**All INP Issues**](https://unlighthouse.dev/learn-lighthouse/inp#common-inp-issues) [**INP Definition**](https://unlighthouse.dev/glossary/inp) [**TBT Definition**](https://unlighthouse.dev/glossary/tbt) [**INP Analyzer Tool**](https://unlighthouse.dev/tools/inp-analyzer)

[**Long-Running JavaScript** Reduce JavaScript execution time to improve INP. Learn code splitting, web workers, and task chunking to keep the main thread responsive.](https://unlighthouse.dev/learn-lighthouse/inp/long-running-javascript) [**Main Thread Work** Reduce main thread work from DOM manipulation, style recalculation, and layout thrashing. Keep interactions responsive.](https://unlighthouse.dev/learn-lighthouse/inp/heavy-dom-operations)

**On this page **

- [What's the problem?](#whats-the-problem)
- [How TBT relates to INP](#how-tbt-relates-to-inp)
- [How to identify](#how-to-identify)
- [The fix](#the-fix)
- [Framework-specific solutions](#framework-specific-solutions)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix Images Without Dimensions for Better CLS · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/cls/unsized-images
- **Description:** Images without width and height cause layout shifts. Add explicit dimensions to prevent your page from jumping around as images load.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Images Without Dimensions for Better CLS**

Images without width and height cause layout shifts. Add explicit dimensions to prevent your page from jumping around as images load.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)8 min read Published **Jan 18, 2025**

Images without explicit width and height cause 66% of CLS issues on mobile. Every image missing dimensions is a layout shift waiting to happen.

**CLS**Cumulative Layout Shift** CWV **

**25% weight **

Good ≤0.10Poor >0.25

## What's the problem?

When you load an image without telling the browser its size, the browser reserves zero space for it. The image downloads, the browser discovers its actual dimensions, and everything below it gets shoved down. That's a layout shift.

This happens because browsers render content progressively. They don't wait for images to download before showing text. So they start laying out the page with a 0x0 placeholder for your image. When the image finally loads, the placeholder expands to fit it, and content reflows.

**The technical flow:**

1. Browser parses HTML, finds `**<img>**` with no dimensions
2. Creates 0x0 inline box for the image
3. Renders page - user starts reading
4. Image downloads, actual size determined (say, 800x600)
5. Browser recalculates layout, content below shifts by 600px
6. User loses their place, might misclick

The larger the image and the higher it appears on the page, the worse the shift. A hero image without dimensions can cause CLS of 0.3+ on its own - three times over the "poor" threshold.

## How to identify this issue

### Chrome DevTools

Open Elements panel and inspect your images. Look for:

- Missing `**width**` attribute
- Missing `**height**` attribute
- CSS that sets `**width: auto**` or `**height: auto**` without an `**aspect-ratio**`

Quick console check:

```js
document.querySelectorAll('img').forEach((img) => {
  const hasWidth = img.hasAttribute('width') || img.style.width
  const hasHeight = img.hasAttribute('height') || img.style.height
  const hasAspectRatio = getComputedStyle(img).aspectRatio !== 'auto'

  if (!(hasWidth && hasHeight) && !hasAspectRatio) {
    console.warn('Unsized image:', img.src, img)
  }
})
```

### Lighthouse

The audit "Image elements do not have explicit `**width**` and `**height**`" lists every offending image with its URL and DOM location. Each image in that list is causing or could cause a layout shift.

Lighthouse checks that images have either:

- Both `**width**` and `**height**` HTML attributes with valid non-negative integers
- CSS `**width**` and `**height**` that aren't `**auto/initial/unset/inherit**`
- One explicit dimension plus an explicit `**aspect-ratio**`

Images with `**position: fixed**` or `**position: absolute**` are excluded since they don't affect document flow.

## The fix

### 1. add width and height attributes

The simplest fix. Add `**width**` and `**height**` to every `**<img>**` element:

```html
<!-- Before: CLS disaster -->
<img src="/hero.jpg" alt="Hero image">

<!-- After: No CLS -->
<img src="/hero.jpg" width="1200" height="630" alt="Hero image">
```

These attributes tell the browser the image's intrinsic dimensions. Modern browsers use them to calculate the aspect ratio and reserve the correct space before the image loads.

**For responsive images**, combine attributes with CSS:

```html
<img
  src="/hero.jpg"
  width="1200"
  height="630"
  class="w-full h-auto"
  alt="Hero image"
>
```

```css
.w-full { width: 100%; }
.h-auto { height: auto; }
```

The browser calculates: "This image has a 1200:630 (1.9:1) aspect ratio. At 100% width, I'll reserve height accordingly." No shift.

### 2. use CSS aspect-ratio

When you can't add HTML attributes (CMS limitations, dynamic images), use CSS:

```css
.hero-image {
  aspect-ratio: 16 / 9;
  width: 100%;
}

.avatar {
  aspect-ratio: 1;
  width: 48px;
}

.product-image {
  aspect-ratio: 4 / 3;
  width: 100%;
  object-fit: cover;
}
```

`**aspect-ratio**` tells the browser the proportions directly. Combined with one dimension (width or height), it calculates the other.

**Fallback for older browsers:**

```css
.hero-image {
  aspect-ratio: 16 / 9;
  width: 100%;
}

/* Fallback using padding trick */
@supports not (aspect-ratio: 16 / 9) {
  .hero-image-wrapper {
    position: relative;
    padding-bottom: 56.25%; /* 9/16 = 0.5625 */
  }
  .hero-image-wrapper img {
    position: absolute;
    width: 100%;
    height: 100%;
    object-fit: cover;
  }
}
```

### 3. handle user-uploaded images

When dimensions are truly unknown (user uploads, external URLs), use container constraints:

```html
<div class="image-container">
  <img src="/user-upload.jpg" alt="User content">
</div>
```

```css
.image-container {
  aspect-ratio: 1; /* Force square */
  width: 100%;
  overflow: hidden;
  background: var(--ui-bg-muted);
}

.image-container img {
  width: 100%;
  height: 100%;
  object-fit: cover;
}
```

The container reserves space. The image fills it. Content around it never shifts.

For galleries with mixed aspect ratios, pick a dominant ratio:

```css
.gallery-item {
  aspect-ratio: 4 / 3; /* Most photos are roughly this */
  background: var(--ui-bg-muted);
}

.gallery-item img {
  width: 100%;
  height: 100%;
  object-fit: contain; /* or cover, depending on preference */
}
```

### Why this works

Browser aspect ratio calculation happens during the layout phase, before paint. When you provide dimensions (via attributes or CSS), the browser knows exactly how much space to reserve during initial layout.

The insight: providing dimensions prevents the layout from changing when the image loads.

## Framework-specific solutions

**Next.js**

`**next/image**` requires dimensions and prevents CLS by design:

```jsx
import Image from 'next/image'

// Static import - dimensions inferred
import heroImage from './hero.jpg'

export function Hero() {
  return <Image src={heroImage} alt="Hero" />
}

// External URL - dimensions required
export function Photo() {
  return (
    <Image
      src="https://example.com/photo.jpg"
      width={800}
      height={600}
      alt="Photo"
    />
  )
}

// Fill mode - container controls size
export function FillHero() {
  return (
    <div className="relative w-full aspect-video">
      <Image src="/hero.jpg" fill alt="Hero" />
    </div>
  )
}
```

The component generates `**srcset**` and handles responsive sizing. Using raw `**<img>**` in [**~~Next.js~~**](https://nextjs.org) usually means missing out on these protections.

**Nuxt**

`**NuxtImg**` from `**@nuxt/image**` handles dimensions:

```html
<template>
  <NuxtImg
    src="/photo.jpg"
    width="800"
    height="600"
    alt="Photo"
  />
</template>
```

With responsive sizes:

```html
<NuxtImg
  src="/hero.jpg"
  width="1200"
  height="630"
  sizes="sm:100vw md:50vw lg:800px"
  alt="Hero"
/>
```

For dynamic images, wrap in a sized container:

```html
<div class="aspect-video w-full">
  <NuxtImg
    :src="dynamicUrl"
    class="w-full h-full object-cover"
    alt="Dynamic content"
  />
</div>
```

## Verify the fix

After adding dimensions:

**1. Re-run Lighthouse**

The "Image elements do not have explicit width and height" audit should pass. If images still appear, they're missing proper sizing.

**2. Check with DevTools**

```js
// Should return empty array
document.querySelectorAll('img').filter((img) => {
  const style = getComputedStyle(img)
  const hasExplicitSize
    = (img.width && img.height)
      || (style.width !== 'auto' && style.height !== 'auto')
      || style.aspectRatio !== 'auto'
  return !hasExplicitSize
})
```

**3. Visual test**

Throttle network to Slow 3G, reload the page. Watch the image areas. They should have placeholder space that fills in when images load - no jumping.

**Expected improvement:** Fixing a single unsized hero image can reduce CLS from 0.25+ to under 0.1. Multiple unsized images compound, so fixing all of them often results in CLS dropping to near zero from this source.

## Common mistakes

**Only adding width**

```html
<!-- Wrong - height is still auto -->
<img src="/photo.jpg" width="800">

<!-- Right -->
<img src="/photo.jpg" width="800" height="600">
```

Lighthouse requires both dimensions to calculate the aspect ratio correctly.

**Wrong aspect ratio**

```html
<!-- Image is actually 1200x800, not 1200x600 -->
<img src="/photo.jpg" width="1200" height="600">
```

This causes the image to stretch or compress. Use actual image dimensions or matching aspect ratio.

**Forgetting lazy-loaded images**

```html
<!-- Still needs dimensions even with lazy loading -->
<img src="/photo.jpg" loading="lazy" width="800" height="600">
```

Lazy loading defers download, not space reservation. Dimensions are still critical.

**Using percentage for both dimensions**

```css
/* Doesn't help - browser still doesn't know absolute size */
img {
  width: 100%;
  height: 100%;
}
```

The parent needs a defined size, or use `**aspect-ratio**` with one dimension.

## Related issues

Unsized images often appear alongside:

- [**~~Ads & Embeds~~**](https://unlighthouse.dev/learn-lighthouse/cls/ads-embeds-iframes) - Third-party images with unknown dimensions
- [**~~Dynamic Content~~**](https://unlighthouse.dev/learn-lighthouse/cls/dynamic-content-injection) - Lazy-loaded image galleries
- [**~~Web Fonts~~**](https://unlighthouse.dev/learn-lighthouse/cls/web-fonts-causing-foit) - Both cause above-the-fold shifts

## Test your entire site

One page might pass. Another might have a template with unsized images that repeats across hundreds of URLs. [**~~Unlighthouse~~**](https://unlighthouse.dev/) scans your entire site and surfaces every page with unsized image issues, sorted by CLS impact.

### **Related **

[**CLS Overview**](https://unlighthouse.dev/learn-lighthouse/cls) [**All CLS Issues**](https://unlighthouse.dev/learn-lighthouse/cls#common-cls-issues) [**CLS Definition**](https://unlighthouse.dev/glossary/cls) [**CLS Debugger Tool**](https://unlighthouse.dev/tools/cls-debugger)

[**CLS** Google considers a CLS score of 0.1 or less as good. Learn what causes layout shifts and how to fix CLS with proven techniques for images, fonts, ads, and dynamic content.](https://unlighthouse.dev/learn-lighthouse/cls) [**Large Layout Shifts** Diagnose and fix layout shifts caused by CSS reflow, font-size changes, unsized media, web fonts, and injected iframes. Reduce your CLS score.](https://unlighthouse.dev/learn-lighthouse/cls/layout-shifts)

**On this page **

- [What's the problem?](#whats-the-problem)
- [How to identify this issue](#how-to-identify-this-issue)
- [The fix](#the-fix)
- [Framework-specific solutions](#framework-specific-solutions)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix Large Images for Better LCP · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/lcp/large-images
- **Description:** Optimize LCP images with responsive srcset, modern formats like WebP and AVIF, and proper compression. Reduce image size without losing quality.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Large Images for Better LCP**

Optimize LCP images with responsive srcset, modern formats like WebP and AVIF, and proper compression. Reduce image size without losing quality.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)7 min read Published **Jan 18, 2025**

[**~~73% of mobile pages have an image as their LCP element~~**](https://almanac.httparchive.org/en/2024/performance). When that image is unoptimized, nothing else you do matters - you're bottlenecked by download time.

The median site keeps LCP images under 100KB, but [**~~8% of sites serve LCP images over 1MB~~**](https://almanac.httparchive.org/en/2024/media). That's 5-10 seconds of download time on 3G.

## What's the problem?

Large images slow LCP in a direct, linear way: bigger file = longer download. The resource load duration, how long the image takes to download, accounts for roughly 40% of typical LCP time.

**Common causes:**

- Using JPEG or PNG instead of WebP/AVIF (2-3x larger)
- Serving desktop-sized images to mobile devices
- No compression or using maximum quality
- Ignoring responsive images (srcset/sizes)
- Animated GIFs instead of video formats

Lighthouse flags this through multiple audits: "Properly size images," "Serve images in next-gen formats," "Efficiently encode images," and the combined "Improve image delivery" insight.

### The math

A 1MB hero image on a 3G connection (1.5 Mbps):

- Download time: \~5.3 seconds
- Your LCP cannot be faster than 5.3 seconds

The same image optimized to 100KB:

- Download time: \~530ms
- LCP budget now available for other things

## How to identify this issue

### Chrome DevTools

1. Open Network tab (F12)
2. Filter by "Img"
3. Find your LCP image (usually the largest above-fold image)
4. Check the "Size" column
5. Click the image, check "Content-Length" in headers

**Red flags:**

- LCP image > 200KB on desktop
- LCP image > 100KB on mobile
- Download time > 500ms on good connection

### Lighthouse

Look for these audits:

- "Properly size images" - Image dimensions vs display size
- "Serve images in next-gen formats" - JPEG/PNG that should be WebP/AVIF
- "Efficiently encode images" - Compression opportunities
- "Improve image delivery" - Combined recommendations

### Webpagetest

Waterfall chart shows exact download time per image. Look for long bars on image requests.

## The fix

### 1. use modern image formats

WebP and AVIF are 30-50% smaller than JPEG at equivalent visual quality.

```html
<!-- Before: JPEG only -->
<img src="hero.jpg" alt="Hero">

<!-- After: modern formats with fallback -->
<picture>
  <source srcset="hero.avif" type="image/avif">
  <source srcset="hero.webp" type="image/webp">
  <img src="hero.jpg" alt="Hero" width="1200" height="600">
</picture>
```

**Format comparison at \~80 quality:**

| **Format** | **Typical size** | **Browser support** |
| --- | --- | --- |
| JPEG | 150KB | 100% |
| WebP | 90KB | 97%+ |
| AVIF | 60KB | 93%+ |

Use AVIF as primary, WebP as fallback, JPEG for ancient browsers.

### 2. use responsive images

Don't serve 2400px images to 400px mobile screens.

```html
<img
  src="hero.webp"
  srcset="
    hero-400.webp 400w,
    hero-800.webp 800w,
    hero-1200.webp 1200w,
    hero-1600.webp 1600w
  "
  sizes="100vw"
  width="1200"
  height="600"
  alt="Hero"
>
```

**Understanding srcset and sizes:**

- `**srcset**` lists available images with their widths ( `**400w**` = 400px wide)
- `**sizes**` tells browser how wide the image will display
- Browser picks the optimal image based on screen size and DPR

**Common sizes patterns:**

```html
<!-- Full width hero -->
sizes="100vw"

<!-- Full width mobile, half width desktop -->
sizes="(max-width: 768px) 100vw, 50vw"

<!-- Fixed width sidebar image -->
sizes="300px"

<!-- Complex layout -->
sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw"
```

### 3. compress appropriately

Quality 80-85 is visually indistinguishable from 100 for most images.

```bash
npx sharp-cli hero.jpg -o hero.webp -- webp -q 80

convert hero.jpg -quality 80 hero.webp

# Cwebp (Google)
cwebp -q 80 hero.jpg -o hero.webp
```

**Quality guidelines:**

| **Image type** | **Quality** | **Rationale** |
| --- | --- | --- |
| Hero/LCP | 80-85 | Needs to look sharp |
| Product photos | 75-80 | Balance quality/size |
| Thumbnails | 70-75 | Small display size |
| Backgrounds | 60-70 | Often blurred/dimmed |

### 4. set explicit dimensions

Always include `**width**` and `**height**` to prevent layout shifts and help browser allocate space.

```html
<img
  src="hero.webp"
  width="1200"
  height="600"
  style="width: 100%; height: auto;"
  alt="Hero"
>
```

Or use CSS aspect-ratio:

```css
.hero-img {
  width: 100%;
  aspect-ratio: 2 / 1;
  object-fit: cover;
}
```

### 5. use an image CDN

Image CDNs (Cloudinary, imgix, Cloudflare Images) handle format selection, resizing, and compression automatically.

```html
<!-- Cloudinary: automatic format, width, quality -->
<img
  src="https://res.cloudinary.com/demo/image/upload/w_800,q_auto,f_auto/hero.jpg"
  srcset="
    https://res.cloudinary.com/demo/image/upload/w_400,q_auto,f_auto/hero.jpg 400w,
    https://res.cloudinary.com/demo/image/upload/w_800,q_auto,f_auto/hero.jpg 800w,
    https://res.cloudinary.com/demo/image/upload/w_1200,q_auto,f_auto/hero.jpg 1200w
  "
  sizes="100vw"
  alt="Hero"
>
```

Benefits:

- Automatic WebP/AVIF serving
- Dynamic resizing
- Global CDN caching
- No build-time image generation

### Complete example

```html
<picture>
  <!-- AVIF for modern browsers -->
  <source
    type="image/avif"
    srcset="
      hero-400.avif 400w,
      hero-800.avif 800w,
      hero-1200.avif 1200w
    "
    sizes="100vw"
  >
  <!-- WebP fallback -->
  <source
    type="image/webp"
    srcset="
      hero-400.webp 400w,
      hero-800.webp 800w,
      hero-1200.webp 1200w
    "
    sizes="100vw"
  >
  <!-- JPEG for old browsers -->
  <img
    src="hero-800.jpg"
    srcset="
      hero-400.jpg 400w,
      hero-800.jpg 800w,
      hero-1200.jpg 1200w
    "
    sizes="100vw"
    width="1200"
    height="600"
    fetchpriority="high"
    decoding="async"
    alt="Descriptive alt text"
  >
</picture>
```

## Why this works

Image download time is governed by simple physics: file size divided by bandwidth. You cannot make bytes download faster - you can only send fewer bytes.

Modern formats use better compression algorithms:

- WebP: Predictive coding, superior entropy encoding
- AVIF: AV1 video codec applied to images, excellent for photos

Responsive images make sure you're not sending 4x more pixels than needed:

- 2400px image at 2x DPR for 600px display = 4.8 megapixels
- 1200px image at 2x DPR for 600px display = 1.2 megapixels
- That's 75% fewer pixels to compress

Combined, format + responsive + compression reduces image size by 80-90%.

## Framework-specific solutions

**Next.js**

`**next/image**` handles everything - format selection, responsive sizes, lazy loading:

```jsx
import Image from 'next/image'

export function HeroImage() {
  return (
    <Image
      src="/hero.jpg"
      width={1200}
      height={600}
      priority // For LCP image
      sizes="100vw"
      alt="Hero"
    />
  )
}
```

Configure quality in next.config.js:

```js
export default {
  images: {
    formats: ['image/avif', 'image/webp'],
    deviceSizes: [640, 750, 828, 1080, 1200, 1920],
    quality: 80,
  },
}
```

**Nuxt**

Use `**@nuxt/image**` with a provider (ipx, cloudinary, etc.):

```html
<NuxtImg
  src="/hero.jpg"
  width="1200"
  height="600"
  sizes="100vw sm:100vw md:100vw lg:100vw"
  format="webp"
  quality="80"
  preload
  alt="Hero"
/>
```

Configure in nuxt.config.ts:

```ts
export default defineNuxtConfig({
  image: {
    quality: 80,
    format: ['webp', 'avif'],
    screens: {
      sm: 640,
      md: 768,
      lg: 1024,
      xl: 1280,
    },
  },
})
```

**React**

No built-in solution. Use an image component library or build your own:

```jsx
function ResponsiveImage({ src, alt, sizes = '100vw' }) {
  const base = src.replace(/\.[^.]+$/, '')
  const ext = src.match(/\.[^.]+$/)?.[0] || '.jpg'

  return (
    <picture>
      <source
        type="image/avif"
        srcSet={`${base}-400.avif 400w, ${base}-800.avif 800w, ${base}-1200.avif 1200w`}
        sizes={sizes}
      />
      <source
        type="image/webp"
        srcSet={`${base}-400.webp 400w, ${base}-800.webp 800w, ${base}-1200.webp 1200w`}
        sizes={sizes}
      />
      <img
        src={`${base}-800${ext}`}
        srcSet={`${base}-400${ext} 400w, ${base}-800${ext} 800w, ${base}-1200${ext} 1200w`}
        sizes={sizes}
        alt={alt}
        fetchPriority="high"
      />
    </picture>
  )
}
```

Or use an image CDN and construct URLs dynamically.

## Verify the fix

After implementing:

1. **Network tab**: Check new file sizes, should be significantly smaller
2. **Response headers**: Verify Content-Type shows webp or avif
3. **Lighthouse**: Image audits should pass or show smaller potential savings
4. **Compare LCP**: Before/after measurement

**Expected improvement:** Reducing a 500KB JPEG to 100KB WebP can save 400-800ms on typical connections.

## Common mistakes

### Wrong sizes attribute

If `**sizes**` doesn't match actual layout, browser downloads wrong image.

```html
<!-- Wrong: says full width, but image is actually half width -->
<img sizes="100vw" src="..." style="width: 50%">

<!-- Right: matches layout -->
<img sizes="50vw" src="..." style="width: 50%">
```

### Over-compressing

Quality too low creates visible artifacts. Test visually.

```bash
cwebp -q 30 hero.jpg -o hero.webp  # Will look bad

cwebp -q 80 hero.jpg -o hero.webp
```

### Forgetting high-dpr displays

2x and 3x displays need larger source images.

```html
<!-- srcset should include sizes for high-DPR -->
srcset="
  hero-400.webp 400w,   /* 400px @ 1x */
  hero-800.webp 800w,   /* 400px @ 2x, 800px @ 1x */
  hero-1200.webp 1200w  /* 400px @ 3x, 600px @ 2x */
"
```

### Only optimizing desktop

Mobile users on slow networks benefit most from image optimization. Test on mobile.

## Related issues

Often appears alongside:

- [**~~Prioritize LCP Image~~**](https://unlighthouse.dev/learn-lighthouse/lcp/prioritize-lcp-image) - Optimized image + priority = fast LCP
- [**~~LCP Lazy Loaded~~**](https://unlighthouse.dev/learn-lighthouse/lcp/lcp-lazy-loaded) - Don't lazy-load your optimized hero

## Test your entire site

Image optimization varies by page. Your homepage hero might be perfect while blog post images are unoptimized PNGs. [**~~Unlighthouse~~**](https://unlighthouse.dev/) scans your entire site and identifies pages with oversized images.

### **Related **

[**LCP Overview**](https://unlighthouse.dev/learn-lighthouse/lcp) [**All LCP Issues**](https://unlighthouse.dev/learn-lighthouse/lcp#common-lcp-issues) [**LCP Definition**](https://unlighthouse.dev/glossary/lcp) [**LCP Finder Tool**](https://unlighthouse.dev/tools/lcp-finder)

[**LCP Lazy Loaded** Remove loading='lazy' from hero images. Lazy-loading your LCP image adds 500ms+ delay. Fix with eager loading and fetchpriority='high'.](https://unlighthouse.dev/learn-lighthouse/lcp/lcp-lazy-loaded) [**Lazy-Loading Above Fold** Why you should never lazy-load your LCP image and how to fix it.](https://unlighthouse.dev/learn-lighthouse/lcp/lazy-loading-above-fold)

**On this page **

- [What's the problem?](#whats-the-problem)
- [How to identify this issue](#how-to-identify-this-issue)
- [The fix](#the-fix)
- [Why this works](#why-this-works)
- [Framework-specific solutions](#framework-specific-solutions)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix Ads, Embeds &amp; iframes for Better CLS · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/cls/ads-embeds-iframes
- **Description:** Prevent layout shifts from third-party ads, video embeds, social widgets, and iframes with reserved space techniques.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Ads, Embeds & iframes for Better CLS**

Prevent layout shifts from third-party ads, video embeds, social widgets, and iframes with reserved space techniques.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)6 min read Published **Jan 18, 2025**

Third-party content is the hardest CLS problem to solve. You control neither the dimensions nor the load timing. Ads are the worst offenders - they shift content an average of 0.15 CLS on affected pages.

**CLS**Cumulative Layout Shift** CWV **

**25% weight **

Good ≤0.10Poor >0.25

## What lighthouse detects

Lighthouse's layout-shifts audit specifically flags "Injected iframe" as a root cause. When an iframe loads asynchronously and pushes content, it gets flagged with its URL source.

The audit tracks:

- Layout shift score per event
- Impacted nodes (elements that moved)
- Root cause: `**rootCauseInjectedIframe**` with iframe URL

## Why this destroys CLS

Third-party content has three problems:

1. **Unknown dimensions**: Ad networks serve different creative sizes. YouTube embeds default to 0x0 until their script runs. Twitter cards have variable heights.
2. **Asynchronous loading**: These scripts load after your content renders. By design, they arrive late.
3. **Dynamic resizing**: Some ads resize based on viewport, ad availability, or user interaction.

**Real impact:** A single 300x250 ad loading in the middle of an article causes 0.1-0.3 CLS. If you have multiple ad placements, you can easily exceed 0.5 CLS.

## Strategic insights

| **Strategy** | **Details** | **Impact** |
| --- | --- | --- |
| **Mobile-First Reality** | Google indexes the mobile version of your site. On a phone screen, a 300px height shift pushes *all* content off-screen, creating a much higher Impact Fraction than on desktop. | **Critical** |
| **Field Data (CrUX) Truth** | You cannot hide CLS from Google by blocking ad scripts in `**robots.txt**`. Ranking uses [**~~Chrome User Experience Report (CrUX)~~**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) data from real users who *do* see the ads. | **High** |
| **Accessibility & A11y** | Layout shifts aren't just visual annoyances. For users with motor impairments or those using screen magnifiers, an ad snapping into place can cause them to lose their reading position entirely. | **Medium** |

## How to diagnose

### DevTools performance panel

1. Open DevTools > Performance tab
2. Check "Web Vitals" checkbox
3. Record and reload
4. Click on Layout Shift entries
5. Look at "Sources" - if it shows an iframe or ad container, this guide is for you

### Layout shift regions

Enable "Layout Shift Regions" in DevTools Rendering tab. Reload the page slowly (throttle to Slow 3G). Blue/red flashes around iframe areas confirm the problem.

### Console snippet

```js
new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    entry.sources?.forEach((source) => {
      if (source.node?.tagName === 'IFRAME') {
        console.log('iframe shift:', entry.value, source.node.src)
      }
    })
  }
}).observe({ type: 'layout-shift', buffered: true })
```

## The fixes

### 1. reserve exact space for ads

Know your ad sizes. Common IAB standard sizes:

| **Format** | **Dimensions** |
| --- | --- |
| Medium Rectangle | 300x250 |
| Leaderboard | 728x90 |
| Mobile Banner | 320x50 |
| Wide Skyscraper | 160x600 |
| Billboard | 970x250 |

Reserve the space before the ad loads:

```html
<div class="ad-container" style="min-height: 250px; min-width: 300px;">
  <!-- Ad script injects here -->
</div>
```

Better approach with CSS containment:

```css
.ad-slot {
  contain: layout size;
  min-height: 250px;
  min-width: 300px;
  background: var(--ui-bg-muted);
}

.ad-slot::before {
  content: 'Advertisement';
  display: flex;
  align-items: center;
  justify-content: center;
  height: 100%;
  color: var(--ui-text-dimmed);
  font-size: 11px;
  text-transform: uppercase;
  letter-spacing: 0.5px;
}

.ad-slot:has(iframe)::before {
  display: none;
}
```

The `**contain: layout size**` tells the browser this element won't affect layout outside its bounds. Critical for preventing CLS.

### 2. use aspect-ratio for video embeds

YouTube, Vimeo, and most video platforms use 16:9. Reserve it:

```css
.video-embed {
  aspect-ratio: 16/9;
  width: 100%;
  contain: layout;
  background: #000;
}

.video-embed iframe {
  width: 100%;
  height: 100%;
  border: 0;
}
```

```html
<div class="video-embed">
  <iframe
    src="https://www.youtube.com/embed/VIDEO_ID"
    loading="lazy"
    title="Video title"
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
    allowfullscreen
  ></iframe>
</div>
```

### 3. facade pattern for embeds

Load a static preview, replace with real embed on interaction. Eliminates CLS and improves page load:

```html
<div class="youtube-facade" data-video-id="dQw4w9WgXcQ">
  <img
    src="https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg"
    alt="Video thumbnail"
    width="1280"
    height="720"
  >
  <button class="play-button" aria-label="Play video">
    <svg viewBox="0 0 68 48" width="68" height="48">
      <path fill="#f00" d="M66.52 7.74c-.78-2.93-2.49-5.41-5.42-6.19C55.79.13 34 0 34 0S12.21.13 6.9 1.55c-2.93.78-4.63 3.26-5.42 6.19C.06 13.05 0 24 0 24s.06 10.95 1.48 16.26c.78 2.93 2.49 5.41 5.42 6.19C12.21 47.87 34 48 34 48s21.79-.13 27.1-1.55c2.93-.78 4.64-3.26 5.42-6.19C67.94 34.95 68 24 68 24s-.06-10.95-1.48-16.26z"/>
      <path fill="#fff" d="M45 24L27 14v20"/>
    </svg>
  </button>
</div>
```

```css
.youtube-facade {
  aspect-ratio: 16/9;
  width: 100%;
  position: relative;
  cursor: pointer;
  background: #000;
}

.youtube-facade img {
  width: 100%;
  height: 100%;
  object-fit: cover;
}

.play-button {
  position: absolute;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  background: none;
  border: none;
  cursor: pointer;
  transition: transform 0.2s;
}

.play-button:hover {
  transform: translate(-50%, -50%) scale(1.1);
}
```

```js
document.querySelectorAll('.youtube-facade').forEach((facade) => {
  facade.addEventListener('click', () => {
    const videoId = facade.dataset.videoId
    const iframe = document.createElement('iframe')
    iframe.src = `https://www.youtube-nocookie.com/embed/${videoId}?autoplay=1`
    iframe.allow = 'autoplay; encrypted-media; picture-in-picture'
    iframe.allowFullscreen = true
    iframe.style.cssText = 'width:100%;height:100%;border:0;position:absolute;top:0;left:0'
    facade.innerHTML = ''
    facade.appendChild(iframe)
  })
})
```

### 4. handle social media embeds

Twitter/X embeds are notoriously bad for CLS - they load, measure content, then resize. Reserve generous space:

```css
.twitter-embed {
  min-height: 400px; /* Twitter cards are tall */
  contain: layout;
}

.instagram-embed {
  aspect-ratio: 4/5;
  min-height: 500px;
  contain: layout;
}
```

Better: Use oEmbed APIs and render static previews:

```js
// Fetch embed data server-side, render static HTML
// Only load interactive widget on user request
```

### 5. sticky ads avoid CLS

Ads at screen edges with `**position: fixed**` or `**position: sticky**` don't cause layout shifts:

```css
.sticky-ad {
  position: sticky;
  top: 20px;
  height: 600px;
  width: 160px;
}

.fixed-bottom-ad {
  position: fixed;
  bottom: 0;
  left: 0;
  right: 0;
  height: 50px;
  z-index: 1000;
}
```

### 6. handle ad collapse

Sometimes no ad fills the slot. Handle gracefully:

```js
// Example: Google Publisher Tag collapse callback
googletag.pubads().addEventListener('slotRenderEnded', (event) => {
  if (event.isEmpty) {
    const slot = document.getElementById(event.slot.getSlotElementId())
    slot.style.minHeight = '0'
    slot.style.transition = 'min-height 0.3s ease-out'
  }
})
```

The transition smooths the collapse. Still causes CLS, but reduces perceived jank.

## Framework solutions

**Next.js**

Use `**next/script**` with `**lazyOnload**` and always wrap in sized container:

```jsx
import Script from 'next/script'

export function AdSlot({ width = 300, height = 250 }) {
  return (
    <div
      style={{
        minWidth: width,
        minHeight: height,
        contain: 'layout size'
      }}
    >
      <Script
        src="https://securepubads.g.doubleclick.net/tag/js/gpt.js"
        strategy="lazyOnload"
      />
      <div id="ad-slot-1" />
    </div>
  )
}
```

For YouTube, use `**@next/third-parties**`:

```jsx
import { YouTubeEmbed } from '@next/third-parties/google'

export const Video = () => <YouTubeEmbed videoid="dQw4w9WgXcQ" />
```

**Nuxt**

Use `**useScript**` with idle trigger:

```html
<script setup>
const adLoaded = ref(false)

useScript('https://securepubads.g.doubleclick.net/tag/js/gpt.js', {
  trigger: 'idle',
  onLoad: () => { adLoaded.value = true }
})
</script>

<template>
  <div class="ad-container" :class="{ loaded: adLoaded }">
    <div id="ad-slot" />
  </div>
</template>

<style scoped>
.ad-container {
  min-height: 250px;
  min-width: 300px;
  contain: layout size;
}
</style>
```

For YouTube, use `**nuxt-youtube**` or lite-youtube-embed.

## Verification

After implementing:

1. **Throttle network** to Slow 3G in DevTools
2. **Watch the page load**: container should appear with placeholder, then ad loads inside without shift
3. **Check Layout Shift Regions**: no flashes around embed areas
4. **Run Lighthouse**: CLS should improve significantly
5. **Use `**PerformanceObserver**`**: iframe-related shifts should be gone

**Expected improvement:** 0.1-0.3 CLS reduction per properly reserved embed.

## Common mistakes

- **Forgetting contain: layout**: Without it, ad content can still affect surrounding layout
- **Wrong size estimates**: Check your ad network's actual creative sizes
- **Not handling responsive**: Use `**min-height**` not `**height**` so content can expand
- **Loading all embeds eagerly**: Use `**loading="lazy"**` or facade patterns

## Working with ad networks

Push back on your ad provider:

- Request fixed-size ad units only
- Ask for collapse callbacks
- Consider fewer, larger placements over many small ones
- Use sticky/fixed positions where possible

## Related issues

- [**~~Unsized Images~~**](https://unlighthouse.dev/learn-lighthouse/cls/unsized-images) - Same reserved space principle
- [**~~Dynamic Content~~**](https://unlighthouse.dev/learn-lighthouse/cls/dynamic-content-injection) - Ads are dynamic content

## Site-wide audit

Ad and embed placements vary across templates. [**~~Unlighthouse~~**](https://unlighthouse.dev/) scans your entire site and identifies which pages have CLS from third-party content.

### **Related **

[**CLS Overview**](https://unlighthouse.dev/learn-lighthouse/cls) [**All CLS Issues**](https://unlighthouse.dev/learn-lighthouse/cls#common-cls-issues) [**CLS Definition**](https://unlighthouse.dev/glossary/cls) [**CLS Debugger Tool**](https://unlighthouse.dev/tools/cls-debugger)

[**Dynamic Content** Stop cookie banners, notifications, and lazy-loaded content from causing layout shifts with space reservation and transforms.](https://unlighthouse.dev/learn-lighthouse/cls/dynamic-content-injection) [**Animations & Transitions** Eliminate CLS from animations by using compositor-friendly properties like transform and opacity instead of layout-triggering properties.](https://unlighthouse.dev/learn-lighthouse/cls/animations-transitions)

**On this page **

- [What lighthouse detects](#what-lighthouse-detects)
- [Why this destroys CLS](#why-this-destroys-cls)
- [Strategic insights](#strategic-insights)
- [How to diagnose](#how-to-diagnose)
- [The fixes](#the-fixes)
- [Framework solutions](#framework-solutions)
- [Verification](#verification)
- [Common mistakes](#common-mistakes)
- [Working with ad networks](#working-with-ad-networks)
- [Related issues](#related-issues)
- [Site-wide audit](#site-wide-audit)

---

- **Page:** Fix Long-Running JavaScript for Better INP · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/inp/long-running-javascript
- **Description:** Reduce JavaScript execution time to improve INP. Learn code splitting, web workers, and task chunking to keep the main thread responsive.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Long-Running JavaScript for Better INP**

Reduce JavaScript execution time to improve INP. Learn code splitting, web workers, and task chunking to keep the main thread responsive.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)8 min read Published **Jan 18, 2025**

Any JavaScript task over 50ms blocks user input. The median site has 3.5 seconds of JavaScript execution time. That's 70 opportunities for users to experience delayed interactions.

Lighthouse's `**bootup-time**` audit measures total script evaluation and parse time. Sites scoring green keep execution under 1.3 seconds. Red flags appear above 3.5 seconds. But even well-scoring sites can have poor INP if that time isn't broken into small chunks.

**TBT**Total Blocking Time

**30% weight **

Good ≤200msPoor >600ms

## What's the problem?

Browsers run JavaScript on the main thread. The same thread handles user input, layout calculations, and painting. When JavaScript monopolizes this thread, everything else waits.

A click handler can't fire. A scroll can't register. A keystroke goes unacknowledged. The user sees a frozen interface.

**Accessibility is critically impacted.** Screen readers rely on the main thread to receive updates from the Accessibility Tree. When JavaScript blocks the main thread, screen readers go silent. A blind user tabbing through your site won't hear "Link: Checkout" until the blocked task finishes - making your site effectively unusable.

**The 50ms threshold matters.** Human perception research shows delays under 100ms feel instantaneous. At 50ms task length, the browser has 50ms buffer to respond before users notice lag. Longer tasks eat into that buffer.

**How Lighthouse calculates this:** The `**bootup-time**` audit sums all script evaluation and parsing time for scripts exceeding 50ms total execution. It applies CPU throttling (4x on mobile simulation) to reflect real device performance.

## Common causes

**Large bundles downloading and parsing at once.** A 500KB JavaScript file doesn't just download slowly. It also blocks the main thread during parsing and compilation. V8 can parse \~1MB/second on mobile, meaning that bundle blocks for 500ms before a single line executes.

**Synchronous data processing.** Filtering 10,000 items in a single loop. Sorting a large dataset. Transforming nested JSON structures. Each operation keeps the main thread busy.

**Heavy initialization.** Third-party libraries that run expensive setup code on load. Analytics packages building user profiles. Feature detection libraries testing browser capabilities.

**Unoptimized framework hydration.** [**~~React~~**](https://react.dev), Vue, and [**~~Svelte~~**](https://svelte.dev) all need to "wake up" server-rendered HTML. Poorly structured component trees mean thousands of elements traversed synchronously.

## How to identify

### Chrome DevTools performance panel

1. Open DevTools (F12)
2. Go to Performance tab
3. Click record, interact with your page, stop recording
4. Look at the Main thread row
5. Tasks with red corners exceed 50ms

Long yellow blocks labeled "Evaluate Script" or "Parse Script" indicate JavaScript execution. Click any task to see the call stack and identify the responsible script.

### Lighthouse treemap

Run Lighthouse, then click "View Treemap" on the `**bootup-time**` audit. You'll see execution time broken down by script URL. The largest blocks are your optimization targets.

### Web vitals attribution

```js
import { onINP } from 'web-vitals/attribution'

onINP((metric) => {
  const { inputDelay, processingDuration, presentationDelay } = metric.attribution
  // inputDelay > 100ms means main thread was busy when user interacted
  // processingDuration > 100ms means the handler itself ran too long
  console.log({ inputDelay, processingDuration, presentationDelay })
})
```

## The fix

### 1. code split your bundles

Don't load everything upfront. Split code by route and by feature.

```js
// Before: loads entire admin module on every page
import { AdminDashboard, AdminSettings, AdminUsers } from './admin'

// After: loads each component on demand
const AdminDashboardLazy = () => import('./admin/Dashboard')
const AdminUsersLazy = () => import('./admin/Users')
const AdminSettingsLazy = () => import('./admin/Settings')
```

Route-based splitting is table stakes. Feature-based splitting targets the long tail: modals, dropdowns, charts that most users never see.

```js
// Load chart library only when user opens analytics
async function showAnalytics() {
  const { Chart } = await import('chart.js')
  const chart = new Chart(canvas, config)
}
```

### 2. move heavy work to web workers

Web Workers run on a separate thread. They can't access the DOM, but they're perfect for data processing.

```js
// main.js
const worker = new Worker(new URL('./processor.worker.js', import.meta.url))

function processData(items) {
  return new Promise((resolve) => {
    worker.postMessage({ items })
    worker.onmessage = e => resolve(e.data.result)
  })
}

// processor.worker.js
globalThis.onmessage = (e) => {
  const { items } = e.data
  // This runs on a separate thread - main thread stays responsive
  const result = items.map(expensiveTransform).filter(predicate).sort(compareFn)
  globalThis.postMessage({ result })
}
```

Libraries like Comlink simplify Worker communication with a function-call API.

### 3. yield to the main thread

When you can't avoid main thread work, yield periodically to let the browser handle interactions.

```js
// Before: blocks for entire loop duration
function processItems(items) {
  items.forEach(item => expensiveOperation(item))
}

// After: yields every 100 items
async function processItemsAsync(items) {
  const chunkSize = 100
  for (let i = 0; i < items.length; i += chunkSize) {
    const chunk = items.slice(i, i + chunkSize)
    chunk.forEach(item => expensiveOperation(item))
    await scheduler.yield()
  }
}
```

**Why `**scheduler.yield()**` over `**setTimeout(0)**`:** Both yield control, but `**setTimeout**` moves your task to the back of the queue. Other scripts can cut in line. `**scheduler.yield()**` maintains your position while still letting the browser handle urgent work like user input.

```js
// Polyfill for browsers without scheduler.yield
if (!globalThis.scheduler?.yield) {
  globalThis.scheduler = {
    ...globalThis.scheduler,
    yield: () => new Promise(resolve => setTimeout(resolve, 0))
  }
}
```

### 4. use requestidlecallback for non-critical work

Analytics, prefetching, and background sync don't need to run immediately.

```js
function initAnalytics() {
  if ('requestIdleCallback' in window) {
    requestIdleCallback(() => {
      loadAnalyticsSDK()
      sendPageView()
    }, { timeout: 5000 }) // Give up after 5 seconds
  }
  else {
    // Fallback: delay 1 second
    setTimeout(loadAnalyticsSDK, 1000)
  }
}
```

### 5. check for pending input

The `**isInputPending()**` API lets you yield only when users are waiting.

```js
async function processLargeDataset(data) {
  for (let i = 0; i < data.length; i++) {
    processItem(data[i])

    // Only yield if user is trying to interact
    if (i % 100 === 0 && navigator.scheduling?.isInputPending()) {
      await scheduler.yield()
    }
  }
}
```

## Framework-specific solutions

**Next.js**

Use `**dynamic()**` for components not needed at initial render:

```jsx
import dynamic from 'next/dynamic'

const HeavyChart = dynamic(() => import('./Chart'), {
  loading: () => <ChartSkeleton />,
  ssr: false // Skip server rendering for client-only components
})
```

React 18's `**useTransition**` marks updates as non-urgent:

```jsx
const [isPending, startTransition] = useTransition()

function handleFilter(query) {
  startTransition(() => {
    // This state update won't block typing
    setFilteredResults(filterData(query))
  })
}
```

**Nuxt**

Lazy-load components with the `**Lazy**` prefix:

```html
<template>
  <LazyHeavyChart v-if="showChart" :data="chartData" />
</template>
```

Use `**callOnce()**` to prevent duplicate initialization:

```html
<script setup>
await callOnce(async () => {
  // Runs once, even across hydration
  await initializeExpensiveFeature()
})
</script>
```

**React**

`**useDeferredValue**` lets expensive renders happen during idle time:

```jsx
import { useDeferredValue } from 'react'

function SearchResults({ query }) {
  const deferredQuery = useDeferredValue(query)

  // Filtering runs when browser is idle
  const results = useMemo(
    () => items.filter(item => item.name.includes(deferredQuery)),
    [deferredQuery]
  )

  return <ResultsList items={results} />
}
```

## Verify the fix

1. Run Lighthouse before and after. Check `**bootup-time**` and TBT metrics.
2. Record a Performance trace during interaction. Confirm no tasks exceed 50ms.
3. Test on throttled CPU (4x slowdown) to simulate mobile devices.

**Expected improvement:** Breaking a 500ms task into 50ms chunks can reduce INP from 500ms to under 100ms. The math is direct: you've eliminated 450ms of main thread blocking.

## Common mistakes

**Yielding too frequently.** Each yield has \~4ms overhead. Yielding after every array item turns a 100ms task into a 400ms series of microtasks.

**Using setTimeout for everything.** `**setTimeout(fn, 0)**` still blocks if the callback runs too long. You need to yield inside the callback, not before it.

**Optimizing the wrong scripts.** Profile first. That tiny utility library isn't your problem. The 800KB charting library is.

**Ignoring third-party scripts.** Your code might be clean, but that embedded chat widget runs a 200ms initialization. Third-party scripts need the same scrutiny.

## Related issues

Often appears alongside:

- [**~~Total Blocking Time~~**](https://unlighthouse.dev/learn-lighthouse/inp/total-blocking-time) - The lab metric that proxies INP
- [**~~Third-Party Scripts~~**](https://unlighthouse.dev/learn-lighthouse/inp/third-party-scripts) - External scripts causing long tasks
- [**~~Event Handler Delays~~**](https://unlighthouse.dev/learn-lighthouse/inp/event-handler-delays) - Handlers doing too much work

## Test your entire site

JavaScript execution varies wildly by page. Your homepage might be fast while your checkout flow runs 5 seconds of script. [**~~Unlighthouse~~**](https://unlighthouse.dev/) scans every page and surfaces the worst offenders.

### **Related **

[**INP Overview**](https://unlighthouse.dev/learn-lighthouse/inp) [**All INP Issues**](https://unlighthouse.dev/learn-lighthouse/inp#common-inp-issues) [**INP Definition**](https://unlighthouse.dev/glossary/inp) [**INP Analyzer Tool**](https://unlighthouse.dev/tools/inp-analyzer)

[**INP** Master INP optimization with practical fixes for JavaScript execution, DOM operations, and event handlers. Improve responsiveness across your site.](https://unlighthouse.dev/learn-lighthouse/inp) [**Total Blocking Time** Reduce TBT to improve your Lighthouse performance score. TBT measures main thread blocking - the lab proxy for real-world INP.](https://unlighthouse.dev/learn-lighthouse/inp/total-blocking-time)

**On this page **

- [What's the problem?](#whats-the-problem)
- [Common causes](#common-causes)
- [How to identify](#how-to-identify)
- [The fix](#the-fix)
- [Framework-specific solutions](#framework-specific-solutions)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix Animations &amp; Transitions for Better CLS · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/cls/animations-transitions
- **Description:** Eliminate CLS from animations by using compositor-friendly properties like transform and opacity instead of layout-triggering properties.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Animations & Transitions for Better CLS**

Eliminate CLS from animations by using compositor-friendly properties like transform and opacity instead of layout-triggering properties.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)5 min read Published **Jan 18, 2025**

39% of mobile pages use non-composited animations that trigger layout recalculations on every frame. These animations cause CLS, jank, and battery drain - all avoidable with the right CSS properties.

**CLS**Cumulative Layout Shift** CWV **

**25% weight **

Good ≤0.10Poor >0.25

## What lighthouse detects

The `**non-composited-animations**` audit flags animations that can't run on the GPU compositor. It reports:

- **Unsupported CSS Properties**: Properties like `**width**`, `**height**`, `**top**`, `**left**`, `**margin**`, `**padding**` that require layout calculations
- **Custom CSS Properties**: CSS variables ( `**--custom-prop**`) can't be composited
- **Transform depends on box size**: Percentage-based transforms that need layout info
- **Filter may move pixels**: Certain filters that affect layout
- **Incompatible animations**: Multiple animations on the same element conflicting

When you see "Avoid non-composited animations" in Lighthouse, your animations are causing the browser to recalculate layout repeatedly.

## Why non-composited animations hurt

The browser renders in layers:

1. **Main thread**: JavaScript, DOM, layout calculations
2. **Compositor thread**: GPU-accelerated rendering of `**transform**` and `**opacity**`

When you animate layout properties, every frame requires:

- Recalculating element positions (Layout)
- Repainting affected pixels (Paint)
- Compositing layers (Composite)

When you animate compositor properties, only step 3 runs. It's 60fps vs stuttering.

**CLS impact:** Each layout recalculation during animation can register as a layout shift. A modal sliding in by animating `**top**` creates measurable CLS.

## How to diagnose

### DevTools performance panel

1. Open DevTools > Performance
2. Record while triggering your animation
3. Look for purple "Layout" blocks during the animation
4. Multiple Layout events = non-composited animation

### Rendering panel

1. Open DevTools > More tools > Rendering
2. Enable "Paint flashing" (green = repaints)
3. Enable "Layout Shift Regions" (blue = shifts)
4. Trigger your animations
5. Green flashes everywhere = non-composited

### Layers panel

1. Open DevTools > More tools > Layers
2. Check if animated elements have their own layer
3. No layer = no compositor optimization

## The fixes

### 1. replace position with transform

The most common mistake - animating `**top**`, `**left**`, `**right**`, `**bottom**`:

```css
/* BAD: animates layout property */
.element {
  position: relative;
  top: 0;
  transition: top 0.3s ease;
}
.element:hover {
  top: -10px;
}

/* GOOD: animates compositor property */
.element {
  transition: transform 0.3s ease;
}
.element:hover {
  transform: translateY(-10px);
}
```

Same visual result. Zero layout shifts.

### 2. replace size with scale

Don't animate `**width**` and `**height**`:

```css
/* BAD: animates width/height */
.button {
  width: 100px;
  height: 40px;
  transition: width 0.2s, height 0.2s;
}
.button:hover {
  width: 110px;
  height: 44px;
}

/* GOOD: animates scale */
.button {
  transition: transform 0.2s ease;
}
.button:hover {
  transform: scale(1.1);
}
```

Use `**transform-origin**` to control where scaling originates:

```css
.card {
  transform-origin: top left; /* Expands from corner */
  transition: transform 0.3s ease;
}
.card:hover {
  transform: scale(1.05);
}
```

### 3. replace margin with transform

Slide-in animations often abuse margins:

```css
/* BAD: animates margin */
@keyframes slideIn {
  from { margin-left: -100%; }
  to { margin-left: 0; }
}

/* GOOD: animates transform */
@keyframes slideIn {
  from { transform: translateX(-100%); }
  to { transform: translateX(0); }
}
```

### 4. use opacity for show/hide

Fading elements is compositor-friendly:

```css
/* BAD: display/visibility causes layout */
.modal {
  display: none;
}
.modal.active {
  display: block;
}

/* GOOD: opacity + pointer-events */
.modal {
  opacity: 0;
  pointer-events: none;
  transition: opacity 0.3s ease;
}
.modal.active {
  opacity: 1;
  pointer-events: auto;
}
```

### 5. handle accordions carefully

Height animations are tricky. The "animate height" pattern always causes layout shifts:

```css
/* BAD: max-height animation */
.accordion-content {
  max-height: 0;
  overflow: hidden;
  transition: max-height 0.3s ease;
}
.accordion-content.open {
  max-height: 500px; /* Arbitrary, causes shift */
}
```

Better alternatives:

**Option A: Use CSS Grid**

```css
.accordion-content {
  display: grid;
  grid-template-rows: 0fr;
  transition: grid-template-rows 0.3s ease;
}
.accordion-content.open {
  grid-template-rows: 1fr;
}
.accordion-content > div {
  overflow: hidden;
}
```

**Option B: Reserve space, animate opacity**

```css
.accordion-content {
  height: var(--content-height); /* Set via JS */
  opacity: 0;
  overflow: hidden;
  transition: opacity 0.3s ease;
}
.accordion-content.open {
  opacity: 1;
}
```

**Option C: Accept the shift, minimize impact**

```css
.accordion-content {
  max-height: 0;
  overflow: hidden;
  transition: max-height 0.3s ease-out;
  contain: layout; /* Limit shift impact */
}
```

### 6. use will-change strategically

Hint to the browser that an element will animate:

```css
.frequently-animated {
  will-change: transform, opacity;
}
```

**Rules for will-change:**

- Only apply to elements that animate frequently
- Don't put it on everything (wastes GPU memory)
- Add before animation starts, remove after
- Don't use `**will-change: all**` - it's counterproductive

```js
// Apply before animation
element.style.willChange = 'transform'
element.addEventListener('transitionend', () => {
  element.style.willChange = 'auto'
}, { once: true })
```

### 7. use CSS containment

Tell the browser an element's layout is independent:

```css
.animated-card {
  contain: layout; /* Layout changes don't affect siblings */
}

.animated-modal {
  contain: strict; /* Fully isolated for rendering */
}
```

`**contain: layout**` prevents the element from causing layout shifts outside its bounds - essential for animated components.

### 8. avoid box-shadow animations

Box-shadow trigger repaints:

```css
/* BAD: expensive box-shadow */
.card {
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
  transition: box-shadow 0.3s;
}
.card:hover {
  box-shadow: 0 8px 24px rgba(0,0,0,0.2);
}

/* GOOD: pseudo-element technique */
.card {
  position: relative;
}
.card::after {
  content: '';
  position: absolute;
  inset: 0;
  box-shadow: 0 8px 24px rgba(0,0,0,0.2);
  opacity: 0;
  transition: opacity 0.3s;
  pointer-events: none;
}
.card:hover::after {
  opacity: 1;
}
```

## Framework solutions

**Next.js / React**

CSS transitions are fine. For complex animations, use Framer Motion with compositor-friendly properties:

```jsx
import { motion } from 'framer-motion'

// GOOD: only animates transform and opacity
export function AnimatedBox() {
  return (
    <motion.div
      initial={{ opacity: 0, y: 20 }}
      animate={{ opacity: 1, y: 0 }}
      exit={{ opacity: 0, y: -20 }}
      transition={{ duration: 0.3, ease: 'easeOut' }}
    >
      Content
    </motion.div>
  )
}
```

Avoid Framer Motion's `**layout**` prop for production - it animates layout properties and causes CLS:

```jsx
// CAREFUL: layout prop causes CLS
<motion.div layout>
  {/* This animates width/height internally */}
</motion.div>
```

**Nuxt / Vue**

Vue transitions work great when you use transform:

```html
<template>
  <Transition name="slide-fade">
    <div v-if="show">
      Content
    </div>
  </Transition>
</template>

<style>
.slide-fade-enter-active,
.slide-fade-leave-active {
  transition: transform 0.3s ease, opacity 0.3s ease;
}

.slide-fade-enter-from {
  opacity: 0;
  transform: translateX(-20px);
}

.slide-fade-leave-to {
  opacity: 0;
  transform: translateX(20px);
}
</style>
```

For lists, Vue's TransitionGroup uses FLIP (compositor-friendly):

```html
<template>
  <TransitionGroup name="list" tag="ul">
    <li v-for="item in items" :key="item.id">
      {{ item.name }}
    </li>
  </TransitionGroup>
</template>

<style>
.list-move {
  transition: transform 0.5s ease;
}
.list-enter-active,
.list-leave-active {
  transition: opacity 0.3s ease, transform 0.3s ease;
}
.list-enter-from,
.list-leave-to {
  opacity: 0;
  transform: scale(0.9);
}
</style>
```

**Tailwind CSS**

Tailwind's animation utilities use compositor properties by default:

```html
<!-- GOOD: these are compositor-friendly -->
<div class="animate-fade-in" /> <!-- opacity -->
<div class="animate-slide-up" /> <!-- transform -->
<div class="hover:scale-105 transition-transform" />
<div class="hover:-translate-y-1 transition-transform" />

<!-- CAREFUL: these might not be -->
<div class="animate-pulse" /> <!-- uses opacity, fine -->
<div class="animate-bounce" /> <!-- uses transform, fine -->
```

Define custom animations with compositor properties:

```js
// tailwind.config.js
export default {
  theme: {
    extend: {
      keyframes: {
        'slide-in': {
          '0%': { transform: 'translateX(-100%)', opacity: '0' },
          '100%': { transform: 'translateX(0)', opacity: '1' }
        }
      },
      animation: {
        'slide-in': 'slide-in 0.3s ease-out'
      }
    }
  }
}
```

## Verification

After fixing:

1. **Performance panel**: Record animation, look for absence of purple Layout blocks
2. **Layers panel**: Confirm animated elements have dedicated compositor layers
3. **Paint flashing**: Minimal or no green flashes during animation
4. **Layout Shift Regions**: No blue flashes during animation
5. **Lighthouse audit**: "Avoid non-composited animations" should pass

**Expected improvement:** 0.01-0.1 CLS reduction. More importantly, smoother 60fps animations.

## Compositable properties reference

**Safe to animate (GPU-accelerated):**

- `**transform**` (translate, rotate, scale, skew)
- `**opacity**`
- `**filter**` (with caveats)

**Never animate:**

- `**width**`, `**height**`
- `**top**`, `**right**`, `**bottom**`, `**left**`
- `**margin**`, `**padding**`
- `**border-width**`
- `**font-size**`

**Expensive but sometimes necessary:**

- `**background-color**` (triggers paint, not layout)
- `**box-shadow**` (triggers paint)
- `**clip-path**` (compositor in some browsers)

## Common mistakes

- **Animating CSS custom properties**: `**--my-var**` can't be composited
- **Using `**left**` on fixed elements**: Even fixed elements should use transform
- **will-change on everything**: Causes memory issues, only use on frequently animated elements
- **Mixing composited and non-composited**: Browser may demote to non-composited

## Related issues

- [**~~Dynamic Content~~**](https://unlighthouse.dev/learn-lighthouse/cls/dynamic-content-injection) - Animated content appearing
- [**~~Web Fonts~~**](https://unlighthouse.dev/learn-lighthouse/cls/web-fonts-causing-foit) - Font loading triggering animations

## Site-wide audit

Animation issues affect different templates differently. [**~~Unlighthouse~~**](https://unlighthouse.dev/) scans your entire site and identifies pages with non-composited animations.

### **Related **

[**CLS Overview**](https://unlighthouse.dev/learn-lighthouse/cls) [**All CLS Issues**](https://unlighthouse.dev/learn-lighthouse/cls#common-cls-issues) [**CLS Definition**](https://unlighthouse.dev/glossary/cls) [**CLS Debugger Tool**](https://unlighthouse.dev/tools/cls-debugger)

[**Ads, Embeds & iframes** Prevent layout shifts from third-party ads, video embeds, social widgets, and iframes with reserved space techniques.](https://unlighthouse.dev/learn-lighthouse/cls/ads-embeds-iframes) [**INP** Master INP optimization with practical fixes for JavaScript execution, DOM operations, and event handlers. Improve responsiveness across your site.](https://unlighthouse.dev/learn-lighthouse/inp)

**On this page **

- [What lighthouse detects](#what-lighthouse-detects)
- [Why non-composited animations hurt](#why-non-composited-animations-hurt)
- [How to diagnose](#how-to-diagnose)
- [The fixes](#the-fixes)
- [Framework solutions](#framework-solutions)
- [Verification](#verification)
- [Compositable properties reference](#compositable-properties-reference)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Site-wide audit](#site-wide-audit)

---

- **Page:** Fix Dynamic Content Injection for Better CLS · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/cls/dynamic-content-injection
- **Description:** Stop cookie banners, notifications, and lazy-loaded content from causing layout shifts with space reservation and transforms.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Dynamic Content Injection for Better CLS**

Stop cookie banners, notifications, and lazy-loaded content from causing layout shifts with space reservation and transforms.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)7 min read Published **Jan 18, 2025**

Dynamic content is the silent CLS killer. 73% of pages with poor CLS scores have at least one element injected above existing content after initial render. Banners, notifications, cookie consent - they all push your content down.

**CLS**Cumulative Layout Shift** CWV **

**25% weight **

Good ≤0.10Poor >0.25

## What's the problem?

Dynamic content injection means adding elements to the DOM after the page has rendered. When you inject content above existing content, everything below shifts down. The browser reports this as a layout shift.

The most common offenders:

- **Cookie consent banners** at the top of the page
- **Notification bars** (sales, announcements, promotions)
- **Async-loaded components** that push siblings down
- **Lazy-loaded content** without reserved space
- **Sticky headers** that appear after scroll
- **Chat widgets** that resize their container

The math is brutal. A 100px banner on a 800px viewport causes a shift score of \~0.125. Add a notification toast and a late-loading promo? You've already exceeded Google's 0.1 threshold before the user even scrolls.

**Why it matters:** Users start reading your content. Then everything jumps. They lose their place. On mobile, they accidentally tap the wrong link. Frustration compounds with each shift. Google penalizes pages with CLS above 0.1 in search rankings.

## How to identify this issue

### Chrome DevTools

**Performance Panel:**

1. Open DevTools > Performance
2. Enable "Web Vitals" checkbox
3. Record a page load
4. Look for Layout Shift entries in the timeline
5. Click each to see which element moved

**Layout Shift Regions:**

1. Open DevTools > Rendering panel (three dots > More tools > Rendering)
2. Enable "Layout Shift Regions"
3. Reload the page
4. Watch for blue/green flashes when banners or notifications appear

**Elements Panel:**

Monitor DOM mutations while loading:

1. Open Elements panel
2. Right-click `**<body>**` > Break on > Subtree modifications
3. Reload and step through each DOM insertion

### Performance observer

Track shifts in real-time with their sources:

```js
new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (entry.hadRecentInput)
      continue // Ignore user-triggered shifts

    console.group(`Shift: ${entry.value.toFixed(4)}`)
    console.log('Time:', entry.startTime.toFixed(0), 'ms')

    entry.sources?.forEach((source) => {
      const el = source.node
      console.log('Element:', el?.tagName, el?.className)
      console.log('Moved from:', source.previousRect)
      console.log('Moved to:', source.currentRect)
    })
    console.groupEnd()
  }
}).observe({ type: 'layout-shift', buffered: true })
```

Look for shifts where the moved element is NOT the injected content but what came after it. That's your culprit.

## Crawler vs. user experience

It's possible to have a "Good" CLS score for real users but a "Poor" score in Google Search Console. This often happens due to **bot rendering differences**:

1. **Robots.txt Blocking**: If your `**robots.txt**` blocks Googlebot from crawling specific CSS or JS files used for layout (e.g., a styling script for a dynamic banner), the bot renders the page without them. It might see a layout shift that real users don't.
2. **Cookie Banners**: Bots visit as "new users" every time. They *always* see the cookie banner. If you only test as a logged-in user or with cookies accepted, you'll miss the massive shift the bot sees on every crawl.
3. **Viewport Meta Tag**: Ensure `**<meta name="viewport" content="width=device-width, initial-scale=1">**` is present. Without it, mobile bots may render a desktop width and then snap to mobile, triggering shifts.

## The fix

### 1. reserve space for known content

If you know content will appear, reserve its space from the start.

**Cookie banners with fixed height:**

```css
/* Reserve space in HTML before the banner loads */
.cookie-banner-placeholder {
  min-height: 80px;
  contain: layout;
}

.cookie-banner {
  min-height: 80px;
}
```

```html
<div class="cookie-banner-placeholder">
  <!-- Banner script injects here -->
</div>
<main>
  <!-- Page content stays put -->
</main>
```

**Notification bars:**

```css
.notification-slot {
  min-height: 48px;
  contain: layout size;
}

/* Hide when empty */
.notification-slot:empty {
  min-height: 0;
  transition: min-height 0.2s ease-out;
}
```

The `**contain: layout size**` property tells the browser this element won't affect layout outside its bounds.

### 2. use transforms instead of layout changes

Transforms don't trigger layout recalculation. Slide content in rather than inserting it.

**Slide-down banner:**

```css
.promo-banner {
  transform: translateY(-100%);
  transition: transform 0.3s ease-out;
  position: relative;
  z-index: 100;
}

.promo-banner.visible {
  transform: translateY(0);
}
```

```js
// Show banner without causing layout shift
const banner = document.querySelector('.promo-banner')
banner.classList.add('visible')
```

**Toast notifications:**

```css
.toast-container {
  position: fixed;
  top: 16px;
  right: 16px;
  z-index: 1000;
}

.toast {
  transform: translateX(120%);
  opacity: 0;
  transition: transform 0.3s ease-out, opacity 0.2s;
}

.toast.show {
  transform: translateX(0);
  opacity: 1;
}
```

Fixed/absolute positioned elements don't cause layout shifts because they're outside normal document flow.

### 3. fixed/sticky positioning from start

Elements with `**position: fixed**` or `**position: sticky**` don't cause CLS when they appear. The key is setting the position BEFORE the element renders, not after.

**Cookie banner that never shifts:**

```css
.cookie-consent {
  position: fixed;
  bottom: 0;
  left: 0;
  right: 0;
  transform: translateY(100%);
  transition: transform 0.3s ease-out;
}

.cookie-consent.show {
  transform: translateY(0);
}
```

**Sticky header done right:**

```css
/* Wrong: starts static, becomes sticky */
.header {
  position: relative;
}
.header.scrolled {
  position: sticky; /* This causes shift */
}

/* Right: always sticky */
.header {
  position: sticky;
  top: 0;
}
```

**Late-appearing sticky nav:**

```css
.sticky-nav {
  position: sticky;
  top: 60px;
  opacity: 0;
  pointer-events: none;
  transition: opacity 0.2s;
}

.sticky-nav.visible {
  opacity: 1;
  pointer-events: auto;
}
```

### 4. skeleton screens

For async content that must be in document flow, show a skeleton with matching dimensions:

```html
<div class="user-profile" data-user-id="123">
  <!-- Skeleton shown immediately -->
  <div class="skeleton">
    <div class="skeleton-avatar"></div>
    <div class="skeleton-text"></div>
    <div class="skeleton-text short"></div>
  </div>
</div>
```

```css
.user-profile {
  min-height: 120px; /* Match actual content height */
  contain: layout;
}

.skeleton {
  display: flex;
  gap: 16px;
  padding: 16px;
}

.skeleton-avatar {
  width: 80px;
  height: 80px;
  border-radius: 50%;
  background: var(--ui-bg-muted);
}

.skeleton-text {
  height: 16px;
  background: var(--ui-bg-muted);
  border-radius: 4px;
  width: 200px;
}

.skeleton-text.short {
  width: 100px;
}
```

```js
// Replace skeleton with real content—same container size
async function loadProfile(container) {
  const data = await fetch(`/api/user/${container.dataset.userId}`)
  container.innerHTML = renderProfile(data)
  // No shift because container height matches
}
```

### Why this works

Layout shifts occur when the browser recalculates element positions. Three strategies avoid this:

1. **Reserved space**: Browser allocates room upfront. When content fills it, nothing moves.
2. **Transforms**: CSS transforms don't trigger layout. Elements visually move without affecting siblings.
3. **Fixed/sticky positioning**: These elements exist in their own layer. They never participate in document flow.
4. **Skeletons**: Matching dimensions means swapping content doesn't resize the container.

The common thread: tell the browser exactly where things will be BEFORE they appear.

## Framework-specific solutions

**Next.js**

Handle dynamic content with Suspense boundaries:

```jsx
import { Suspense } from 'react'

function Page() {
  return (
    <>
      <CookieBanner />
      {' '}
      {/* Fixed position, no shift */}

      <Suspense fallback={<NotificationSkeleton />}>
        <NotificationBar />
      </Suspense>

      <main>
        <Suspense fallback={<div style={{ minHeight: 400 }} />}>
          <AsyncContent />
        </Suspense>
      </main>
    </>
  )
}

// Cookie banner with transform animation
function CookieBanner() {
  const [show, setShow] = useState(true)

  return (
    <div
      className={`fixed bottom-0 inset-x-0 transform transition-transform ${
        show ? 'translate-y-0' : 'translate-y-full'
      }`}
    >
      <div className="bg-white p-4 shadow-lg">
        <p>We use cookies...</p>
        <button onClick={() => setShow(false)}>Accept</button>
      </div>
    </div>
  )
}
```

For notifications, use a portal to fixed container:

```jsx
import { createPortal } from 'react-dom'

function Toast({ message }) {
  return createPortal(
    <div className="fixed top-4 right-4 animate-slide-in">
      {message}
    </div>,
    document.body
  )
}
```

**Nuxt**

Use `**ClientOnly**` with sized fallbacks:

```html
<script setup>
// Cookie banner uses transform, not layout
const showBanner = ref(true)
</script>

<template>
  <div>
    <!-- Fixed position cookie banner -->
    <CookieBanner class="fixed bottom-0 inset-x-0" />

    <!-- Async content with reserved space -->
    <ClientOnly>
      <PromoBar />
      <template #fallback>
        <div class="h-12 bg-gray-100" />
      </template>
    </ClientOnly>

    <main>
      <ClientOnly>
        <UserDashboard />
        <template #fallback>
          <DashboardSkeleton />
        </template>
      </ClientOnly>
    </main>
  </div>
</template>
```

For notifications, use Nuxt UI's toast system which uses fixed positioning:

```html
<script setup>
const toast = useToast()

// Toasts appear in fixed container—no CLS
toast.add({ title: 'Success!' })
</script>
```

## Verify the fix

**1. Before/After Lighthouse**

Run Lighthouse before and after. The "Avoid large layout shifts" audit should show fewer shifts from injected elements.

**2. Performance Observer Check**

```js
let injectionShifts = 0

new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (!entry.hadRecentInput && entry.startTime > 500) {
      // Shifts after 500ms are likely from dynamic content
      injectionShifts++
      console.log('Late shift detected:', entry.value)
    }
  }
}).observe({ type: 'layout-shift', buffered: true })

// After page load
setTimeout(() => {
  console.log('Dynamic content shifts:', injectionShifts)
}, 5000)
```

**3. Visual Test**

Record screen while loading on Slow 3G. Play at 0.5x speed. Banners and notifications should slide/fade in, not push content.

**Expected improvement:** Pages with cookie banners and notifications typically drop from 0.2-0.3 CLS to under 0.05 after fixes.

## Common mistakes

**Reserving wrong dimensions**

```css
/* Wrong: too small */
.banner-slot { min-height: 40px; }

/* Right: match actual banner */
.banner-slot { min-height: 80px; }
```

Measure your actual banner height including padding and margins.

**Animating height instead of transform**

```css
/* Wrong: animates layout property */
.banner {
  height: 0;
  transition: height 0.3s;
}
.banner.show { height: 80px; }

/* Right: animates transform */
.banner {
  transform: scaleY(0);
  transform-origin: top;
  transition: transform 0.3s;
}
.banner.show { transform: scaleY(1); }
```

**Starting sticky too late**

```js
// Wrong: makes sticky after scroll
window.addEventListener('scroll', () => {
  if (window.scrollY > 100) {
    header.style.position = 'sticky' // Causes shift
  }
})

// Right: always sticky, just change appearance
window.addEventListener('scroll', () => {
  header.classList.toggle('compact', window.scrollY > 100)
})
```

**Lazy loading without placeholders**

```html
<!-- Wrong -->
<div class="lazy-section" data-load-on-scroll>
  <!-- Content loads, pushes everything down -->
</div>

<!-- Right -->
<div class="lazy-section" data-load-on-scroll style="min-height: 400px;">
  <div class="skeleton">...</div>
</div>
```

## Related issues

- [**~~Large Layout Shifts~~**](https://unlighthouse.dev/learn-lighthouse/cls/layout-shifts) - General shift debugging
- [**~~Ads, Embeds & iframes~~**](https://unlighthouse.dev/learn-lighthouse/cls/ads-embeds-iframes) - Third-party injection
- [**~~Animations & Transitions~~**](https://unlighthouse.dev/learn-lighthouse/cls/animations-transitions) - Motion that causes shifts
- [**~~Web Fonts~~**](https://unlighthouse.dev/learn-lighthouse/cls/web-fonts-causing-foit) - Font loading shifts

## Test your entire site

Different pages have different dynamic content patterns. Your homepage might have a promo banner. Product pages might have stock notifications. Blog posts might have newsletter popups. [**~~Unlighthouse~~**](https://unlighthouse.dev/) scans every page and identifies which dynamic elements are causing CLS problems across your entire site.

### **Related **

[**CLS Overview**](https://unlighthouse.dev/learn-lighthouse/cls) [**All CLS Issues**](https://unlighthouse.dev/learn-lighthouse/cls#common-cls-issues) [**CLS Definition**](https://unlighthouse.dev/glossary/cls) [**CLS Debugger Tool**](https://unlighthouse.dev/tools/cls-debugger)

[**Web Fonts (FOIT/FOUT)** How to prevent layout shifts from web font loading using font-display, preloading, and fallback metrics.](https://unlighthouse.dev/learn-lighthouse/cls/web-fonts-causing-foit) [**Ads, Embeds & iframes** Prevent layout shifts from third-party ads, video embeds, social widgets, and iframes with reserved space techniques.](https://unlighthouse.dev/learn-lighthouse/cls/ads-embeds-iframes)

**On this page **

- [What's the problem?](#whats-the-problem)
- [How to identify this issue](#how-to-identify-this-issue)
- [Crawler vs. user experience](#crawler-vs-user-experience)
- [The fix](#the-fix)
- [Framework-specific solutions](#framework-specific-solutions)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** What is cumulative layout shift (CLS)? · Unlighthouse
- **Source:** https://unlighthouse.dev/glossary/cls
- **Description:** CLS measures visual stability. Learn what it is, thresholds, and how to prevent layout shifts.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Glossary**

# **What is cumulative layout shift (CLS)?**

[Copy for LLMs](https://unlighthouse.dev/glossary/cls.md)

Loading demo...

Cumulative Layout Shift (CLS) measures visual stability - how much content unexpectedly moves during loading. It's one of Google's three [**~~Core Web Vitals~~**](https://unlighthouse.dev/glossary) and affects both UX and search rankings.

## Thresholds

| **Score** | **Rating** |
| --- | --- |
| ≤ 0.1 | Good |
| 0.1 - 0.25 | Needs Improvement |
| > 0.25 | Poor |

Aim for a score of 0.1 or less at the 75th percentile of page loads to pass the [**~~Google threshold~~**](https://web.dev/articles/cls).

## How Lighthouse calculates CLS

CLS quantifies unexpected shifts by multiplying impact fraction (viewport affected) by distance fraction (how far elements moved). User-initiated shifts within 500ms of interaction don't count.

## Why it matters

Layout shifts cause accidental clicks and lost reading position. [**~~79% of mobile sites pass CLS~~**](https://almanac.httparchive.org/en/2024/performance) - it's the best-performing Core Web Vital. [**~~Redbus reduced CLS to 0 and saw 80-100% higher conversions~~**](https://web.dev/case-studies/vitals-business-impact).

## Common issues

- Images without width/height dimensions
- Ads and embeds without reserved space
- Web fonts causing text reflow
- Dynamically injected content

## Measure CLS

- [**~~Core Web Vitals Checker~~**](https://unlighthouse.dev/tools/cwv-checker) - test any page
- Chrome DevTools Performance panel
- Lighthouse audit
- [**~~PageSpeed Insights~~**](https://pagespeed.web.dev/) (field data)
- Web Vitals Chrome extension

→ [**~~Complete CLS guide~~**](https://unlighthouse.dev/learn-lighthouse/cls)

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/cls.md)

[Markdown For LLMs](https://unlighthouse.dev/glossary/cls.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/cls.md) on GitHub or provide anonymous feedback below.

### **Related **

[**CLS Guide**](https://unlighthouse.dev/learn-lighthouse/cls) [**Core Web Vitals Checker**](https://unlighthouse.dev/tools/cwv-checker) [**Largest Contentful Paint (LCP)**](https://unlighthouse.dev/glossary/lcp) [**Interaction to Next Paint (INP)**](https://unlighthouse.dev/glossary/inp)

[**FCP** FCP measures when the first content renders. Learn what it is, thresholds, and how to improve it.](https://unlighthouse.dev/glossary/fcp) 

**On this page **

- [Thresholds](#thresholds)
- [How Lighthouse calculates CLS](#how-lighthouse-calculates-cls)
- [Why it matters](#why-it-matters)
- [Common issues](#common-issues)
- [Measure CLS](#measure-cls)

---

- **Page:** Fix Event Handler Delays for Better INP · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/inp/event-handler-delays
- **Description:** Slow event handlers directly hurt INP. Optimize click, input, and keypress handlers for instant feedback.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Event Handler Delays for Better INP**

Slow event handlers directly hurt INP. Optimize click, input, and keypress handlers for instant feedback.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)6 min read Published **Jan 18, 2025**

Event handlers run synchronously on the main thread. When a user clicks and your handler does 200ms of work before updating the UI, that's 200ms of perceived lag - even if the operation completes successfully.

## What's the problem?

INP measures from input to next paint: `**input delay + processing duration + presentation delay**`. Event handler code runs during processing duration. Heavy handlers directly increase INP.

The timeline for a slow interaction:

1. User clicks submit button
2. Handler validates 15 form fields (40ms)
3. Handler prepares API payload (20ms)
4. Handler starts async request
5. Handler tracks analytics event (30ms)
6. Handler finally updates button text
7. Browser paints - INP measured here (90ms+ processing)

The user waited 90ms staring at an unchanged button before seeing "Submitting..." feedback.

Common causes of handler delays:

- **Synchronous validation**: Form validation running before any UI update
- **Data transformation**: Serializing or processing data in the handler
- **Analytics calls**: Tracking events blocking UI updates
- **State cascades**: Multiple state updates triggering sequential re-renders
- **Synchronous storage**: Reading/writing localStorage or sessionStorage

[**~~Chrome's analysis of real-world INP~~**](https://web.dev/articles/optimize-inp#identify_and_reduce_input_delay) shows processing duration accounts for 40-50% of total INP on many sites.

### The "not my code" problem: input delay

Sometimes, your event handler is innocent. You might optimize your click handler to 5ms, but the INP score is still 300ms. Why?

**Input Delay.**

If a user clicks *while* the main thread is already busy doing something else (e.g., parsing a third-party script, hydrating a footer), the browser can't even *start* your event handler until that task finishes.

- **Scenario:** Main thread is blocked for 200ms by `**ad-script.js**`.
- **User Action:** Clicks button at 100ms mark.
- **Result:** Browser waits 100ms (remaining blocking time) → Input Delay = 100ms.
- **Your Code:** Runs for 5ms.
- **Total INP:** 105ms + Presentation Delay.

If your "Processing Duration" is low but INP is high, look for *other* tasks running immediately before the interaction.

## How to identify the issue

Use the web-vitals library to measure processing duration:

```js
import { onINP } from 'web-vitals/attribution'

onINP((metric) => {
  const { processingDuration, interactionTarget } = metric.attribution

  if (processingDuration > 100) {
    console.warn('Slow handler:', interactionTarget, `${processingDuration}ms`)
  }
})
```

In Chrome DevTools, record a Performance trace during the interaction. Find the click/keydown event in the main thread, expand it, and see exactly which functions consumed time before the paint.

## The fix

### Show immediate visual feedback

Update the UI first, then do everything else. The browser paints as soon as JavaScript yields.

```js
// Before: user waits 150ms for visual feedback
submitButton.onclick = async () => {
  const isValid = validateAllFields() // 50ms
  if (!isValid)
    return showErrors()

  const payload = preparePayload() // 30ms
  trackEvent('submit_clicked') // 20ms

  submitButton.textContent = 'Submitting...' // Finally visible
  await sendToServer(payload)
}

// After: feedback in <10ms, work continues after
submitButton.onclick = async () => {
  submitButton.disabled = true
  submitButton.textContent = 'Submitting...'

  // Yield to browser, then continue
  requestAnimationFrame(() => {
    setTimeout(async () => {
      const isValid = validateAllFields()
      if (!isValid) {
        submitButton.disabled = false
        submitButton.textContent = 'Submit'
        showErrors()
        return
      }

      const payload = preparePayload()
      trackEvent('submit_clicked')
      await sendToServer(payload)
    }, 0)
  })
}
```

The `**requestAnimationFrame**` + `**setTimeout**` pattern makes sure the browser paints before heavy work continues.

### Use `**scheduler.yield()**` to break up work

The Scheduler API (Chrome 115+) provides cleaner yielding:

```js
async function handleClick() {
  // Immediate feedback
  button.classList.add('active')

  // Yield to let browser paint
  await scheduler.yield()

  // Heavy work after paint
  const result = expensiveComputation()
  updateResults(result)
}
```

For browsers without scheduler support:

```js
function yieldToMain() {
  return new Promise(resolve =>
    setTimeout(resolve, 0)
  )
}

async function handleClick() {
  button.classList.add('active')
  await yieldToMain()
  // Continue work
}
```

### Debounce high-frequency events

Input, scroll, and mousemove events fire rapidly. Debouncing reduces handler execution:

```js
function debounce(fn, delay) {
  let timeout
  return (...args) => {
    clearTimeout(timeout)
    timeout = setTimeout(fn, delay, ...args)
  }
}

const handleSearch = debounce((query) => {
  const results = searchIndex(query) // Expensive
  renderResults(results)
}, 150)

searchInput.oninput = (e) => {
  // Always show immediate feedback
  showSearchingIndicator()

  // Debounced expensive work
  handleSearch(e.target.value)
}
```

For scroll handlers, use `**throttle**` instead - it executes periodically rather than only after quiet periods.

### Move heavy work to web workers

Computation-heavy operations belong in a worker:

```js
// worker.js
globalThis.onmessage = ({ data }) => {
  const result = heavyComputation(data)
  globalThis.postMessage(result)
}

// main.js
const worker = new Worker('worker.js')

button.onclick = () => {
  button.textContent = 'Processing...'

  worker.postMessage(inputData)
  worker.onmessage = ({ data }) => {
    displayResults(data)
    button.textContent = 'Done'
  }
}
```

Workers run on a separate thread - computation doesn't block interactions at all.

### Avoid synchronous storage in handlers

`**localStorage**` and `**sessionStorage**` are synchronous and can take 10-50ms on slow devices:

```js
// Before: blocks thread during write
button.onclick = () => {
  localStorage.setItem('preferences', JSON.stringify(bigObject))
  showConfirmation()
}

// After: write after paint
button.onclick = () => {
  showConfirmation()

  requestIdleCallback(() => {
    localStorage.setItem('preferences', JSON.stringify(bigObject))
  })
}
```

For larger data, use IndexedDB with a library like `**idb**` - it's asynchronous.

### Split validation phases

Run fast validation immediately, defer expensive validation:

```js
function quickValidate(form) {
  // Fast: required fields, basic format
  return form.email.value && form.email.value.includes('@')
}

async function fullValidate(form) {
  // Slow: API calls, complex rules
  const emailAvailable = await checkEmailAvailability(form.email.value)
  const passwordStrong = assessPasswordStrength(form.password.value)
  return emailAvailable && passwordStrong
}

form.onsubmit = async (e) => {
  e.preventDefault()

  // Fast check provides immediate feedback
  if (!quickValidate(form)) {
    showError('Please fill required fields')
    return
  }

  // Show loading, then do full validation
  showLoading()

  await scheduler.yield()

  if (!await fullValidate(form)) {
    hideLoading()
    showDetailedErrors()
    return
  }

  await submitForm(form)
}
```

## Framework-specific solutions

**Next.js / React**

Use `**useTransition**` to mark state updates as non-urgent:

```jsx
import { useState, useTransition } from 'react'

function SearchResults() {
  const [query, setQuery] = useState('')
  const [results, setResults] = useState([])
  const [isPending, startTransition] = useTransition()

  function handleChange(e) {
    // Urgent: update input immediately
    setQuery(e.target.value)

    // Non-urgent: can be interrupted
    startTransition(() => {
      setResults(search(e.target.value))
    })
  }

  return (
    <>
      <input value={query} onChange={handleChange} />
      {isPending ? <Spinner /> : <Results data={results} />}
    </>
  )
}
```

[**~~React~~**](https://react.dev) 18's concurrent features let urgent updates interrupt non-urgent ones.

**Nuxt / Vue**

Use `**nextTick**` to defer work until after Vue's reactivity updates:

```html
<script setup>
const isLoading = ref(false)
const results = ref([])

async function handleSearch(query) {
  // Immediate feedback
  isLoading.value = true

  // Wait for Vue to update DOM
  await nextTick()

  // Heavy work after paint
  results.value = await search(query)
  isLoading.value = false
}
</script>
```

For expensive computed properties, consider `**computedAsync**` from [**~~VueUse~~**](https://vueuse.org) or moving logic to a worker.

## Verify the fix

After changes:

1. Monitor processing duration with web-vitals - target under 100ms
2. Record Performance traces - verify visual feedback appears in first frame after input
3. Compare INP in field data before and after deployment

**TBT**Total Blocking Time

**30% weight **

Good ≤200msPoor >600ms

Moving 150ms of handler work after visual feedback reduces perceived INP by 150ms.

## Common mistakes

**Awaiting before visual feedback**: `**await**` doesn't yield to the browser. Visual updates before any await still wait for the entire async function setup.

```js
// Still blocks until await is reached
button.onclick = async () => {
  heavySetup() // 100ms
  await asyncWork() // Browser can't paint until here
}
```

**Putting heavy work in requestAnimationFrame**: rAF callbacks run before paint. Put expensive work in setTimeout inside rAF.

**Forgetting mobile devices**: A 50ms handler on desktop becomes 150ms+ on a mid-range phone. Always test throttled.

**Over-debouncing**: Debounce delays of 300ms+ make interfaces feel sluggish. Keep delays under 200ms for search, 100ms for autocomplete.

## Related issues

Event handler delays often compound with other INP causes:

- [**~~Long-Running JavaScript~~**](https://unlighthouse.dev/learn-lighthouse/inp/long-running-javascript) - Handlers calling expensive functions
- [**~~Heavy DOM Operations~~**](https://unlighthouse.dev/learn-lighthouse/inp/heavy-dom-operations) - Handler-triggered renders causing presentation delay

## Test your entire site

Different interactions have different handler complexity. A simple navigation click behaves differently than a complex form submission. [**~~Unlighthouse~~**](https://unlighthouse.dev/) surfaces TBT (INP proxy) issues across your entire site, helping identify which pages have the slowest interactions.

### **Related **

[**INP Overview**](https://unlighthouse.dev/learn-lighthouse/inp) [**All INP Issues**](https://unlighthouse.dev/learn-lighthouse/inp#common-inp-issues) [**INP Definition**](https://unlighthouse.dev/glossary/inp) [**INP Analyzer Tool**](https://unlighthouse.dev/tools/inp-analyzer)

[**Third-Party Scripts** Third-party scripts compete for main thread time. Learn to defer, facade, and limit their impact on interaction responsiveness.](https://unlighthouse.dev/learn-lighthouse/inp/third-party-scripts) [**Hydration Issues** Framework hydration blocks interactivity. Delay and partial hydration strategies to make SSR sites responsive faster.](https://unlighthouse.dev/learn-lighthouse/inp/hydration-issues)

**On this page **

- [What's the problem?](#whats-the-problem)
- [How to identify the issue](#how-to-identify-the-issue)
- [The fix](#the-fix)
- [Framework-specific solutions](#framework-specific-solutions)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** What is largest contentful paint (LCP)? · Unlighthouse
- **Source:** https://unlighthouse.dev/glossary/lcp
- **Description:** LCP measures loading performance. Learn what it is, thresholds, and how to improve your score.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Glossary**

# **What is largest contentful paint (LCP)?**

[Copy for LLMs](https://unlighthouse.dev/glossary/lcp.md)

Loading demo...

Largest Contentful Paint (LCP) measures how long it takes for the largest visible element to render. It's one of Google's three [**~~Core Web Vitals~~**](https://unlighthouse.dev/glossary) and directly impacts search rankings.

## Thresholds

| **Score** | **Rating** |
| --- | --- |
| ≤ 2.5s | Good |
| 2.5s - 4.0s | Needs Improvement |
| > 4.0s | Poor |

Aim for a score of 2.5 seconds or less at the 75th percentile of page loads to pass the [**~~Google threshold~~**](https://web.dev/articles/lcp).

## What triggers LCP

LCP tracks when the largest image, video poster, or text block renders. [**~~73% of mobile pages have an image as their LCP element~~**](https://almanac.httparchive.org/en/2024/performance).

## Why it matters

LCP is the [**~~hardest Core Web Vital to pass~~**](https://almanac.httparchive.org/en/2024/performance) - only 59% of mobile pages achieve good scores. [**~~Vodafone improved LCP by 31% and saw 8% more sales~~**](https://web.dev/case-studies/vitals-business-impact).

## Common issues

- Slow server response ([**~~TTFB~~**](https://unlighthouse.dev/glossary/ttfb))
- Render-blocking CSS/JavaScript
- Large unoptimized images
- Client-side rendering delays

## Measure LCP

- [**~~Core Web Vitals Checker~~**](https://unlighthouse.dev/tools/cwv-checker) - test any page
- Chrome DevTools Performance panel
- Lighthouse audit
- [**~~PageSpeed Insights~~**](https://pagespeed.web.dev/) (field data)
- Search Console Core Web Vitals report

→ [**~~Complete LCP guide~~**](https://unlighthouse.dev/learn-lighthouse/lcp)

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/lcp.md)

[Markdown For LLMs](https://unlighthouse.dev/glossary/lcp.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/lcp.md) on GitHub or provide anonymous feedback below.

### **Related **

[**LCP Guide**](https://unlighthouse.dev/learn-lighthouse/lcp) [**Core Web Vitals Checker**](https://unlighthouse.dev/tools/cwv-checker) [**Cumulative Layout Shift (CLS)**](https://unlighthouse.dev/glossary/cls) [**Interaction to Next Paint (INP)**](https://unlighthouse.dev/glossary/inp)

[**INP** INP measures responsiveness. Learn what it is, thresholds, and how to improve interaction speed.](https://unlighthouse.dev/glossary/inp) [**Speed Index** Speed Index (SI) measures how fast visible content fills the viewport. Good: ≤3.4s mobile, ≤1.3s desktop. 10% of Lighthouse performance score. Thresholds, tools, fixes.](https://unlighthouse.dev/glossary/speed-index)

**On this page **

- [Thresholds](#thresholds)
- [What triggers LCP](#what-triggers-lcp)
- [Why it matters](#why-it-matters)
- [Common issues](#common-issues)
- [Measure LCP](#measure-lcp)

---

- **Page:** Fix Third-Party Script Impact on INP · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/inp/third-party-scripts
- **Description:** Third-party scripts compete for main thread time. Learn to defer, facade, and limit their impact on interaction responsiveness.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Third-Party Script Impact on INP**

Third-party scripts compete for main thread time. Learn to defer, facade, and limit their impact on interaction responsiveness.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)7 min read Published **Jan 18, 2025**

Third-party scripts consume an average of 30% of main thread time on commercial websites. That's not your code causing INP problems - it's analytics, ads, chat widgets, and embedded content fighting for the same thread your users need for interactions.

## What's the problem?

Every third-party script runs on the main thread. When a user clicks a button, but the browser is busy executing Google Tag Manager callbacks or ad rendering code, that click waits. The [**~~HTTP Archive reports~~**](https://almanac.httparchive.org/en/2024/third-parties) median sites load 21 third-party resources totaling 450KB.

Third-party impact on INP happens three ways:

**Input delay**: User clicks while third-party code is executing. The browser queues the interaction until the main thread is free.

**Processing interference**: Your event handler runs, but third-party code also runs during the same task, extending total blocking time.

**Periodic execution**: Many scripts don't just run on load. Analytics libraries send beacons, ad scripts refresh, and chat widgets poll for new messages. These ongoing tasks compete with interactions throughout the session.

### Hidden cost: structured data & meta tags

We often think of SEO tags as "free," but injecting massive JSON-LD blobs or complex meta tags via JavaScript can block the main thread.

If you use a tag manager or a CMS plugin to inject [**~~Schema.org~~**](http://Schema.org) data:

1. The browser parses the script (Main Thread)
2. The browser serializes the JSON (Main Thread)
3. The browser inserts it into the DOM (Main Thread)

For large product catalogs, a 50KB JSON-LD object can cause a 100ms+ blocking task to "help SEO" - ironically hurting your Core Web Vitals ranking factor. Use the [**~~JSON Size Analyzer~~**](https://unlighthouse.dev/tools/json-size) to measure [**~~Schema.org~~**](http://Schema.org) payloads before injection.

The Lighthouse audit "Reduce the impact of third-party code" identifies scripts blocking the main thread. It measures transfer size and main thread execution time per third-party origin.

## How to identify the issue

Open Chrome DevTools Performance panel, record an interaction, and look at the main thread. Third-party code appears as tasks from external domains. Sort the call tree by "Self Time" to find the worst offenders.

For ongoing monitoring, measure third-party main thread time:

```js
const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (entry.duration > 50) {
      const script = entry.attribution?.[0]?.containerSrc
      if (script && !script.includes(location.hostname)) {
        console.log('Third-party long task:', script, entry.duration)
      }
    }
  }
})
observer.observe({ entryTypes: ['longtask'] })
```

## The fix

### Load non-essential scripts on interaction

The facade pattern shows a lightweight placeholder, then loads the full script when users interact. YouTube embeds are the classic example - a thumbnail and play button cost a few KB, while the full player loads 1MB+.

```js
class YouTubeFacade extends HTMLElement {
  connectedCallback() {
    const videoId = this.getAttribute('video-id')
    this.innerHTML = `
      <img src="https://i.ytimg.com/vi/${videoId}/hqdefault.jpg"
           alt="Video thumbnail" loading="lazy">
      <button aria-label="Play video">Play</button>
    `
    this.querySelector('button').onclick = () => this.loadPlayer()
  }

  loadPlayer() {
    const videoId = this.getAttribute('video-id')
    this.innerHTML = `
      <iframe src="https://www.youtube.com/embed/${videoId}?autoplay=1"
              allow="autoplay; encrypted-media" allowfullscreen></iframe>
    `
  }
}
customElements.define('youtube-facade', YouTubeFacade)
```

Apply this pattern to chat widgets, social embeds, maps, and any interactive third-party content below the fold.

### Use `**async**` or `**defer**` appropriately

Both attributes prevent render blocking, but they execute differently:

- `**async**` - Downloads in parallel, executes immediately when ready. Order not guaranteed.
- `**defer**` - Downloads in parallel, executes after HTML parsing, in document order.

```html
<!-- Analytics: doesn't need DOM, order doesn't matter -->
<script async src="https://analytics.example.com/track.js"></script>

<!-- Widget that needs DOM: defer ensures HTML is ready -->
<script defer src="https://widget.example.com/embed.js"></script>
```

For scripts that must execute in order (like GTM loading other scripts), use `**defer**`. For independent analytics, use `**async**`.

### Self-host critical third-party code

External scripts require DNS lookup, TCP connection, and TLS handshake - adding 100-500ms before download starts. Self-hosting eliminates this latency.

```bash
curl -o public/gtm.js https://www.googletagmanager.com/gtm.js?id=GTM-XXXX
```

Self-hosted scripts also benefit from your CDN, HTTP/2 multiplexing, and caching strategy. Update periodically to get vendor fixes.

Be aware: some scripts check their origin or rely on same-origin cookies. Test thoroughly before self-hosting.

### Use web workers for analytics

Web Workers run JavaScript off the main thread. Tools like [**~~Partytown~~**](https://partytown.builder.io/) proxy third-party scripts into a worker:

```html
<script>
  partytown = {
    forward: ['dataLayer.push', 'gtag']
  }
</script>
<script src="/~partytown/partytown.js"></script>
<script type="text/partytown" src="https://www.googletagmanager.com/gtag/js"></script>
```

The worker communicates with the main thread through postMessage, but third-party execution no longer blocks interactions. [**~~Early adopters report 50-70% TBT reduction~~**](https://partytown.builder.io/).

Caveats: not all scripts work in workers (DOM access requires proxying), and debugging becomes harder. Test critical user flows.

### Set resource hints

Preconnect warms up connections to third-party origins you know you'll need:

```html
<link rel="preconnect" href="https://www.google-analytics.com">
<link rel="dns-prefetch" href="https://static.ads.example.com">
```

Use `**preconnect**` for critical third parties (2-3 max - more wastes bandwidth). Use `**dns-prefetch**` for less critical origins where you want DNS resolved early but don't need the full connection.

## Framework-specific solutions

**Next.js**

The `**next/script**` component provides loading strategies:

```jsx
import Script from 'next/script'

export function GoogleTagManager() {
  return <Script src="https://www.googletagmanager.com/gtag/js" strategy="worker" />
}

export function ChatWidget() {
  return <Script src="https://widget.example.com/chat.js" strategy="lazyOnload" />
}

export function Analytics() {
  return <Script src="https://analytics.example.com/track.js" strategy="afterInteractive" />
}
```

**Nuxt**

Use `**useScript**` composable with triggers:

```ts
// Load when browser is idle
useScript('https://analytics.example.com/track.js', {
  trigger: 'idle'
})

// Load when element is visible
const chatContainer = ref(null)
useScript('https://chat.example.com/widget.js', {
  trigger: useScriptTriggerElement({ el: chatContainer })
})

// Load on manual trigger
const { load } = useScript('https://maps.example.com/api.js', {
  trigger: 'manual'
})
// Later: load()
```

For worker-based loading, use `**@nuxtjs/partytown**` module.

## Verify the fix

After changes, measure the impact:

1. Run Lighthouse - check "Third-party code blocked the main thread" diagnostic
2. Record a Performance trace during interaction - third-party tasks should be shorter or absent
3. Monitor RUM data - compare INP before and after deployment

**TBT**Total Blocking Time

**30% weight **

Good ≤200msPoor >600ms

Expect TBT reduction of 100-500ms when moving analytics to workers or deferring heavy embeds.

## Common mistakes

**Loading everything on page load**: Even deferred scripts execute eventually. Use facades and lazy loading for content users might never interact with.

**Preconnecting to too many origins**: Each preconnect consumes bandwidth and CPU. Limit to 2-3 critical origins.

**Breaking tracking**: Deferred analytics may miss early page events. Make sure critical tracking fires before users can navigate away.

**Testing only on fast connections**: Third-party impact is far worse on mobile. Test on throttled connections.

## Third-party triage

Not all third parties are equal. Prioritize by business impact:

| **Category** | **Priority** | **Strategy** |
| --- | --- | --- |
| Consent management | Critical | Load early, minimize size |
| Analytics | High | Defer or worker |
| A/B testing | High | Load early, minimize blocking |
| Ads | Revenue | Lazy-load when in view |
| Chat widgets | Medium | Facade, load on interaction |
| Social embeds | Low | Facade with placeholder |
| Video embeds | Low | Facade with thumbnail |

Consider removing scripts that don't justify their performance cost. Every analytics tool added has a cumulative impact.

## Related issues

Third-party scripts often combine with other INP causes:

- [**~~Long-Running JavaScript~~**](https://unlighthouse.dev/learn-lighthouse/inp/long-running-javascript) - Your code + third-party code compete
- [**~~Hydration Issues~~**](https://unlighthouse.dev/learn-lighthouse/inp/hydration-issues) - Scripts loading during hydration extend blocking time

## Test your entire site

Third-party impact varies by page. A minimal homepage may perform well while product pages with multiple embeds suffer. [**~~Unlighthouse~~**](https://unlighthouse.dev/) scans every page and surfaces TBT problems from third-party scripts across your entire site.

### **Related **

[**INP Overview**](https://unlighthouse.dev/learn-lighthouse/inp) [**All INP Issues**](https://unlighthouse.dev/learn-lighthouse/inp#common-inp-issues) [**INP Definition**](https://unlighthouse.dev/glossary/inp) [**INP Analyzer Tool**](https://unlighthouse.dev/tools/inp-analyzer) [**Page Size Checker**](https://unlighthouse.dev/tools/page-size) [**HAR File Viewer**](https://unlighthouse.dev/tools/har-viewer)

[**DOM Size** Large DOMs slow every interaction. Reduce DOM size with virtualization, lazy rendering, and smarter component architecture.](https://unlighthouse.dev/learn-lighthouse/inp/dom-size) [**Event Handler Delays** Slow event handlers directly hurt INP. Optimize click, input, and keypress handlers for instant feedback.](https://unlighthouse.dev/learn-lighthouse/inp/event-handler-delays)

**On this page **

- [What's the problem?](#whats-the-problem)
- [How to identify the issue](#how-to-identify-the-issue)
- [The fix](#the-fix)
- [Framework-specific solutions](#framework-specific-solutions)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Third-party triage](#third-party-triage)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix Excessive DOM Size for Better INP · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/inp/dom-size
- **Description:** Large DOMs slow every interaction. Reduce DOM size with virtualization, lazy rendering, and smarter component architecture.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Excessive DOM Size for Better INP**

Large DOMs slow every interaction. Reduce DOM size with virtualization, lazy rendering, and smarter component architecture.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)6 min read Published **Jan 18, 2025**

Every DOM node adds overhead to every interaction. Style recalculation doesn't check "what changed" - it rechecks everything. A 5,000 element DOM doesn't just load slower; every click, every keystroke, every hover state change takes longer to process.

**TBT**Total Blocking Time

**30% weight **

Good ≤200msPoor >600ms

## What's the problem?

The DOM Size audit measures three things:

| **Statistic** | **Warning** | **Fail** |
| --- | --- | --- |
| Total Elements | >800 | >1,400 |
| Maximum Depth | >32 levels | >32 levels |
| Maximum Children | >60 per parent | >60 per parent |

These thresholds exist because DOM size directly impacts:

- **Style recalculation** - More elements means more selector matching
- **Layout** - Larger layout trees take longer to compute
- **Memory** - Each node consumes memory
- **Garbage collection** - More objects to track and clean up

The relationship isn't linear. A 2,000 element page doesn't take 2x as long as a 1,000 element page - it can take 4x or more due to cascading effects.

## Why large doms hurt INP

When you change a single element's class, the browser doesn't just restyle that element. It recalculates styles for potentially thousands of elements to check if any selectors now match differently.

Chrome's style recalculation scales roughly as O(n \* m) where n is DOM elements and m is CSS rules. Doubling your DOM size can quadruple style recalculation time.

Real measurement from a production e-commerce site:

| **DOM Size** | **Style Recalc Time** | **INP (p75)** |
| --- | --- | --- |
| 800 elements | 12ms | 85ms |
| 2,400 elements | 48ms | 180ms |
| 4,800 elements | 156ms | 420ms |

Every interaction on that 4,800 element page felt sluggish.

### Hidden cost: garbage collection & memory

We often talk about rendering, but memory is the silent INP killer.

DOM nodes are expensive objects. A large DOM increases the memory footprint of your page. When the browser runs out of available memory, it triggers **Garbage Collection (GC)**.

- **The GC Pause:** Garbage collection pauses the main thread. If a GC event triggers while a user is interacting, the browser adds that pause directly to the Input Delay.
- **The Frequency:** The more DOM nodes you create and destroy (e.g., in Single Page Apps navigating between routes), the more frequently the GC has to run.

A "stuttery" experience often correlates with high GC activity caused by excessive DOM churn.

## How to identify the issue

### Lighthouse DOM size audit

Run Lighthouse. The DOM Size audit shows:

- Total element count
- Deepest element (with path)
- Element with most children

### DevTools elements panel

Open DevTools Console and run:

```js
document.querySelectorAll('*').length
```

For a breakdown by tag:

```js
const counts = {}
document.querySelectorAll('*').forEach((el) => {
  counts[el.tagName] = (counts[el.tagName] || 0) + 1
})
console.table(Object.entries(counts).sort((a, b) => b[1] - a[1]))
```

This reveals what's bloating your DOM. Often it's SVG icons, list items, or nested component wrappers.

### Find deep nesting

```js
function getDepth(el, depth = 0) {
  return el.parentElement ? getDepth(el.parentElement, depth + 1) : depth
}
const deepest = Array.from(document.querySelectorAll('*'), el => ({ el, depth: getDepth(el) }))
  .sort((a, b) => b.depth - a.depth)[0]
console.log('Deepest element:', deepest.depth, deepest.el)
```

Depth over 32 indicates over-nested component structures.

## The fix

### 1. virtual scrolling for lists and tables

Stop rendering what users can't see:

```jsx
// @tanstack/react-virtual
import { useVirtualizer } from '@tanstack/react-virtual'

function ProductList({ products }) {
  const parentRef = useRef(null)

  const rowVirtualizer = useVirtualizer({
    count: products.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 120,
    overscan: 5,
  })

  return (
    <div ref={parentRef} className="h-[600px] overflow-auto">
      <div style={{ height: rowVirtualizer.getTotalSize() }}>
        {rowVirtualizer.getVirtualItems().map(virtualRow => (
          <ProductCard
            key={virtualRow.key}
            product={products[virtualRow.index]}
            style={{
              position: 'absolute',
              top: virtualRow.start,
              height: virtualRow.size,
            }}
          />
        ))}
      </div>
    </div>
  )
}
```

A 10,000 item list becomes \~20 DOM nodes. INP drops dramatically.

### 2. lazy render below-fold content

Don't render what's not visible on load:

```jsx
function LazySection({ children }) {
  const [isVisible, setIsVisible] = useState(false)
  const ref = useRef(null)

  useEffect(() => {
    const observer = new IntersectionObserver(
      ([entry]) => {
        if (entry.isIntersecting) {
          setIsVisible(true)
          observer.disconnect()
        }
      },
      { rootMargin: '100px' }
    )

    if (ref.current)
      observer.observe(ref.current)
    return () => observer.disconnect()
  }, [])

  return (
    <div ref={ref}>
      {isVisible ? children : <div className="h-[400px]" />}
    </div>
  )
}
```

Use it for footer sections, related products, comments - anything below the fold.

### 3. remove hidden elements, don't hide them

`**display: none**` and `**visibility: hidden**` still keep elements in the DOM:

```jsx
// Bad: element stays in DOM
<Modal style={{ display: isOpen ? 'block' : 'none' }}>
  <ComplexContent />
</Modal>

// Good: element removed from DOM
{ isOpen && (
  <Modal>
    <ComplexContent />
  </Modal>
) }
```

This matters for modals, dropdowns, tabs, and accordions. A page with 10 hidden modals has all that DOM weight.

### 4. flatten deeply nested structures

Each wrapper div adds depth:

```jsx
// Over-nested (adds 4 unnecessary levels)
export function DeepCard() {
  return (
    <CardWrapper>
      <CardInner>
        <CardContent>
          <CardBody>
            <p>Content</p>
          </CardBody>
        </CardContent>
      </CardInner>
    </CardWrapper>
  )
}

// Flattened
export function FlatCard() {
  return (
    <article className="card">
      <p>Content</p>
    </article>
  )
}
```

Review your component library. Wrapper components stack up quickly.

### 5. use CSS instead of DOM for visual effects

Don't add elements for visual styling:

```jsx
// Bad: 4 extra DOM nodes
export function ComplexCard() {
  return (
    <div className="card">
      <div className="card-shadow" />
      <div className="card-border" />
      <div className="card-glow" />
      <div className="card-content">Content</div>
    </div>
  )
}

// Good: CSS pseudo-elements (0 extra DOM nodes)
export function SimpleCard() {
  return <div className="card">Content</div>
}
```

```css
.card {
  position: relative;
}
.card::before {
  content: '';
  position: absolute;
  inset: 0;
  box-shadow: 0 4px 12px rgba(0,0,0,0.1);
  border-radius: inherit;
}
```

Pseudo-elements (`**::before**`, `**::after**`) are "free" - they don't add to DOM element count.

### 6. inline SVG icons only once

Every inline SVG icon adds 10-50 elements:

```html
<!-- Bad: each icon duplicates the SVG -->
<button><svg>...</svg> Save</button>
<button><svg>...</svg> Delete</button>

<!-- Better: use <use> to reference once -->
<svg style="display: none">
  <symbol id="icon-save"><path d="..."/></symbol>
</svg>
<button><svg><use href="#icon-save"/></svg> Save</button>
```

Or use an icon font (1 element per icon instead of 10+).

## Framework-specific solutions

**React**

Use `**react-window**` or `**@tanstack/react-virtual**` for lists:

```jsx
import { FixedSizeList } from 'react-window'

export function VirtualList({ items }) {
  return (
    <FixedSizeList
      height={400}
      itemCount={items.length}
      itemSize={50}
    >
      {({ index, style }) => (
        <div style={style}>{items[index].name}</div>
      )}
    </FixedSizeList>
  )
}
```

For conditional rendering, prefer `**&&**` over CSS hiding:

```jsx
export function Conditional({ isVisible }) {
  return (
    <>
      { isVisible && <ExpensiveComponent /> }
    </>
  )
}
```

**Vue / Nuxt**

Use `**vue-virtual-scroller**` for lists:

```html
<template>
  <RecycleScroller
    v-slot="{ item }"
    :items="items"
    :item-size="50"
    class="h-[400px]"
  >
    <div>{{ item.name }}</div>
  </RecycleScroller>
</template>
```

Use `**v-if**` instead of `**v-show**` for heavy components:

```html
<template>
  <!-- v-show: element stays in DOM -->
  <Modal v-show="isOpen" />

  <!-- v-if: element removed from DOM -->
  <Modal v-if="isOpen" />
</template>
```

**Angular**

Use `**@angular/cdk/scrolling**`:

```text
<cdk-virtual-scroll-viewport itemSize="50" class="h-[400px]">
  <div *cdkVirtualFor="let item of items">
    {{ item.name }}
  </div>
</cdk-virtual-scroll-viewport>
```

Use `***ngIf**` instead of `**[hidden]**` for heavy components.

## Verify the fix

After implementing changes:

1. Run Lighthouse DOM Size audit - target under 800 elements
2. Check maximum depth stays under 32
3. No parent should have more than 60 children
4. Monitor INP improvements with web-vitals

```js
// Quick check in console
console.log('DOM elements:', document.querySelectorAll('*').length)
```

**Target metrics:**

- Total elements: under 800 (good), under 1,400 (acceptable)
- Max depth: under 20 levels (good), under 32 (acceptable)
- Max children: under 30 (good), under 60 (acceptable)

## Common mistakes

**Using display:none for tab content.** All tabs stay in DOM. Use conditional rendering to remove inactive tabs.

**Rendering full lists then filtering.** Render 100 items, filter to 10 visible. Better: filter first, render second.

**SVG icon libraries with inline SVGs.** Each icon adds 10-50 elements. Use sprites or icon fonts.

**Component wrapper divs.** `**<Wrapper><Inner><Content>**` adds 2 unnecessary elements. Flatten when possible.

**Hidden modals.** A modal with 50 elements adds 50 to your DOM even when closed. Mount on open, unmount on close.

## Related issues

DOM size problems often combine with:

- [**~~Heavy DOM Operations~~**](https://unlighthouse.dev/learn-lighthouse/inp/heavy-dom-operations) - More elements means more work per operation
- [**~~Long-Running JavaScript~~**](https://unlighthouse.dev/learn-lighthouse/inp/long-running-javascript) - Script evaluation adds to main thread time
- [**~~Hydration Issues~~**](https://unlighthouse.dev/learn-lighthouse/inp/hydration-issues) - Large DOMs take longer to hydrate

## Test your entire site

DOM size varies wildly by page. Your homepage might have 600 elements while your product listing has 3,000.

[**~~Unlighthouse~~**](https://unlighthouse.dev/) scans your entire site and surfaces pages exceeding DOM thresholds so you can prioritize fixes.

### **Related **

[**INP Overview**](https://unlighthouse.dev/learn-lighthouse/inp) [**All INP Issues**](https://unlighthouse.dev/learn-lighthouse/inp#common-inp-issues) [**INP Definition**](https://unlighthouse.dev/glossary/inp) [**INP Analyzer Tool**](https://unlighthouse.dev/tools/inp-analyzer)

[**Main Thread Work** Reduce main thread work from DOM manipulation, style recalculation, and layout thrashing. Keep interactions responsive.](https://unlighthouse.dev/learn-lighthouse/inp/heavy-dom-operations) [**Third-Party Scripts** Third-party scripts compete for main thread time. Learn to defer, facade, and limit their impact on interaction responsiveness.](https://unlighthouse.dev/learn-lighthouse/inp/third-party-scripts)

**On this page **

- [What's the problem?](#whats-the-problem)
- [Why large doms hurt INP](#why-large-doms-hurt-inp)
- [How to identify the issue](#how-to-identify-the-issue)
- [The fix](#the-fix)
- [Framework-specific solutions](#framework-specific-solutions)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix Hydration Issues for Better INP · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/inp/hydration-issues
- **Description:** Framework hydration blocks interactivity. Delay and partial hydration strategies to make SSR sites responsive faster.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Hydration Issues for Better INP**

Framework hydration blocks interactivity. Delay and partial hydration strategies to make SSR sites responsive faster.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)7 min read Published **Jan 18, 2025**

Hydration can block interactions for 500ms to 3 seconds on complex pages. Users see a fully rendered page, try to interact, and nothing happens - the JavaScript framework is busy "waking up" server-rendered HTML.

## What's the problem?

Server-side rendering delivers HTML fast, but that HTML is static. Buttons don't work, forms don't submit, and dropdowns don't open until hydration completes. Hydration is the process where a JavaScript framework:

1. Downloads the component JavaScript
2. Parses and executes that JavaScript
3. Walks the DOM tree matching components
4. Attaches event handlers to elements
5. Initializes reactive state

During steps 2-5, the main thread is blocked. Any user interaction during this time gets high input delay - the click event queues until hydration finishes.

The [**~~Google research~~**](https://web.dev/articles/why-speed-matters) found that bounce probability increases 90% as load time goes from 1s to 5s. Hydration is often why time-to-interactive exceeds first contentful paint by 2-4 seconds.

**Real-world impact:** A [**~~React~~**](https://react.dev) e-commerce site with 200 components takes 800ms to hydrate on a mobile device. Every early interaction during that 800ms window has 800ms+ INP.

### The "uncanny valley" of interactivity

Hydration creates a deceptive state: the "Uncanny Valley."

- **0s - 1.5s:** Page is white (Loading). Users wait.
- **1.5s - 3.5s:** Page *looks* complete (The Valley). Users try to click.
- **3.5s:** Page becomes interactive.

The danger is that users rely on visual cues. If they see a button, they click it. If the main thread is locked in a hydration loop, that click goes into a void, resulting in a "Broken" feeling and a poor INP score.

**Double Hydration:** A common bug where server-rendered HTML doesn't match the client-side initial render (e.g., mismatched timestamps or IDs). React is forced to discard the HTML and re-render the entire tree from scratch. This doubles the work and kills INP.

## How to identify the issue

Hydration issues manifest as early interactions with high input delay. Use web-vitals to detect this pattern:

```js
import { onINP } from 'web-vitals/attribution'

onINP((metric) => {
  const { inputDelay, interactionTime } = metric.attribution

  // Early interaction with high input delay suggests hydration blocking
  if (inputDelay > 200 && interactionTime < 10000) {
    console.warn('Possible hydration blocking:', {
      inputDelay,
      interactionTime,
      target: metric.attribution.interactionTarget
    })
  }
})
```

In Chrome DevTools:

1. Record a Performance trace starting before page load
2. Click a button immediately when the page appears rendered
3. Look for the click event - a long gap before your handler runs indicates hydration blocking
4. Find hydration tasks by searching for framework-specific functions: `**hydrate**`, `**hydrateRoot**`, `**$mount**`, `**$hydrate**`

Manual testing: load your page on a throttled connection, click buttons as soon as they appear. If clicks are ignored or severely delayed, hydration is the bottleneck.

## The fix

### Progressive hydration

Hydrate critical interactive elements first, defer the rest. Users interact with navigation and CTAs immediately; comments and footers can wait.

```js
// Hydrate immediately
hydrateRoot(document.getElementById('nav'), <Navigation />)
hydrateRoot(document.getElementById('hero-cta'), <HeroCTA />)

// Hydrate when idle
requestIdleCallback(() => {
  hydrateRoot(document.getElementById('comments'), <Comments />)
})

// Hydrate when visible
const observer = new IntersectionObserver((entries) => {
  entries.forEach((entry) => {
    if (entry.isIntersecting) {
      hydrateRoot(entry.target, <Footer />)
      observer.disconnect()
    }
  })
})
observer.observe(document.getElementById('footer'))
```

### Islands architecture

Only hydrate interactive parts of the page. Static content stays as plain HTML - no JavaScript attached, no hydration cost.

[**~~Astro~~**](https://astro.build) pioneered this pattern:

```astro
---
// Static by default - no JS
import Header from './Header.astro'
import ProductInfo from './ProductInfo.astro'

// Interactive island - hydrates independently
import AddToCart from './AddToCart.jsx'
---

<Header />  <!-- Static HTML, zero JS -->

<ProductInfo product={product} />  <!-- Static HTML, zero JS -->

<AddToCart client:visible product={product} />  <!-- Hydrates when scrolled into view -->
```

The result: a page with 50 components might only hydrate 3-4 interactive islands. Total hydration time drops from 800ms to 80ms.

### Defer below-fold hydration

Components not visible on initial load don't need immediate hydration:

```js
// Lazy hydration utility
function hydrateOnVisible(container, component) {
  if ('IntersectionObserver' in window) {
    const observer = new IntersectionObserver((entries) => {
      if (entries[0].isIntersecting) {
        hydrateRoot(container, component)
        observer.disconnect()
      }
    }, { rootMargin: '200px' }) // Start hydrating slightly before visible
    observer.observe(container)
  }
  else {
    // Fallback: hydrate after delay
    setTimeout(hydrateRoot, 2000, container, component)
  }
}
```

### Server components (React)

React Server Components don't hydrate at all - they render on the server and send HTML. Only `**'use client'**` components require hydration.

```jsx
// app/page.js - Server Component (no hydration)
export default function ProductPage({ product }) {
  return (
    <div>
      {/* These never hydrate - just HTML */}
      <ProductTitle title={product.title} />
      <ProductDescription description={product.description} />
      <ProductSpecs specs={product.specs} />

      {/* Only this hydrates */}
      <AddToCartButton productId={product.id} />
    </div>
  )
}

// components/AddToCartButton.js
'use client' // This component hydrates

export function AddToCartButton({ productId }) {
  const [adding, setAdding] = useState(false)
  // Interactive logic...
}
```

Server Components can reduce hydration - a page might go from hydrating 100 components to hydrating 5.

### Reduce component tree depth

Deep component trees take longer to hydrate. Each level adds reconciliation overhead.

```jsx
// Before: deeply nested (slow hydration)
export function NestedApp() {
  return (
    <App>
      <Layout>
        <PageWrapper>
          <ContentContainer>
            <Section>
              <ProductCard>
                <ProductInfo>
                  <ProductPrice />
                </ProductInfo>
              </ProductCard>
            </Section>
          </ContentContainer>
        </PageWrapper>
      </Layout>
    </App>
  )
}

// After: flattened (faster hydration)
export function FlatApp() {
  return (
    <App>
      <>
        <Header />
        <ProductCard product={product} />
        <Footer />
      </>
    </App>
  )
}
```

Wrapper components that add no interactivity should become Server Components or plain HTML.

## Framework-specific solutions

**Next.js (App Router)**

Server Components are the default. Push `**'use client'**` boundaries as low as possible:

```jsx
// app/product/[id]/page.js
export default async function ProductPage({ params }) {
  const product = await getProduct(params.id)

  return (
    <div>
      {/* Server rendered, no hydration */}
      <h1>{product.name}</h1>
      <p>{product.description}</p>
      <ProductImages images={product.images} />

      {/* Client boundary - only this tree hydrates */}
      <ProductActions product={product} />
    </div>
  )
}
```

For Pages Router, use `**dynamic**` imports with `**ssr: false**` for non-critical components.

**Nuxt 3**

Use `**nuxt-delay-hydration**` module for automatic delay:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-delay-hydration'],
  delayHydration: {
    mode: 'init', // or 'mount' for more aggressive
    debug: process.dev
  }
})
```

For component-level control:

```html
<template>
  <!-- Immediate hydration -->
  <Navigation />

  <!-- Delay hydration until idle -->
  <LazyComments v-if="showComments" />

  <!-- No hydration (static) -->
  <ClientOnly>
    <InteractiveWidget />
    <template #fallback>
      <WidgetPlaceholder />
    </template>
  </ClientOnly>
</template>
```

Nuxt Islands (experimental) provide Astro-like partial hydration.

**Astro**

Islands are built-in. Choose hydration timing with directives:

```astro
<!-- Never hydrates - static HTML -->
<StaticComponent />

<!-- Hydrates immediately -->
<Interactive client:load />

<!-- Hydrates when visible -->
<BelowFold client:visible />

<!-- Hydrates when idle -->
<LowPriority client:idle />

<!-- Hydrates on media query -->
<MobileOnly client:media="(max-width: 768px)" />
```

**Qwik**

[**~~Qwik~~**](https://qwik.dev) uses "resumability" instead of hydration. The server serializes component state and event handlers. On the client, the browser loads handlers on demand when users interact - no upfront hydration.

```jsx
export const Counter = component$(() => {
  const count = useSignal(0)

  return (
    // Handler loads only when clicked
    <button onClick$={() => count.value++}>
      {count.value}
    </button>
  )
})
```

Qwik apps have near-zero JavaScript execution at startup, making early interactions instant.

## Verify the fix

After changes:

1. Test early interactions - click buttons within 1 second of page appearing
2. Compare time-to-interactive vs first contentful paint - gap should shrink
3. Monitor INP for interactions in first 10 seconds of page load
4. Profile hydration time in DevTools - search for hydration-related functions

**TBT**Total Blocking Time

**30% weight **

Good ≤200msPoor >600ms

Expect 50-80% reduction in early-interaction INP with proper hydration strategies.

## Common mistakes

**Hydrating everything**: Even "lazy" loaded components hydrate when their chunk loads. Use true partial hydration (islands) or Server Components.

**Deep component trees**: Wrapper components that exist only for styling or layout still need hydration. Flatten or make them server-only.

**Hydrating invisible components**: Modals, drawers, and tabs that aren't visible on load shouldn't hydrate until needed.

**Not measuring the right thing**: Lab tools often test after hydration completes. Use RUM data to catch real-user early interactions.

## Related issues

Hydration problems often combine with:

- [**~~Long-Running JavaScript~~**](https://unlighthouse.dev/learn-lighthouse/inp/long-running-javascript) - Hydration IS long-running JavaScript
- [**~~Third-Party Scripts~~**](https://unlighthouse.dev/learn-lighthouse/inp/third-party-scripts) - Scripts competing with hydration for main thread

## Test your entire site

Hydration impact varies by page complexity. A simple about page hydrates fast; a product page with reviews, recommendations, and interactive filters takes much longer. [**~~Unlighthouse~~**](https://unlighthouse.dev/) scans your entire site and surfaces TBT during page load across all pages.

### **Related **

[**INP Overview**](https://unlighthouse.dev/learn-lighthouse/inp) [**All INP Issues**](https://unlighthouse.dev/learn-lighthouse/inp#common-inp-issues) [**INP Definition**](https://unlighthouse.dev/glossary/inp) [**INP Analyzer Tool**](https://unlighthouse.dev/tools/inp-analyzer)

[**Event Handler Delays** Slow event handlers directly hurt INP. Optimize click, input, and keypress handlers for instant feedback.](https://unlighthouse.dev/learn-lighthouse/inp/event-handler-delays) [**LCP** LCP measures when the main content loads. Good score: ≤2.5s mobile. Fix slow LCP with image optimization, TTFB improvements, and render-blocking resource removal.](https://unlighthouse.dev/learn-lighthouse/lcp)

**On this page **

- [What's the problem?](#whats-the-problem)
- [How to identify the issue](#how-to-identify-the-issue)
- [The fix](#the-fix)
- [Framework-specific solutions](#framework-specific-solutions)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix Enormous Network Payloads for Better LCP · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/lcp/total-byte-weight
- **Description:** How to reduce total page weight and avoid enormous network payloads that slow down your Largest Contentful Paint.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Enormous Network Payloads for Better LCP**

How to reduce total page weight and avoid enormous network payloads that slow down your Largest Contentful Paint.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)5 min read Published **Jan 18, 2025**

Pages over 4MB take an average of 8+ seconds to load on mobile connections. Every megabyte you trim directly accelerates your LCP.

## What's the problem?

Lighthouse flags pages where total network payload exceeds 2,667KB (the 10th percentile threshold). The median website transfers around 4MB - and that's already too much for most users on mobile networks.

Large payloads hurt LCP in multiple ways. First, more bytes mean longer download times. On a 4G connection averaging 10Mbps, downloading 4MB takes at least 3.2 seconds - before any parsing or rendering begins. Second, large pages consume user bandwidth and data plans, causing throttling on metered connections. Third, memory pressure from large payloads can slow down parsing and rendering, especially on low-end devices.

**Why it hurts LCP:** Your LCP element can't paint until it loads. If that element competes with megabytes of other resources, it waits in line. Even after the LCP resource downloads, large payloads cause processing delays that postpone the actual paint.

## How to identify this issue

### Lighthouse

Look for the audit "Avoid enormous network payloads" under Diagnostics. It shows:

- Total transfer size in KB
- Top 10 largest resources sorted by size
- Red if total exceeds \~2.5MB, yellow above \~1.3MB

### Chrome DevTools network tab

1. Open DevTools → Network tab
2. Reload the page with cache disabled (Ctrl+Shift+R)
3. Check the summary bar at the bottom: "X requests, Y MB transferred"
4. Sort by "Size" column to find largest offenders
5. Filter by type (JS, CSS, Img) to identify categories

You can also export a HAR file from the Network tab and analyze it with the [**~~HAR Viewer~~**](https://unlighthouse.dev/tools/har-viewer) to inspect per-request timing and sizes.

### Page size checker

Use the [**~~Page Size Checker~~**](https://unlighthouse.dev/tools/page-size) to quickly test any URL's total page weight, resource breakdown, third-party contribution, and see how it compares against HTTP Archive percentiles.

### Webpagetest

Run a test and check:

- "Bytes In" in the summary
- Content breakdown pie chart
- Request waterfall sorted by bytes

## The fix

### 1. optimize images (usually the biggest win)

Images typically account for 50%+ of page weight. Target: under 200KB per hero image.

```html
<!-- Before: 2MB unoptimized PNG -->
<img src="hero.png" />

<!-- After: Responsive WebP with fallback -->
<picture>
  <source srcset="hero-400.webp 400w, hero-800.webp 800w, hero-1200.webp 1200w"
          sizes="(max-width: 600px) 100vw, 50vw"
          type="image/webp" />
  <img src="hero-800.jpg" alt="Hero" loading="eager" />
</picture>
```

Compress images with modern formats:

- WebP: 25-35% smaller than JPEG at same quality
- AVIF: 50% smaller than JPEG (limited browser support)

```bash
cwebp -q 80 hero.png -o hero.webp

npx sharp-cli --input "*.{jpg,png}" --output webp --webp
```

### 2. enable compression

All text-based assets (HTML, CSS, JS, JSON, SVG) should use Brotli or gzip compression.

**Nginx configuration:**

```nginx
brotli on;
brotli_types text/plain text/css application/javascript application/json image/svg+xml;
brotli_comp_level 6;

gzip on;
gzip_types text/plain text/css application/javascript application/json image/svg+xml;
gzip_min_length 256;
```

**Verify compression in DevTools:**

- Network tab → select a JS/CSS file → Headers → look for `**content-encoding: br**` or `**gzip**`

Compression typically reduces text assets by 60-80%.

### 3. remove unused dependencies

Audit your node\_modules and remove packages you don't use.

```bash
npx cost-of-modules

npx webpack-bundle-analyzer stats.json

npx vite-bundle-visualizer
```

Replace heavy libraries with lighter alternatives:

- `**moment.js**` (300KB) → `**date-fns**` (tree-shakeable) or `**dayjs**` (2KB)
- `**lodash**` (70KB) → native ES6 methods or `**lodash-es**` (tree-shakeable)
- `**axios**` (13KB) → native `**fetch**`

### 4. lazy load below-the-fold content

Only load what's needed for the initial viewport.

```js
// Lazy load images
<img src="product.jpg" loading="lazy" />

// Dynamic import for heavy components
const HeavyChart = () => import('./HeavyChart.vue')

// Intersection Observer for custom lazy loading
const observer = new IntersectionObserver((entries) => {
  entries.forEach((entry) => {
    if (entry.isIntersecting) {
      loadHeavyModule()
      observer.disconnect()
    }
  })
})
observer.observe(document.querySelector('#chart-container'))
```

### 5. set cache headers

Proper caching prevents re-downloading unchanged assets.

```nginx
location ~* \.(js | css | png | jpg | webp | woff2)$ {
  expires 1y;
  add_header Cache-Control "public, immutable";
}

location ~* \.html$ {
  expires 5m;
  add_header Cache-Control "public, must-revalidate";
}
```

## Why this works

Reducing total bytes directly reduces download time. On a typical 4G connection (10Mbps):

- 4MB payload = 3.2 seconds minimum download time
- 1MB payload = 0.8 seconds minimum download time

That's 2.4 seconds saved before any other optimization. The browser can start parsing, executing, and rendering sooner when there's less to download.

**LCP**Largest Contentful Paint** CWV **

**25% weight **

Good ≤2.5sPoor >4.0s

## Framework-specific solutions

**Next.js**

Next.js Image component automatically optimizes images:

```jsx
import Image from 'next/image'

// Automatic WebP/AVIF, responsive sizes, lazy loading
export const Hero = () => <Image src="/hero.jpg" width={1200} height={600} priority alt="Hero" />
```

Enable compression in `**next.config.js**`:

```js
export default {
  compress: true, // gzip by default
}
```

**Nuxt**

Use `**@nuxt/image**` for automatic image optimization:

```html
<NuxtImg src="/hero.jpg" width="1200" format="webp" />
```

Configure compression via Nitro:

```ts
export default defineNuxtConfig({
  nitro: {
    compressPublicAssets: true,
  }
})
```

## Verify the fix

After implementing:

1. Run Lighthouse → "Avoid enormous network payloads" should show green (< 1.3MB) or yellow (< 2.5MB)
2. Check Network tab → total transferred should be significantly lower
3. Compare total bytes in WebPageTest before/after
4. Verify compression headers are present on text assets

**Target thresholds:**

- Excellent: < 1,282KB (p10)
- Acceptable: < 2,667KB
- Poor: > 4,000KB (median)

## Common mistakes

- **Forgetting font subsetting**: Full Google Fonts can add 500KB+. Subset to characters you use.
- **Serving uncompressed assets**: Check that your CDN/server enables Brotli/gzip.
- **Loading all JavaScript upfront**: Split bundles and lazy load routes.
- **Using oversized favicons**: A 256x256 PNG favicon is overkill. Use SVG or properly sized ICO.
- **Ignoring third-party scripts**: Tag managers, analytics, and widgets can add 500KB+ easily.

## Related issues

Often appears alongside:

- [**~~Unminified JavaScript~~**](https://unlighthouse.dev/learn-lighthouse/lcp/unminified-javascript) - Bloated JS increases page weight
- [**~~Unused JavaScript~~**](https://unlighthouse.dev/learn-lighthouse/lcp/unused-javascript) - Dead code adds unnecessary bytes
- [**~~Large Images~~**](https://unlighthouse.dev/learn-lighthouse/lcp/large-images) - Usually the biggest contributor to page weight

## Test your entire site

Page weight varies between templates - your homepage might be lean while product pages are bloated. [**~~Unlighthouse~~**](https://unlighthouse.dev/) crawls your entire site and identifies the heaviest pages by total transfer size.

### **Related **

[**LCP Overview**](https://unlighthouse.dev/learn-lighthouse/lcp) [**All LCP Issues**](https://unlighthouse.dev/learn-lighthouse/lcp#common-lcp-issues) [**LCP Definition**](https://unlighthouse.dev/glossary/lcp) [**LCP Finder Tool**](https://unlighthouse.dev/tools/lcp-finder) [**Page Size Checker**](https://unlighthouse.dev/tools/page-size) [**HAR File Viewer**](https://unlighthouse.dev/tools/har-viewer)

[**Slow Server Response** Reduce server response time to improve LCP. Learn CDN setup, caching strategies, database optimization, and edge computing solutions.](https://unlighthouse.dev/learn-lighthouse/lcp/slow-server-response) [**Unminified JavaScript** How to minify JavaScript files to reduce payload sizes, improve parse time, and accelerate your Largest Contentful Paint.](https://unlighthouse.dev/learn-lighthouse/lcp/unminified-javascript)

**On this page **

- [What's the problem?](#whats-the-problem)
- [How to identify this issue](#how-to-identify-this-issue)
- [The fix](#the-fix)
- [Why this works](#why-this-works)
- [Framework-specific solutions](#framework-specific-solutions)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** LCP Optimization Best Practices 2026: The Complete Guide · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/lcp/best-practices-2026
- **Description:** A practical 2026 LCP playbook using Lighthouse 13 Insights, Priority Hints, early resource discovery, modern images, and field data.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **LCP Optimization Best Practices 2026: The Complete Guide**

A practical 2026 LCP playbook using Lighthouse 13 Insights, Priority Hints, early resource discovery, modern images, and field data.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)12 min read Published **Apr 13, 2026** Updated **Aug 9, 2026**

**LCP**Largest Contentful Paint** CWV **

**25% weight **

Good ≤2.5sPoor >4.0s

:: ::

### **Related **

[**LCP Overview**](https://unlighthouse.dev/learn-lighthouse/lcp) [**Core Web Vitals**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) [**LCP Definition**](https://unlighthouse.dev/glossary/lcp) [**LCP Finder Tool**](https://unlighthouse.dev/tools/lcp-finder) [**Bulk PageSpeed Test**](https://unlighthouse.dev/tools/bulk-pagespeed)

[**Unused JavaScript** How to reduce unused JavaScript through code splitting, tree shaking, and dynamic imports to improve your Largest Contentful Paint.](https://unlighthouse.dev/learn-lighthouse/lcp/unused-javascript) [**Render-Blocking Resources** How to eliminate render-blocking CSS and JavaScript in the Lighthouse audit. Async/defer scripts, critical CSS extraction, font loading, and Next.js optimizeCss config.](https://unlighthouse.dev/learn-lighthouse/lcp/render-blocking-resources)

**On this page **

- Priority Hints are baseline
- Speculation Rules prerendering
- Lighthouse 13 Insights panel
- 103 Early Hints
- View Transitions are a separate concern
- Modern image formats
- Font loading with size-adjust
- Main thread work can delay paint
- Treat HTTP/3 as a transport improvement
- Edge rendering and streaming SSR
- Nuxt 4: render the LCP element in HTML
- Verify with field data
- Scan every page
- 2026 LCP Optimization Strategy

---

- **Page:** Fix Unminified JavaScript for Better LCP · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/lcp/unminified-javascript
- **Description:** How to minify JavaScript files to reduce payload sizes, improve parse time, and accelerate your Largest Contentful Paint.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Unminified JavaScript for Better LCP**

How to minify JavaScript files to reduce payload sizes, improve parse time, and accelerate your Largest Contentful Paint.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)5 min read Published **Jan 18, 2025**

Unminified JavaScript files can be 60-80% larger than necessary. Lighthouse flags scripts where over 10% of bytes could be saved through minification - wasted bytes that directly delay your LCP.

## What's the problem?

Minification removes whitespace, shortens variable names, and eliminates dead code without changing functionality. When you ship unminified JavaScript, you're transferring unnecessary bytes that serve no purpose in production.

Lighthouse triggers this audit when a script has more than 10% potential savings AND at least 2KB could be saved. That threshold exists because minification always provides some benefit - only scripts with significant waste get flagged.

**Why it hurts LCP:** JavaScript must download and parse before your page becomes interactive. Unminified scripts take longer to download (more bytes) and longer to parse (more tokens for the engine to process). If your LCP element depends on JavaScript to render, common in SPAs, those extra milliseconds directly delay your largest paint.

Consider a typical [**~~React~~**](https://react.dev) app bundle. An unminified version might be 800KB. Minified with Terser, it drops to 250KB. With gzip compression on top, it becomes 80KB. That's a 10x reduction in transfer size from two simple build steps.

## How to identify this issue

### Lighthouse

Look for the audit "Minify JavaScript" under Opportunities. It shows:

- Each unminified script URL
- Total transfer size
- Potential savings in KB
- Red flag if savings exceed 8KB per file

### Chrome DevTools

**Network Tab Method:**

1. Open DevTools → Network tab
2. Filter by "JS" type
3. Click a script file
4. Look at the Response tab - readable code with whitespace indicates unminified

**Sources Tab Method:**

1. Open DevTools → Sources tab
2. Navigate to your JS files
3. If code is readable with full variable names and comments, it's unminified
4. Minified code appears as long, dense lines with single-letter variables

### Coverage tab

1. Open DevTools → More tools → Coverage
2. Click the reload button
3. Red bars indicate unused code, but check file names - `**.min.js**` suggests minification, plain `**.js**` may not be

## The fix

### 1. configure your bundler for production mode

Most bundlers minify automatically in production mode.

**Vite (recommended):**

```js
// vite.config.js
import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    minify: 'terser', // or 'esbuild' (default, faster)
    terserOptions: {
      compress: {
        drop_console: true, // Remove console.log
        drop_debugger: true // Remove debugger statements
      }
    }
  }
})
```

[**~~Vite~~**](https://vite.dev) uses [**~~esbuild~~**](https://esbuild.github.io) by default (faster) but Terser produces smaller output.

**webpack:**

```js
// webpack.config.js
import TerserPlugin from 'terser-webpack-plugin'

export default {
  mode: 'production', // Enables minification
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        terserOptions: {
          compress: {
            drop_console: true,
          },
          mangle: true,
          format: {
            comments: false,
          },
        },
        extractComments: false,
      }),
    ],
  },
}
```

**Rollup:**

```js
// rollup.config.js
import terser from '@rollup/plugin-terser'

const config2 = {
  plugins: [
    terser({
      compress: {
        passes: 2,
        drop_console: true,
      },
      mangle: true,
    })
  ]
}
```

### 2. verify build output

After configuring, verify your output is minified.

```bash
ls -la dist/assets/*.js
```

Inspect the output file - it should be dense, single-line code:

```js
// Unminified (don't ship this)
function calculateTotal(items) {
  let total = 0
  for (const item of items) {
    total += item.price * item.quantity
  }
  return total
}
```

// Minified (ship this)

```text
function calculateTotalMinified(e){let t=0;for(const l of e)t+=l.price*l.quantity;return t}
```

### 3. minify third-party scripts

Self-hosted libraries might not be minified. Check and replace.

```html
<!-- Before: unminified -->
<script src="/js/lodash.js"></script>

<!-- After: minified -->
<script src="/js/lodash.min.js"></script>
```

For [**~~npm~~**](https://npmjs.com) packages, ensure you're importing production builds:

```js
// Some packages require explicit production imports
import Vue from 'vue/dist/vue.runtime.min.js'
```

### 4. use a CDN with automatic minification

CDNs like [**~~Cloudflare~~**](https://cloudflare.com) can minify JavaScript on the fly.

**Cloudflare settings:**

1. Speed → Optimization → Auto Minify
2. Enable "JavaScript" checkbox

This catches any scripts that slip through your build process.

### 5. minify inline scripts

Don't forget `**<script>**` tags embedded in HTML.

```html
<!-- Before -->
<script>
  // Initialize analytics
  window.dataLayer = window.dataLayer || [];
  function gtag() {
    dataLayer.push(arguments);
  }
  gtag('js', new Date());
  gtag('config', 'G-XXXXXX');
</script>

<!-- After -->
<script>window.dataLayer=window.dataLayer || [];function gtag(){dataLayer.push(arguments)}gtag("js",new Date);gtag("config","G-XXXXXX");</script>
```

Use HTML minification plugins to handle this automatically:

```js
// vite.config.js
import { createHtmlPlugin } from 'vite-plugin-html'

const config3 = {
  plugins: [
    createHtmlPlugin({
      minify: true
    })
  ]
}
```

## Why this works

Minification reduces JavaScript size through three mechanisms:

1. **Whitespace removal**: Spaces, tabs, and newlines add zero value in production
2. **Identifier mangling**: `**calculateTotalPrice**` becomes `**a**`, `**userPreferences**` becomes `**b**`
3. **Dead code elimination**: Unused exports and unreachable branches are stripped

The result: 60-80% smaller files that parse faster. Smaller files also compress better - Brotli works more efficiently on dense, repetitive minified code.

**LCP**Largest Contentful Paint** CWV **

**25% weight **

Good ≤2.5sPoor >4.0s

## Framework-specific solutions

**Next.js**

[**~~Next.js~~**](https://nextjs.org) minifies automatically in production. Verify with:

```bash
npm run build

# + /_app 87 kb 87 kb
```

For additional compression, enable SWC minification (default in Next 13+):

```js
// next.config.js
const config4 = {
  swcMinify: true,
}
```

**Nuxt**

Nuxt 3 uses Vite with esbuild minification by default. For smaller output with Terser:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  vite: {
    build: {
      minify: 'terser',
    }
  }
})
```

Check bundle sizes after build:

```bash
npx nuxi build
```

**Vue CLI**

Vue CLI minifies in production mode by default:

```bash
npm run build -- --mode production
```

Verify in `**vue.config.js**`:

```js
const config5 = {
  productionSourceMap: false, // Smaller builds
  configureWebpack: {
    optimization: {
      minimize: true
    }
  }
}
```

## Verify the fix

After implementing:

1. Run Lighthouse → "Minify JavaScript" should pass or show minimal savings
2. Check DevTools Sources → JS files should be dense, unreadable code
3. Compare file sizes before/after (aim for 60-80% reduction)
4. Test in staging to ensure functionality isn't broken

**File size targets:**

| **Original Size** | **After Minification** | **After Gzip** | **After Brotli** |
| --- | --- | --- | --- |
| 100KB | 30-40KB | 10-15KB | 8-12KB |
| 500KB | 150-200KB | 50-70KB | 40-55KB |
| 1MB | 300-400KB | 100-140KB | 80-110KB |

## Common mistakes

- **Forgetting to set NODE\_ENV=production**: Many tools only minify when `**process.env.NODE_ENV === 'production'**`
- **Shipping source maps to production**: Source maps help debugging but add significant bytes. Disable or host separately.
- **Double-minifying**: Minifying already-minified code wastes build time and can break code
- **Aggressive compression breaking code**: Some Terser options (like `**unsafe**`) can break functionality. Test thoroughly.
- **Ignoring vendor bundles**: Split vendor code so the browser can cache it separately, but make sure you still minify it.

## Related issues

Often appears alongside:

- [**~~Unused JavaScript~~**](https://unlighthouse.dev/learn-lighthouse/lcp/unused-javascript) - Even minified unused code wastes bytes
- [**~~Total Byte Weight~~**](https://unlighthouse.dev/learn-lighthouse/lcp/total-byte-weight) - Unminified JS inflates total page weight
- [**~~Render-Blocking Resources~~**](https://unlighthouse.dev/learn-lighthouse/lcp/render-blocking-resources) - Large JS files block rendering longer

## Test your entire site

Different pages may load different JavaScript bundles - some minified, some not. [**~~Unlighthouse~~**](https://unlighthouse.dev/) scans every page on your site and flags any scripts that aren't properly minified.

### **Related **

[**LCP Overview**](https://unlighthouse.dev/learn-lighthouse/lcp) [**All LCP Issues**](https://unlighthouse.dev/learn-lighthouse/lcp#common-lcp-issues) [**LCP Definition**](https://unlighthouse.dev/glossary/lcp) [**LCP Finder Tool**](https://unlighthouse.dev/tools/lcp-finder)

[**Total Byte Weight** How to reduce total page weight and avoid enormous network payloads that slow down your Largest Contentful Paint.](https://unlighthouse.dev/learn-lighthouse/lcp/total-byte-weight) [**Unused JavaScript** How to reduce unused JavaScript through code splitting, tree shaking, and dynamic imports to improve your Largest Contentful Paint.](https://unlighthouse.dev/learn-lighthouse/lcp/unused-javascript)

**On this page **

- [What's the problem?](#whats-the-problem)
- [How to identify this issue](#how-to-identify-this-issue)
- [The fix](#the-fix)
- [Why this works](#why-this-works)
- [Framework-specific solutions](#framework-specific-solutions)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix Resource Load Delay for Better LCP · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/lcp/resource-load-delay
- **Description:** How to reduce resource load delay by preloading LCP resources and prioritizing critical assets.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Resource Load Delay for Better LCP**

How to reduce resource load delay by preloading LCP resources and prioritizing critical assets.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)5 min read Published **Jan 12, 2025**

The median site with poor LCP [**~~spends 1.3 seconds on resource load delay~~**](https://web.dev/blog/common-misconceptions-lcp) - time wasted before even starting to download the LCP image.

## What's the problem?

Resource load delay is the time between when the browser receives the HTML and when it starts downloading the LCP resource. This happens when:

- The LCP image URL isn't in the initial HTML (e.g., set by JavaScript or CSS)
- Other resources are queued ahead of the LCP resource
- The browser doesn't know the image is important

**Why it hurts LCP:** Every millisecond spent waiting to *start* downloading is a millisecond added to LCP.

## How to identify this issue

### Chrome DevTools

1. Performance tab → record → reload
2. Find your LCP image in the Network section
3. Look at when the request starts vs. when HTML arrived
4. Large gap = resource load delay

### Webpagetest

Look at the waterfall chart. If the LCP image request starts late (far to the right), you have resource load delay.

## The fix

### 1. preload the LCP image

Tell the browser to start downloading the LCP image immediately.

```html
<head>
  <!-- Preload LCP image -->
  <link
    rel="preload"
    href="/images/hero.webp"
    as="image"
    fetchpriority="high"
  >
</head>
```

For responsive images:

```html
<link
  rel="preload"
  as="image"
  href="/images/hero.webp"
  imagesrcset="/images/hero-400.webp 400w, /images/hero-800.webp 800w"
  imagesizes="100vw"
  fetchpriority="high"
>
```

### 2. use fetchpriority="high"

Tell the browser this resource is critical.

```html
<img
  src="/images/hero.webp"
  fetchpriority="high"
  alt="Hero image"
>
```

The `**fetchpriority**` attribute has grown from [**~~0.03% adoption in 2022 to 15% in 2024~~**](https://almanac.httparchive.org/en/2024/performance).

### 3. include LCP resource in HTML

If your LCP image URL is set by JavaScript or CSS, move it to HTML.

```html
<!-- Before: image URL in CSS (discovered late) -->
<div class="hero" style="background-image: url(hero.webp)"></div>

<!-- After: image in HTML (discovered immediately) -->
<img src="hero.webp" class="hero" alt="Hero">
```

```jsx
// Before: image URL from JavaScript (discovered late)
function Hero() {
  const [heroImage, setHeroImage] = useState(null)
  useEffect(() => {
    setHeroImage('/hero.webp')
  }, [])
  return heroImage ? <img src={heroImage} /> : null
}

// After: image in initial render
const HeroNew = () => <img src="/hero.webp" alt="Hero" />
```

### 4. avoid lazy-loading LCP

Never use `**loading="lazy"**` on your LCP image.

```html
<!-- Wrong: lazy-loading LCP image -->
<img src="hero.webp" loading="lazy" alt="Hero">

<!-- Correct: eager loading (default) with high priority -->
<img src="hero.webp" loading="eager" fetchpriority="high" alt="Hero">
```

About [**~~10% of LCP images are incorrectly lazy-loaded~~**](https://almanac.httparchive.org/en/2024/performance).

### 5. reduce request chains

If your LCP resource depends on other resources loading first, eliminate the chain.

```html
<!-- Before: chain of dependencies -->
<!-- HTML → CSS → background-image URL → image download -->

<!-- After: direct preload -->
<link rel="preload" href="hero.webp" as="image" fetchpriority="high">
```

## Framework-specific solutions

**Next.js**

Use `**priority**` prop on `**next/image**`:

```jsx
import Image from 'next/image'

export function HeroImage() {
  return (
    <Image
      src="/hero.jpg"
      priority // Adds preload + fetchpriority
      alt="Hero"
    />
  )
}
```

**Nuxt**

Use `**preload**` prop on `**NuxtImg**`:

```html
<NuxtImg
  src="/hero.jpg"
  preload
  alt="Hero"
/>
```

Or use `**useHead**` for manual preload:

```ts
useHead({
  link: [{ rel: 'preload', href: '/hero.webp', as: 'image', fetchpriority: 'high' }]
})
```

## Verify the fix

After implementing:

1. Check Network tab - LCP image should start downloading earlier
2. Run Lighthouse - look for preload suggestions
3. Compare LCP scores before/after

**Expected improvement:** Eliminating 1.3 seconds of resource load delay can improve LCP by 1.3 seconds.

## Common mistakes

- **Preloading too many resources**: Only preload the most critical 2-3 resources. Too many preloads compete for bandwidth.
- **Wrong preload attributes**: Incorrect `**as**` attribute or missing `**crossorigin**` for fonts causes double downloads.
- **Preloading dynamic URLs**: If the image URL changes per page, use server-side rendering to set the correct preload.

## Related issues

Often appears alongside:

- [**~~Large Images~~**](https://unlighthouse.dev/learn-lighthouse/lcp/large-images) - Preloading a 2MB image doesn't help much
- [**~~Lazy-Loading Above Fold~~**](https://unlighthouse.dev/learn-lighthouse/lcp/lazy-loading-above-fold) - Related anti-pattern

## Test your entire site

Resource load delay varies by page. [**~~Unlighthouse~~**](https://unlighthouse.dev/) scans your entire site and identifies pages where the browser discovers LCP resources late.

### **Related **

[**LCP Overview**](https://unlighthouse.dev/learn-lighthouse/lcp) [**All LCP Issues**](https://unlighthouse.dev/learn-lighthouse/lcp#common-lcp-issues) [**LCP Definition**](https://unlighthouse.dev/glossary/lcp) [**LCP Finder Tool**](https://unlighthouse.dev/tools/lcp-finder) [**HAR File Viewer**](https://unlighthouse.dev/tools/har-viewer)

[**Prioritize LCP Image** Add fetchpriority='high' and preload your LCP image. 85% of sites miss this — one attribute can cut LCP by 100-400ms.](https://unlighthouse.dev/learn-lighthouse/lcp/prioritize-lcp-image) [**Client-Side Rendering** How to improve LCP by using server-side rendering or pre-rendering instead of client-side rendering.](https://unlighthouse.dev/learn-lighthouse/lcp/client-side-rendering)

**On this page **

- [What's the problem?](#whats-the-problem)
- [How to identify this issue](#how-to-identify-this-issue)
- [The fix](#the-fix)
- [Framework-specific solutions](#framework-specific-solutions)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix Unused JavaScript for Better LCP · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/lcp/unused-javascript
- **Description:** How to reduce unused JavaScript through code splitting, tree shaking, and dynamic imports to improve your Largest Contentful Paint.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Unused JavaScript for Better LCP**

How to reduce unused JavaScript through code splitting, tree shaking, and dynamic imports to improve your Largest Contentful Paint.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)6 min read Published **Jan 18, 2025**

The average website ships 400KB of JavaScript, but only 100-200KB executes during page load. That unused code still downloads, parses, and compiles - wasting time before your LCP can paint.

## What's the problem?

Lighthouse flags scripts with more than 20KB of unused bytes. This happens when you bundle code for features the current page doesn't need: routes the user hasn't visited, components that only appear on interaction, or library functions you never call.

Modern bundlers make it easy to ship everything in one file. Convenient for developers, expensive for users. A visitor to your homepage downloads JavaScript for your checkout flow, admin panel, and every product page - even though they'll likely never see most of it.

**Why it hurts LCP:** JavaScript is render-blocking by default and expensive even when deferred. The browser must download, parse, and compile all JavaScript before it can execute. Parse and compile time scales with file size regardless of whether the code runs. On mobile devices, parsing 1MB of JavaScript can take 2-4 seconds of main thread time.

## How to identify this issue

### Lighthouse

Look for the audit "Reduce unused JavaScript" under Opportunities. It shows:

- Each script URL with unused bytes
- Total size vs wasted bytes
- Wasted percentage per file
- Sub-items showing which source files contribute most waste (if source maps available)

Lighthouse ignores scripts with less than 20KB unused - below that threshold, the overhead of splitting isn't worth it.

### Chrome DevTools coverage tab

The Coverage tab shows exactly which bytes execute during page load.

1. Open DevTools → More tools → Coverage (or Ctrl+Shift+P → "Show Coverage")
2. Click the reload button to start recording
3. The page reloads and coverage data populates

**Reading the results:**

- Red bars = unused bytes (downloaded but never executed)
- Blue/green bars = used bytes (executed)
- Click any file to see line-by-line coverage in Sources panel

**Pro workflow:**

1. Record coverage on page load
2. Interact with the page (open modals, navigate, etc.)
3. Compare how coverage changes - code that turns blue on interaction is a candidate for lazy loading

### Bundle analyzer tools

Visualize what's in your bundles:

```bash
npx webpack-bundle-analyzer stats.json

npx vite-bundle-visualizer

npx rollup-plugin-visualizer
```

Look for:

- Large node\_modules you don't recognize
- Duplicate dependencies
- Entire libraries when you only use one function

## The fix

### 1. route-based code splitting

Split your bundle by route so each page loads only what it needs.

**React Router:**

```jsx
import { lazy, Suspense } from 'react'
import { Route, Routes } from 'react-router-dom'

// Dynamic imports create separate chunks
const Home = lazy(() => import('./pages/Home'))
const Product = lazy(() => import('./pages/Product'))
const Checkout = lazy(() => import('./pages/Checkout'))

function App() {
  return (
    <Suspense fallback={<Loading />}>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/product/:id" element={<Product />} />
        <Route path="/checkout" element={<Checkout />} />
      </Routes>
    </Suspense>
  )
}
```

**Vue Router:**

```js
// router.js
const routes = [
  {
    path: '/',
    component: () => import('./views/Home.vue')
  },
  {
    path: '/product/:id',
    component: () => import('./views/Product.vue')
  },
  {
    path: '/checkout',
    component: () => import('./views/Checkout.vue')
  }
]
```

### 2. component-level code splitting

Lazy load heavy components that don't appear immediately.

```jsx
// React
const HeavyChart = lazy(() => import('./HeavyChart'))

function Dashboard() {
  const [showChart, setShowChart] = useState(false)

  return (
    <div>
      <button onClick={() => setShowChart(true)}>Show Analytics</button>
      {showChart && (
        <Suspense fallback={<Spinner />}>
          <HeavyChart />
        </Suspense>
      )}
    </div>
  )
}
```

```html
<!-- Vue -->
<script setup>
import { defineAsyncComponent, ref } from 'vue'

const HeavyChart = defineAsyncComponent(() => import('./HeavyChart.vue'))
const showChart = ref(false)
</script>

<template>
  <button @click="showChart = true">
    Show Analytics
  </button>
  <HeavyChart v-if="showChart" />
</template>
```

### 3. tree shaking optimization

Tree shaking removes unused exports, but only works with ES modules.

**Enable ES modules in your library imports:**

```js
// Bad: imports entire library
import _ from 'lodash'

// Best: use lodash-es for full tree shaking
import { debounce as debounceEs } from 'lodash-es'

// Good: imports only what you use
import debounce from 'lodash/debounce'

_.debounce(fn, 300)
debounce(fn, 300)
```

**Verify tree shaking works in your bundler:**

```js
// vite.config.js
export default {
  build: {
    rollupOptions: {
      output: {
        manualChunks: undefined // Let Rollup tree shake freely
      }
    }
  }
}
```

```js
// webpack.config.js
const config2 = {
  mode: 'production',
  optimization: {
    usedExports: true, // Mark unused exports
    sideEffects: true, // Enable tree shaking
  }
}
```

**Mark your package as side-effect free:**

```json
// package.json
{
  "sideEffects": false
}
```

Or specify which files have side effects:

```json
{
  "sideEffects": ["*.css", "./src/polyfills.js"]
}
```

### 4. replace heavy dependencies

Swap large libraries for lighter alternatives.

| **Heavy Library** | **Size** | **Lighter Alternative** | **Size** |
| --- | --- | --- | --- |
| moment | 300KB | date-fns (tree-shakeable) | 13KB used |
| moment | 300KB | dayjs | 2KB |
| lodash | 70KB | lodash-es (tree-shakeable) | varies |
| axios | 13KB | native fetch | 0KB |
| jQuery | 90KB | native DOM | 0KB |
| chart.js | 200KB | uPlot | 35KB |

```text
// After: dayjs (2KB)
import dayjs from 'dayjs'

// Before: moment (300KB)
import moment from 'moment'

moment().format('YYYY-MM-DD')
dayjs().format('YYYY-MM-DD')
```

### 5. analyze and remove dead code

Use coverage data to find and eliminate unused code.

```bash
npx ts-prune

# Src/utils/legacy.ts:15 - unusedfunction
# Src/components/oldbutton.tsx:1 - default
```

Review and delete files that Coverage shows as 100% unused.

## Why this works

Less JavaScript means:

- **Faster download:** Fewer bytes to transfer over the network
- **Faster parse:** The JavaScript engine processes less code
- **Faster compile:** JIT compilation has less work to do
- **Less memory:** Smaller heap allocation

Parse and compile time particularly impact mobile devices. V8 (Chrome's engine) can parse JavaScript at roughly 1MB/second on a mid-range phone. A 500KB bundle takes 500ms of main thread time to parse - before any code executes.

**LCP**Largest Contentful Paint** CWV **

**25% weight **

Good ≤2.5sPoor >4.0s

## Framework-specific solutions

**Next.js**

[**~~Next.js~~**](https://nextjs.org) automatically code-splits by route. For component-level splitting:

```jsx
import dynamic from 'next/dynamic'

const HeavyComponent = dynamic(() => import('./HeavyComponent'), {
  loading: () => <Spinner />,
  ssr: false // Skip server rendering for client-only components
})
```

Analyze bundles with:

```bash
ANALYZE=true npm run build
```

Enable in `**next.config.js**`:

```js
import withBundleAnalyzerFactory from '@next/bundle-analyzer'

const withBundleAnalyzer = withBundleAnalyzerFactory({
  enabled: process.env.ANALYZE === 'true',
})

export default withBundleAnalyzer({})
```

**Nuxt**

Nuxt 3 code-splits routes automatically. For components:

```html
<script setup>
// Lazy-loaded component (automatic code splitting)
const HeavyChart = defineAsyncComponent(() => import('./HeavyChart.vue'))
</script>
```

Or use the `**Lazy**` prefix for automatic async loading:

```html
<template>
  <!-- Automatically lazy-loaded -->
  <LazyHeavyChart v-if="showChart" />
</template>
```

Analyze bundles:

```bash
npx nuxi analyze
```

**Vue (Vite)**

Vue with [**~~Vite~~**](https://vite.dev) handles async components natively:

```js
// Async component with loading state
const AsyncComponent = defineAsyncComponent({
  loader: () => import('./HeavyComponent.vue'),
  loadingComponent: LoadingSpinner,
  delay: 200,
  errorComponent: ErrorDisplay
})
```

For route-level splitting with Vue Router, use dynamic imports as shown above.

## Verify the fix

After implementing:

1. Run Lighthouse → "Reduce unused JavaScript" should show lower wasted bytes
2. Open Coverage tab → you should see significantly reduced red bars
3. Check Network tab → main bundle should be smaller, with additional chunks loading on navigation
4. Test user flows → lazy-loaded content should appear without noticeable delay

**Targets:**

- Main bundle: < 100KB compressed
- Route chunks: < 50KB each
- Unused bytes: < 20% of total JavaScript

**Quick validation:**

```bash
Total JS: 500KB (340KB unused)

Initial JS: 150KB (30KB unused)
Route chunks: load on navigation
```

## Common mistakes

- **Splitting too aggressively**: Creating dozens of tiny chunks adds HTTP overhead. Aim for 5-15 chunks, not 100.
- **Forgetting to preload critical chunks**: If a lazy component appears above the fold, preload it
- **Breaking shared dependencies**: Code that's used across routes should be in a shared chunk, not duplicated
- **Ignoring third-party bundles**: Heavy [**~~npm~~**](https://npmjs.com) packages often need replacement, not just splitting
- **Not testing the loading experience**: Lazy-loaded content needs loading states to avoid layout shift

## Related issues

Often appears alongside:

- [**~~Unminified JavaScript~~**](https://unlighthouse.dev/learn-lighthouse/lcp/unminified-javascript) - Minify after splitting for maximum reduction
- [**~~Total Byte Weight~~**](https://unlighthouse.dev/learn-lighthouse/lcp/total-byte-weight) - Unused JS contributes to overall page weight
- [**~~Render-Blocking Resources~~**](https://unlighthouse.dev/learn-lighthouse/lcp/render-blocking-resources) - Split render-blocking scripts too

## Test your entire site

Different pages have different JavaScript requirements - your homepage might be optimized while product pages load unused checkout code. [**~~Unlighthouse~~**](https://unlighthouse.dev/) analyzes every page and shows exactly which routes have the most unused JavaScript.

### **Related **

[**LCP Overview**](https://unlighthouse.dev/learn-lighthouse/lcp) [**All LCP Issues**](https://unlighthouse.dev/learn-lighthouse/lcp#common-lcp-issues) [**LCP Definition**](https://unlighthouse.dev/glossary/lcp) [**LCP Finder Tool**](https://unlighthouse.dev/tools/lcp-finder)

[**Unminified JavaScript** How to minify JavaScript files to reduce payload sizes, improve parse time, and accelerate your Largest Contentful Paint.](https://unlighthouse.dev/learn-lighthouse/lcp/unminified-javascript) [**LCP Best Practices 2026** A practical 2026 LCP playbook using Lighthouse 13 Insights, Priority Hints, early resource discovery, modern images, and field data.](https://unlighthouse.dev/learn-lighthouse/lcp/best-practices-2026)

**On this page **

- [What's the problem?](#whats-the-problem)
- [How to identify this issue](#how-to-identify-this-issue)
- [The fix](#the-fix)
- [Why this works](#why-this-works)
- [Framework-specific solutions](#framework-specific-solutions)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix Lazy-Loading Above the Fold for Better LCP · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/lcp/lazy-loading-above-fold
- **Description:** Why you should never lazy-load your LCP image and how to fix it.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Lazy-Loading Above the Fold for Better LCP**

Why you should never lazy-load your LCP image and how to fix it.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 12, 2025**

About [**~~10% of LCP images are incorrectly lazy-loaded~~**](https://almanac.httparchive.org/en/2024/performance). This is one of the easiest LCP issues to fix.

## What's the problem?

`**loading="lazy"**` tells the browser to delay downloading an image until it's near the viewport. This is great for images below the fold, but terrible for your LCP image which is already visible.

**What happens with lazy-loaded LCP:**

1. Browser downloads HTML
2. Browser sees `**loading="lazy"**`, skips the image
3. Browser finishes layout, determines image is in viewport
4. Browser finally starts downloading the image
5. LCP fires late

## How to identify this issue

### Chrome DevTools

1. Elements panel → find your LCP image
2. Check if it has `**loading="lazy"**`

### Lighthouse

Look for: "Largest Contentful Paint image was lazily loaded"

### Quick check

View your page source and search for your hero image. If it has `**loading="lazy"**`, that's the problem.

## The fix

### 1. remove lazy loading from LCP image

```html
<!-- Before: wrong -->
<img src="hero.webp" loading="lazy" alt="Hero">

<!-- After: correct (eager is the default) -->
<img src="hero.webp" alt="Hero">

<!-- Or explicitly eager with high priority -->
<img src="hero.webp" loading="eager" fetchpriority="high" alt="Hero">
```

### 2. add fetchpriority for extra priority

```html
<img
  src="hero.webp"
  loading="eager"
  fetchpriority="high"
  alt="Hero"
>
```

### 3. keep lazy-loading for below-fold images

Lazy-loading is still valuable - not for above-the-fold content.

```html
<!-- Hero image: no lazy loading -->
<img src="hero.webp" fetchpriority="high" alt="Hero">

<!-- Below-fold images: lazy load -->
<img src="product1.webp" loading="lazy" alt="Product 1">
<img src="product2.webp" loading="lazy" alt="Product 2">
```

## Framework-specific solutions

**Next.js**

`**next/image**` uses `**loading="lazy"**` by default. Use `**priority**` for LCP images:

```jsx
// Wrong: lazy by default
export const LazyImage = () => <Image src="/hero.jpg" alt="Hero" />

// Correct: priority disables lazy loading
export const PriorityImage = () => <Image src="/hero.jpg" alt="Hero" priority />
```

**Nuxt**

`**NuxtImg**` uses lazy loading by default. Use `**loading="eager"**`:

```html
<!-- Wrong: lazy by default -->
<NuxtImg src="/hero.jpg" alt="Hero" />

<!-- Correct: eager loading -->
<NuxtImg src="/hero.jpg" alt="Hero" loading="eager" />
```

**React**

If using a lazy-loading library, exclude above-fold images:

```jsx
// Don't use LazyLoad for LCP
export const Hero = () => <img src="/hero.jpg" alt="Hero" />

// Use LazyLoad for below-fold
export function Product() {
  return (
    <LazyLoad>
      <img src="/product.jpg" alt="Product" />
    </LazyLoad>
  )
}
```

## Verify the fix

After implementing:

1. Check Elements panel - no `**loading="lazy"**` on LCP image
2. Check Network tab - LCP image should start downloading immediately
3. Run Lighthouse - warning should be gone

**Expected improvement:** Removing lazy-loading from LCP can improve LCP by 100-500ms depending on image size and connection.

## Common mistakes

- **Global lazy-loading**: Don't apply `**loading="lazy"**` to all images. Exclude above-the-fold images.
- **Intersection Observer libraries**: Same issue. Exclude LCP images from lazy-loading logic.
- **CMS defaults**: Some CMS platforms add lazy-loading automatically. Override for hero images.

## Related issues

Often appears alongside:

- [**~~Resource Load Delay~~**](https://unlighthouse.dev/learn-lighthouse/lcp/resource-load-delay) - Both delay LCP image download
- [**~~Large Images~~**](https://unlighthouse.dev/learn-lighthouse/lcp/large-images) - Fix both for best results

## Test your entire site

Different page templates may have different lazy-loading behavior. [**~~Unlighthouse~~**](https://unlighthouse.dev/) scans your entire site and identifies pages with lazy-loaded LCP images.

### **Related **

[**LCP Overview**](https://unlighthouse.dev/learn-lighthouse/lcp) [**All LCP Issues**](https://unlighthouse.dev/learn-lighthouse/lcp#common-lcp-issues) [**LCP Definition**](https://unlighthouse.dev/glossary/lcp) [**LCP Finder Tool**](https://unlighthouse.dev/tools/lcp-finder)

[**Large Images** Optimize LCP images with responsive srcset, modern formats like WebP and AVIF, and proper compression. Reduce image size without losing quality.](https://unlighthouse.dev/learn-lighthouse/lcp/large-images) [**Redirects** Eliminate redirect chains that delay LCP. Learn to identify and fix 301/302 redirects, canonical URL issues, and trailing slash mismatches.](https://unlighthouse.dev/learn-lighthouse/lcp/redirects)

**On this page **

- [What's the problem?](#whats-the-problem)
- [How to identify this issue](#how-to-identify-this-issue)
- [The fix](#the-fix)
- [Framework-specific solutions](#framework-specific-solutions)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix Page Redirects for Better LCP · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/lcp/redirects
- **Description:** Eliminate redirect chains that delay LCP. Learn to identify and fix 301/302 redirects, canonical URL issues, and trailing slash mismatches.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Page Redirects for Better LCP**

Eliminate redirect chains that delay LCP. Learn to identify and fix 301/302 redirects, canonical URL issues, and trailing slash mismatches.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)6 min read Published **Jan 18, 2025**

Every redirect adds a full network round-trip before your page begins loading. A single redirect costs 100-500ms. A chain of 3 redirects? That's potentially 1.5 seconds wasted before the browser receives a single byte of HTML.

**LCP**Largest Contentful Paint** CWV **

**25% weight **

Good ≤2.5sPoor >4.0s

## What's the problem?

Redirects force the browser to make additional HTTP requests before reaching the final destination. Lighthouse flags this as "Avoid multiple page redirects" and calculates the cumulative delay. Each redirect in the chain introduces latency from DNS lookup, TCP connection, TLS handshake, and waiting for the server response.

The damage compounds quickly. A user clicks a link to `**http://example.com**`. The server responds with a 301 redirect to `**https://example.com**`. Then another 301 to `**https://www.example.com**`. Then a 302 to `**https://www.example.com/**`. Three redirects, three round-trips, potentially 900ms+ of pure waste before the browser even begins downloading HTML.

Common redirect causes include: HTTP to HTTPS upgrades, www to non-www normalization (or vice versa), trailing slash enforcement, mobile redirects, marketing campaign tracking, and legacy URL migrations. Each is legitimate on its own, but combined they create performance-killing chains that directly inflate LCP.

## How to identify this issue

### Chrome DevTools

1. Open DevTools (F12) and navigate to the Network tab
2. Reload the page and look at the first request
3. If it shows a 301 or 302 status, click it and check the "Location" response header
4. Follow the chain until you see a 200 response
5. Count the redirects - each one costs time

### Command line

```bash
curl -sIL https://example.com 2>&1 | grep -E "^(HTTP | Location)"

curl -w "Redirect: %{redirect_url}\nTime: %{time_total}s\n" -sIL -o /dev/null https://example.com

curl -sIL -o /dev/null -w "%{redirect_url}\n" https://example.com | wc -l
```

### Lighthouse indicators

The "Avoid multiple page redirects" audit appears under Opportunities when Lighthouse detects redirects. Lighthouse shows:

- Each URL in the redirect chain
- Time wasted per redirect in milliseconds
- Total potential savings for LCP and FCP

A passing score means the final URL was reached directly without redirects.

## The fix

### Primary: link directly to final urls

The most effective fix is eliminating redirects at the source - update all internal links, sitemaps, and canonical tags to point to the final destination URL.

```html
<!-- Before: causes redirect chain -->
<a href="http://example.com/products">Products</a>
<link rel="canonical" href="http://www.example.com/products">

<!-- After: direct link to final URL -->
<a href="https://example.com/products/">Products</a>
<link rel="canonical" href="https://example.com/products/">
```

Update your sitemap:

```xml
<!-- Before -->
<url>
  <loc>http://example.com/page</loc>
</url>

<!-- After -->
<url>
  <loc>https://example.com/page/</loc>
</url>
```

Audit all external links pointing to your site (backlinks, social profiles, email signatures) and update where possible.

### Secondary: server-side redirect consolidation

When redirects are necessary, combine multiple rules into a single redirect to the final destination.

```nginx
server {
    listen 80;
    listen 443 ssl;
    server_name example.com www.example.com;

    # Redirect everything to canonical URL in one hop
    if ($scheme != "https") {
        return 301 https://example.com$request_uri;
    }
    if ($host = "www.example.com") {
        return 301 https://example.com$request_uri;
    }
}
```

```apache
RewriteEngine On

RewriteCond %{HTTPS} off [OR]
RewriteCond %{HTTP_HOST} ^www\. [NC]
RewriteRule ^(.*)$ https://example.com/$1/ [R=301,L]
```

For edge/CDN deployments:

```js
// Cloudflare Workers: Single redirect
export default {
  async fetch(request) {
    const url = new URL(request.url)

    // Build canonical URL
    let redirect = false
    if (url.protocol === 'http:') {
      url.protocol = 'https:'
      redirect = true
    }
    if (url.hostname.startsWith('www.')) {
      url.hostname = url.hostname.slice(4)
      redirect = true
    }
    if (!url.pathname.endsWith('/') && !url.pathname.includes('.')) {
      url.pathname += '/'
      redirect = true
    }

    if (redirect) {
      return Response.redirect(url.toString(), 301)
    }

    return fetch(request)
  }
}
```

### Tertiary: 301 vs 302 redirect strategy

Use 301 (permanent) redirects for URLs that have permanently moved. Use 302 (temporary) only for genuinely temporary situations.

```nginx
# 301 for permanent moves - browsers cache these
location /old-page {
    return 301 /new-page/;
}

# 302 only for temporary situations (a/b tests, maintenance)
location /promo {
    return 302 /current-sale/;
}
```

301 redirects allow browsers to cache the redirect, so repeat visitors skip the round-trip entirely. 302 redirects are re-checked every time.

### Bonus: preconnect to redirect destinations

If redirects are unavoidable (third-party services, OAuth flows), preconnect to the destination domain:

```html
<head>
  <!-- Preconnect to OAuth provider -->
  <link rel="preconnect" href="https://auth.provider.com">

  <!-- DNS prefetch as fallback -->
  <link rel="dns-prefetch" href="https://auth.provider.com">
</head>
```

## Why this works

Each redirect eliminated removes a complete network round-trip from the critical path. Without redirects, the browser's first request returns the actual HTML document instead of an instruction to request another URL. The time savings are cumulative - eliminating a chain of 3 redirects at 300ms each saves 900ms directly off LCP. 301 redirects get cached by browsers, meaning returning visitors experience the improvement immediately without any server contact.

## Framework-specific solutions

**Next.js**: Configure redirects in `**next.config.js**` to consolidate at the edge. Use `**trailingSlash**` config to enforce consistency. Deploy to [**~~Vercel~~**](https://vercel.com) for automatic HTTPS and redirect optimization.

```js
// next.config.js
const config2 = {
  trailingSlash: true,
  async redirects() {
    return [
      {
        source: '/old-path',
        destination: '/new-path/',
        permanent: true,
      },
    ]
  },
}
```

**Nuxt**: Use `**routeRules**` for server-side redirects. Configure trailing slash behavior globally. Enable prerender for static routes to avoid redirect processing entirely.

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    '/old-path': { redirect: '/new-path/' },
  },
  nitro: {
    prerender: {
      crawlLinks: true,
    },
  },
})
```

## Verify the fix

After implementing changes:

1. Run the curl command to confirm no redirects occur
2. Check DevTools Network tab - first request should return 200, not 301/302
3. Run Lighthouse and verify "Avoid multiple page redirects" passes
4. Test both www and non-www, HTTP and HTTPS, with and without trailing slashes
5. Verify canonical URLs match the final destination

```bash
for url in "http://example.com" "https://example.com" "http://www.example.com" "https://www.example.com"; do
  echo "Testing: $url"
  curl -sIL "$url" | grep -E "^(HTTP | Location)"
  echo "---"
done
```

**Expected improvement**: Eliminating a typical 2-redirect chain saves 200-600ms on LCP. For mobile users on slower networks, savings can exceed 1 second.

## Common mistakes

**Redirect loops**: Misconfigured rules can create infinite redirect loops (A redirects to B, B redirects to A). Always test the full chain before deploying. Use `**curl -L --max-redirs 10**` to catch loops.

**Inconsistent internal links**: Fixing server redirects but leaving old URLs in internal links still causes redirects. Audit your entire codebase, CMS content, and external properties. Use site-wide search-replace tools.

**Forgetting trailing slash consistency**: Mixing `**/page**` and `**/page/**` creates redirects. Pick one convention and enforce it everywhere - server config, links, canonical tags, and sitemaps.

## Related issues

Redirects often compound other LCP problems:

- [**~~Slow Server Response~~**](https://unlighthouse.dev/learn-lighthouse/lcp/slow-server-response) - Each redirect adds another TTFB cycle
- [**~~Render-Blocking Resources~~**](https://unlighthouse.dev/learn-lighthouse/lcp/render-blocking-resources) - Redirects delay when blocking resources even start downloading
- [**~~Resource Load Delay~~**](https://unlighthouse.dev/learn-lighthouse/lcp/resource-load-delay) - Late-discovered resources are even later after redirects

## Test your entire site

Redirect issues often hide in forgotten corners of your site - old marketing campaign URLs, migrated pages, legacy mobile redirects. A single page audit won't catch redirect chains that only affect specific routes or user agents.

[Scan Your Site with Unlighthouse](https://unlighthouse.dev/)

### **Related **

[**LCP Overview**](https://unlighthouse.dev/learn-lighthouse/lcp) [**All LCP Issues**](https://unlighthouse.dev/learn-lighthouse/lcp#common-lcp-issues) [**LCP Definition**](https://unlighthouse.dev/glossary/lcp) [**LCP Finder Tool**](https://unlighthouse.dev/tools/lcp-finder)

[**Lazy-Loading Above Fold** Why you should never lazy-load your LCP image and how to fix it.](https://unlighthouse.dev/learn-lighthouse/lcp/lazy-loading-above-fold) [**LHCI vs Unlighthouse** Honest side-by-side comparison of @lhci/cli and Unlighthouse. Setup, URL discovery, budgets, reporting, and when each tool fits your workflow.](https://unlighthouse.dev/learn-lighthouse/lhci-vs-unlighthouse)

**On this page **

- [What's the problem?](#whats-the-problem)
- [How to identify this issue](#how-to-identify-this-issue)
- [The fix](#the-fix)
- [Why this works](#why-this-works)
- [Framework-specific solutions](#framework-specific-solutions)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Unlighthouse Release Notes and Changelog · Unlighthouse
- **Source:** https://unlighthouse.dev/releases
- **Description:** Read the latest Unlighthouse release notes, improvements, fixes, and version history.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Unlighthouse Releases**

See what has been shipping recently.

Last fetched: just now.

Please use GitHub to check for realtime updates, this list is only updated every 24 hours.

- 2 months agov 0.**18.0**** Latest **###    🚨 Breaking Changes
  - Require node 22.x  -  by @harlan-zw [`(c1352)`](https://github.com/harlan-zw/unlighthouse/commit/c1352426) #####      [**~~View changes on GitHub~~**](https://github.com/harlan-zw/unlighthouse/compare/v0.17.10...v0.18.0)
- 2 months agov 0.17.**10**###    🐞 Bug Fixes
  - Dashboard empty when opened after scan completes  -  by @ducky-duke and **ducky-duke** in [**~~https://github.com/harlan-zw/unlighthouse/issues/306~~**](https://github.com/harlan-zw/unlighthouse/issues/306) [`(c3883)`](https://github.com/harlan-zw/unlighthouse/commit/c388392c)
  - LCP column blank & report/column metric mismatch (#375, #376)  -  by @harlan-zw in [**~~https://github.com/harlan-zw/unlighthouse/issues/382~~**](https://github.com/harlan-zw/unlighthouse/issues/382), [**~~https://github.com/harlan-zw/unlighthouse/issues/375~~**](https://github.com/harlan-zw/unlighthouse/issues/375) and [**~~https://github.com/harlan-zw/unlighthouse/issues/376~~**](https://github.com/harlan-zw/unlighthouse/issues/376) [`(37f29)`](https://github.com/harlan-zw/unlighthouse/commit/37f29153)
  - Graceful shutdown on Ctrl+C + Git Bash docs  -  by @harlan-zw in [**~~https://github.com/harlan-zw/unlighthouse/issues/378~~**](https://github.com/harlan-zw/unlighthouse/issues/378) and [**~~https://github.com/harlan-zw/unlighthouse/issues/384~~**](https://github.com/harlan-zw/unlighthouse/issues/384) [`(3a4fc)`](https://github.com/harlan-zw/unlighthouse/commit/3a4fc3cf)
  - **client**: Broken screenshot thumbnails in static reports  -  by @harlan-zw in [**~~https://github.com/harlan-zw/unlighthouse/issues/275~~**](https://github.com/harlan-zw/unlighthouse/issues/275) and [**~~https://github.com/harlan-zw/unlighthouse/issues/383~~**](https://github.com/harlan-zw/unlighthouse/issues/383) [`(19ace)`](https://github.com/harlan-zw/unlighthouse/commit/19ace466) #####      [**~~View changes on GitHub~~**](https://github.com/harlan-zw/unlighthouse/compare/v0.17.9...v0.17.10)
- 4 months agov 0.17.**9**###    🐞 Bug Fixes
  - **client**: Repair web UI broken by HeadlessUI removal  -  by @harlan-zw in [**~~https://github.com/harlan-zw/unlighthouse/issues/305~~**](https://github.com/harlan-zw/unlighthouse/issues/305) [`(008cb)`](https://github.com/harlan-zw/unlighthouse/commit/008cbef) #####      [**~~View changes on GitHub~~**](https://github.com/harlan-zw/unlighthouse/compare/v0.17.8...v0.17.9)
- 4 months agov 0.17.**8**###    🏎 Performance
  - Reduce deps  -  by @harlan-zw [`(41211)`](https://github.com/harlan-zw/unlighthouse/commit/41211df) #####      [**~~View changes on GitHub~~**](https://github.com/harlan-zw/unlighthouse/compare/v0.17.7...v0.17.8)
- 6 months agov 0.17.**7**

  *No significant changes*#####      [**~~View changes on GitHub~~**](https://github.com/harlan-zw/unlighthouse/compare/v0.17.6...v0.17.7)
- 6 months agov 0.17.**6**###    🏎 Performance
  - Smaller dependencies  -  by @harlan-zw [`(d83cc)`](https://github.com/harlan-zw/unlighthouse/commit/d83cc87) #####      [**~~View changes on GitHub~~**](https://github.com/harlan-zw/unlighthouse/compare/v0.17.5...v0.17.6)
- 6 months agov 0.17.**5**###    🐞 Bug Fixes
  - Automatically disable sandbox when running as root  -  by @harlan-zw [`(75b42)`](https://github.com/harlan-zw/unlighthouse/commit/75b42ac)
  - Always respect --config-file  -  by @harlan-zw [`(dfa39)`](https://github.com/harlan-zw/unlighthouse/commit/dfa39f4) #####      [**~~View changes on GitHub~~**](https://github.com/harlan-zw/unlighthouse/compare/v0.17.4...v0.17.5)
- 11 months agov 0.17.**4**

  *No significant changes*#####      [**~~View changes on GitHub~~**](https://github.com/harlan-zw/unlighthouse/compare/v0.17.3...v0.17.4)
- 11 months agov 0.17.**3**###    🐞 Bug Fixes
  - NPM Trusted Publishing  -  by @harlan-zw [`(30ad1)`](https://github.com/harlan-zw/unlighthouse/commit/30ad1a1) #####      [**~~View changes on GitHub~~**](https://github.com/harlan-zw/unlighthouse/compare/v0.17.2...v0.17.3)
- last yearv 0.17.**2**### Bug Fixes
  - broken `**/config**` subpath export ([**~~f9486bd~~**](https://github.com/harlan-zw/unlighthouse/commit/f9486bd)), closes [**~~#289~~**](https://github.com/harlan-zw/unlighthouse/issues/289)
  - normalize report paths for windows ([**~~55ab2e9~~**](https://github.com/harlan-zw/unlighthouse/commit/55ab2e9)), closes [**~~#286~~**](https://github.com/harlan-zw/unlighthouse/issues/286)
- last yearv 0.17.**1**### Bug Fixes
  - missing `**[@clack](https://github.com/clack)/prompts**` dependency ([**~~cf69aa2~~**](https://github.com/harlan-zw/unlighthouse/commit/cf69aa2))
- last yearv 0.**17.0**### Bug Fixes
  - "Duda" sites not scanning correctly ([**~~77ac0bf~~**](https://github.com/harlan-zw/unlighthouse/commit/77ac0bf)), closes [**~~#277~~**](https://github.com/harlan-zw/unlighthouse/issues/277)
  - avoid infinite requeuing on path failure ([**~~f6f14e3~~**](https://github.com/harlan-zw/unlighthouse/commit/f6f14e3)), closes [**~~#268~~**](https://github.com/harlan-zw/unlighthouse/issues/268)
  - avoid using over max CPU cores ([**~~e5115c4~~**](https://github.com/harlan-zw/unlighthouse/commit/e5115c4))
  - disable `**ignoreI18nPages**` when cross-origin default is set for `**/**` ([**~~718b73b~~**](https://github.com/harlan-zw/unlighthouse/commit/718b73b)), closes [**~~#272~~**](https://github.com/harlan-zw/unlighthouse/issues/272)
  - finish worker when all routes are ignored ([**~~4db4297~~**](https://github.com/harlan-zw/unlighthouse/commit/4db4297)), closes [**~~#272~~**](https://github.com/harlan-zw/unlighthouse/issues/272)
  - safer path resolving ([**~~b14ebc8~~**](https://github.com/harlan-zw/unlighthouse/commit/b14ebc8)), closes [**~~#274~~**](https://github.com/harlan-zw/unlighthouse/issues/274) ### Features
  - modern CLI progress ([**~~ce53d66~~**](https://github.com/harlan-zw/unlighthouse/commit/ce53d66))
  - UI clean up ([**~~f720131~~**](https://github.com/harlan-zw/unlighthouse/commit/f720131))
  - UI migration ([**~~#282~~**](https://github.com/harlan-zw/unlighthouse/issues/282)) ([**~~c1608af~~**](https://github.com/harlan-zw/unlighthouse/commit/c1608af))

Please check GitHub for releases further back.

---

- **Page:** Lighthouse CI GitHub Actions: Setup Guide &amp; Documentation · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/github-actions
- **Description:** Complete Lighthouse CI GitHub Actions documentation. Step-by-step YAML workflows, status checks, PR comments, and treosh/lighthouse-ci-action setup.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Lighthouse CI GitHub Actions: Setup Guide & Documentation**

Complete Lighthouse CI GitHub Actions documentation. Step-by-step YAML workflows, status checks, PR comments, and treosh/lighthouse-ci-action setup.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw) Published **Jan 24, 2025**

Run Lighthouse audits on every push and pull request using GitHub Actions. This guide covers basic setup through advanced configurations with status checks and PR comments.

**Requirements**: LHCI 0.15.x requires Node 18+. GitHub Actions Ubuntu runners include Chrome pre-installed at `**/usr/bin/google-chrome**`.

## Basic Workflow

Create `**.github/workflows/lighthouse.yml**`:

```yaml
name: Lighthouse CI
on: [push]

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 20 # Required for base branch comparison
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci && npm run build
      - run: npm install -g @lhci/cli@0.15.x
      - run: lhci autorun
```

**Critical**: Always set `**fetch-depth: 20**` or higher. [**~~Shallow clones break LHCI's ancestor detection~~**](https://github.com/GoogleChrome/lighthouse-ci/blob/main/docs/troubleshooting.md) and cause "Could not find hash" errors.

Add `**lighthouserc.js**` to your repo root:

```js
export default {
  ci: {
    collect: {
      staticDistDir: './dist',
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
}
```

## Testing a Live URL

If your site is already deployed:

```js
const config2 = {
  ci: {
    collect: {
      url: ['https://example.com/', 'https://example.com/about'],
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
}
```

## Testing with a Local Server

For apps that need a running server:

```js
const config3 = {
  ci: {
    collect: {
      startServerCommand: 'npm run start',
      url: ['http://localhost:3000/'],
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
}
```

LHCI starts your server, waits for it to be ready, runs audits, then shuts it down.

## GitHub Status Checks

Add Lighthouse results as [**~~GitHub~~**](https://github.com) status checks on PRs.

### Option 1: GitHub App (Recommended)

1. Install the [**~~Lighthouse CI GitHub App~~**](https://github.com/apps/lighthouse-ci)
2. Authorize it for your repository
3. Copy the token from the authorization page
4. Add it as a repository secret named `**LHCI_GITHUB_APP_TOKEN**`

**Why GitHub App over PAT?**[**~~GitHub App tokens expire in 8 hours~~**](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/deciding-when-to-build-a-github-app) vs PATs which can be indefinite. Apps also use fine-grained permissions scoped to status checks only, making them more secure for public repos.

Update your workflow:

```yaml
name: Lighthouse CI
on: [push, pull_request]

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.sha }}
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci && npm run build
      - run: npm install -g @lhci/cli@0.15.x
      - run: lhci autorun
        env:
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}
```

The `**ref: ${{ github.event.pull_request.head.sha }}**` checks out the correct commit for PRs.

### Option 2: Personal Access Token

1. Create a [**~~personal access token~~**](https://github.com/settings/tokens/new) with `**repo:status**` scope
2. Add it as a secret named `**LHCI_GITHUB_TOKEN**`

```yaml
- run: lhci autorun
  env:
    LHCI_GITHUB_TOKEN: ${{ secrets.LHCI_GITHUB_TOKEN }}
```

## Adding Assertions

Fail the build if performance drops below thresholds:

```js
const config4 = {
  ci: {
    collect: {
      staticDistDir: './dist',
    },
    assert: {
      preset: 'lighthouse:recommended',
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
}
```

Or with custom thresholds:

```js
const config5 = {
  ci: {
    collect: {
      staticDistDir: './dist',
    },
    assert: {
      assertions: {
        'categories:performance': ['error', { minScore: 0.9 }],
        'categories:accessibility': ['error', { minScore: 0.9 }],
        'first-contentful-paint': ['warn', { maxNumericValue: 2000 }],
      },
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
}
```

## Using treosh/lighthouse-ci-action

The community built the [**~~lighthouse-ci-action~~**](https://github.com/treosh/lighthouse-ci-action) (1.2k+ stars) in collaboration with the Lighthouse team to simplify the workflow:

```yaml
name: Lighthouse CI
on: [push]

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Lighthouse
        uses: treosh/lighthouse-ci-action@v12
        with:
          urls: |
            https://example.com/
            https://example.com/about
          budgetPath: ./budget.json
          uploadArtifacts: true
```

With assertions:

```yaml
- uses: treosh/lighthouse-ci-action@v12
  with:
    urls: https://example.com/
    configPath: ./lighthouserc.js
```

## Testing Preview Deploys

For [**~~Vercel~~**](https://vercel.com), [**~~Netlify~~**](https://netlify.com), or Cloudflare Pages preview deployments:

```yaml
name: Lighthouse on Preview
on: deployment_status

jobs:
  lighthouse:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @lhci/cli@0.15.x
      - run: |
          lhci autorun \
            --collect.url=${{ github.event.deployment_status.target_url }} \
            --upload.target=temporary-public-storage
```

## Multiple URLs with Matrix

Test multiple pages in parallel:

```yaml
name: Lighthouse CI
on: [push]

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        url:
          - https://example.com/
          - https://example.com/pricing
          - https://example.com/docs
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @lhci/cli@0.15.x
      - run: |
          lhci autorun \
            --collect.url=${{ matrix.url }} \
            --upload.target=temporary-public-storage
```

## Uploading Reports as Artifacts

Save HTML reports for later review:

```yaml
- run: lhci autorun
- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: lighthouse-report
    path: .lighthouseci/
    retention-days: 14
```

## Running Multiple Times

Reduce variance by running multiple audits per URL:

```js
const config6 = {
  ci: {
    collect: {
      numberOfRuns: 5,
      url: ['https://example.com/'],
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
}
```

LHCI uses the median result for assertions. [**~~Google's research~~**](https://developers.google.com/web/tools/lighthouse/variability) shows the median of 5 runs is **twice as stable** as a single run. Even 3 runs [**~~reduces variance by 37%~~**](https://developers.google.com/web/tools/lighthouse/variability).

## Caching Chrome

Speed up workflows by caching Puppeteer's Chrome:

```yaml
- uses: actions/cache@v4
  with:
    path: ~/.cache/puppeteer
    key: ${{ runner.os }}-puppeteer-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-puppeteer-
```

## Token Security

The `**LHCI_TOKEN**` (build token for LHCI Server) is [**~~write-only and additive~~**](https://googlechrome.github.io/lighthouse-ci/docs/troubleshooting.html) - it cannot read or destroy historical data. This makes it safe to use in public repos as a secret without risk of data exfiltration.

## Full Production Workflow

Complete example with all features:

```yaml
name: Lighthouse CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 20 # Required for ancestor comparison

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - run: npm ci
      - run: npm run build

      - run: npm install -g @lhci/cli@0.15.x

      - run: lhci autorun
        env:
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: lighthouse-report
          path: .lighthouseci/
          retention-days: 14
```

With `**lighthouserc.js**`:

```js
const config7 = {
  ci: {
    collect: {
      staticDistDir: './dist',
      numberOfRuns: 3,
    },
    assert: {
      preset: 'lighthouse:recommended',
      assertions: {
        'categories:performance': ['error', { minScore: 0.8 }],
        'categories:accessibility': ['error', { minScore: 0.9 }],
      },
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
}
```

## Next Steps

- [**~~Configuration Reference~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/configuration) - All lighthouserc.js options
- [**~~Performance Budgets~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/budgets) - Set up assertions and budgets
- [**~~Troubleshooting~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/troubleshooting) - Fix common issues

## When Budgets Fail

If your assertions fail, use these guides to fix the basic issues:

- [**~~Fix LCP~~**](https://unlighthouse.dev/learn-lighthouse/lcp) - Largest Contentful Paint optimization
- [**~~Fix CLS~~**](https://unlighthouse.dev/learn-lighthouse/cls) - Cumulative Layout Shift fixes
- [**~~Fix INP~~**](https://unlighthouse.dev/learn-lighthouse/inp) - Interaction to Next Paint improvements
- [**~~Core Web Vitals Overview~~**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) - Understanding all metrics

[**Lighthouse CI** Complete guide to Lighthouse CI (@lhci/cli) from Google. Automate Lighthouse audits in CI/CD, enforce performance budgets, prevent regressions. Install, configure, GitHub Actions.](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci) [**GitLab CI** Configure Lighthouse CI for GitLab pipelines. Includes .gitlab-ci.yml examples, merge request integration, and artifact storage.](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/gitlab-ci)

**On this page **

- [Basic Workflow](#basic-workflow)
- [Testing a Live URL](#testing-a-live-url)
- [Testing with a Local Server](#testing-with-a-local-server)
- [GitHub Status Checks](#github-status-checks)
- [Adding Assertions](#adding-assertions)
- [Using treosh/lighthouse-ci-action](#using-treoshlighthouse-ci-action)
- [Testing Preview Deploys](#testing-preview-deploys)
- [Multiple URLs with Matrix](#multiple-urls-with-matrix)
- [Uploading Reports as Artifacts](#uploading-reports-as-artifacts)
- [Running Multiple Times](#running-multiple-times)
- [Caching Chrome](#caching-chrome)
- [Token Security](#token-security)
- [Full Production Workflow](#full-production-workflow)
- [Next Steps](#next-steps)
- [When Budgets Fail](#when-budgets-fail)

---

- **Page:** Lighthouse CI with GitLab CI&#x2F;CD: Setup Guide · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/gitlab-ci
- **Description:** Configure Lighthouse CI for GitLab pipelines. Includes .gitlab-ci.yml examples, merge request integration, and artifact storage.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Lighthouse CI with GitLab CI/CD: Setup Guide**

Configure Lighthouse CI for GitLab pipelines. Includes .gitlab-ci.yml examples, merge request integration, and artifact storage.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw) Published **Jan 24, 2025**

Lighthouse CI integrates smoothly with GitLab CI/CD to run performance audits on every merge request. This guide covers setup, configuration, and best practices for [**~~GitLab~~**](https://gitlab.com) pipelines.

## Quick Start

Basic `**.gitlab-ci.yml**` to audit a static site:

```yaml
lighthouse:
  image: cypress/browsers:node-22.12.0-chrome-131.0.6778.204-1-ff-134.0-edge-131.0.2903.112-1
  stage: test
  script:
    - npm install -g @lhci/cli@0.15.x
    - lhci autorun
  artifacts:
    when: always
    paths:
      - .lighthouseci/
    expire_in: 7 days
```

Create `**lighthouserc.js**`:

```js
export default {
  ci: {
    collect: {
      staticDistDir: './dist',
      chromePath: '/usr/bin/google-chrome',
      chromeFlags: '--no-sandbox'
    },
    upload: {
      target: 'temporary-public-storage'
    }
  }
}
```

## Why --no-sandbox?

GitLab CI runners require Chrome's `**--no-sandbox**` flag because [**~~Docker's default seccomp profile blocks the syscalls~~**](https://chromium.googlesource.com/chromium/src/+/0e94f26e8/docs/linux_sandboxing.md) Chrome needs to create its own namespace sandbox. The container itself provides isolation, creating a conflict.

Without it, Chrome fails to launch:

```text
Failed to launch Chrome: spawn EACCES
```

Always include `**chromeFlags: '--no-sandbox'**` in your configuration.

**Security note**: Only use `**--no-sandbox**` in trusted CI environments running your own code. If auditing untrusted websites, [**~~malicious pages could escape the container~~**](https://googlechrome.github.io/lighthouse-ci/docs/recipes/docker-client/). For maximum security, use [**~~Jess Frazelle's Chrome seccomp profile~~**](https://github.com/jessfraz/dotfiles/blob/main/etc/docker/seccomp/chrome.json) which allows only the specific syscalls Chrome needs.

## Testing Different Targets

### Static Build Output

Audit files in `**dist/**` or `**build/**`:

```yaml
lighthouse:
  image: cypress/browsers:node-22.12.0-chrome-131.0.6778.204-1-ff-134.0-edge-131.0.2903.112-1
  stage: test
  script:
    - npm ci
    - npm run build
    - npm install -g @lhci/cli@0.15.x
    - lhci autorun
  artifacts:
    paths:
      - .lighthouseci/
```

```js
// lighthouserc.js
const config2 = {
  ci: {
    collect: {
      staticDistDir: './dist',
      chromePath: '/usr/bin/google-chrome',
      chromeFlags: '--no-sandbox'
    }
  }
}
```

### Live URLs

Test production or staging URLs:

```js
const config3 = {
  ci: {
    collect: {
      url: [
        'https://example.com',
        'https://example.com/about',
        'https://example.com/products'
      ],
      chromePath: '/usr/bin/google-chrome',
      chromeFlags: '--no-sandbox'
    }
  }
}
```

### Local Development Server

Start server, run audits, shut down:

```js
const config4 = {
  ci: {
    collect: {
      startServerCommand: 'npm run serve',
      startServerReadyPattern: 'Server listening on',
      url: ['http://localhost:8080'],
      chromePath: '/usr/bin/google-chrome',
      chromeFlags: '--no-sandbox'
    }
  }
}
```

The CLI automatically kills the server after audits complete.

## Adding Assertions

Fail the pipeline if performance budgets aren't met:

```js
const config5 = {
  ci: {
    collect: {
      staticDistDir: './dist',
      chromePath: '/usr/bin/google-chrome',
      chromeFlags: '--no-sandbox'
    },
    assert: {
      assertions: {
        'categories:performance': ['error', { minScore: 0.9 }],
        'categories:accessibility': ['error', { minScore: 0.9 }],
        'categories:best-practices': ['error', { minScore: 0.9 }],
        'categories:seo': ['error', { minScore: 0.9 }],
        'first-contentful-paint': ['error', { maxNumericValue: 2000 }],
        'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
        'cumulative-layout-shift': ['error', { maxNumericValue: 0.1 }],
        'total-blocking-time': ['error', { maxNumericValue: 300 }]
      }
    },
    upload: {
      target: 'temporary-public-storage'
    }
  }
}
```

Pipeline fails if any assertion fails. See [**~~budgets~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/budgets) for assertion syntax.

## Storing Reports as Artifacts

Save HTML reports for download:

```yaml
lighthouse:
  image: cypress/browsers:node-22.12.0-chrome-131.0.6778.204-1-ff-134.0-edge-131.0.2903.112-1
  stage: test
  script:
    - npm install -g @lhci/cli@0.15.x
    - lhci autorun --upload.target=filesystem --upload.outputDir=./lhci-reports
  artifacts:
    when: always
    paths:
      - lhci-reports/
      - .lighthouseci/
    expire_in: 30 days
```

Reports appear in GitLab's merge request artifacts.

## Testing Review Apps

Audit ephemeral Review Apps using GitLab environment variables:

```yaml
lighthouse:
  image: cypress/browsers:node-22.12.0-chrome-131.0.6778.204-1-ff-134.0-edge-131.0.2903.112-1
  stage: test
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  script:
    - npm install -g @lhci/cli@0.15.x
    - lhci autorun --collect.url=$CI_ENVIRONMENT_URL
  environment:
    name: review/$CI_COMMIT_REF_NAME
    url: https://$CI_COMMIT_REF_SLUG.review.example.com
```

Or configure in `**lighthouserc.js**`:

```js
const config6 = {
  ci: {
    collect: {
      url: [process.env.CI_ENVIRONMENT_URL],
      chromePath: '/usr/bin/google-chrome',
      chromeFlags: '--no-sandbox'
    }
  }
}
```

## Reducing Variance with Multiple Runs

Run Lighthouse multiple times and use median values:

```js
const config7 = {
  ci: {
    collect: {
      numberOfRuns: 5,
      staticDistDir: './dist',
      chromePath: '/usr/bin/google-chrome',
      chromeFlags: '--no-sandbox'
    }
  }
}
```

Increases job duration but reduces false negatives from variance. [**~~Google's research~~**](https://developers.google.com/web/tools/lighthouse/variability) shows 5 runs is twice as stable as 1 run. GitLab runners are generally stable, so 3 runs ([**~~37% variance reduction~~**](https://github.com/GoogleChrome/lighthouse/blob/main/docs/variability.md)) is usually sufficient.

**Hardware requirements**: LHCI needs minimum [**~~2 cores and 4GB RAM~~**](https://googlechrome.github.io/lighthouse-ci/docs/troubleshooting.html). Avoid burstable instances (AWS t-series) as CPU throttling causes score inconsistency.

## Full Production Pipeline

Complete example with build, test, and artifact storage:

```yaml
stages:
  - build
  - test

variables:
  NODE_ENV: production

build:
  stage: build
  image: node:20
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour

lighthouse:
  stage: test
  image: cypress/browsers:node-22.12.0-chrome-131.0.6778.204-1-ff-134.0-edge-131.0.2903.112-1
  dependencies:
    - build
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == "main"'
  script:
    - npm install -g @lhci/cli@0.15.x
    - lhci autorun
  artifacts:
    when: always
    paths:
      - .lighthouseci/
      - lhci-reports/
    expire_in: 30 days
```

```js
// lighthouserc.js
const config8 = {
  ci: {
    collect: {
      staticDistDir: './dist',
      numberOfRuns: 3,
      chromePath: '/usr/bin/google-chrome',
      chromeFlags: '--no-sandbox'
    },
    assert: {
      preset: 'lighthouse:recommended',
      assertions: {
        'categories:performance': ['error', { minScore: 0.9 }],
        'uses-responsive-images': 'off',
        'offscreen-images': 'off'
      }
    },
    upload: {
      target: 'filesystem',
      outputDir: './lhci-reports'
    }
  }
}
```

## Lighthouse CI Server Integration

Upload to a persistent Lighthouse CI server for historical tracking:

```yaml
lighthouse:
  image: cypress/browsers:node-22.12.0-chrome-131.0.6778.204-1-ff-134.0-edge-131.0.2903.112-1
  stage: test
  script:
    - npm install -g @lhci/cli@0.15.x
    - lhci autorun --upload.serverBaseUrl=$LHCI_SERVER_URL --upload.token=$LHCI_BUILD_TOKEN
```

Set `**LHCI_SERVER_URL**` and `**LHCI_BUILD_TOKEN**` as CI/CD variables in GitLab project settings. See [**~~server setup~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/server) for details.

## Troubleshooting

### Chrome Won't Launch

**Error:**

```text
Failed to launch Chrome: spawn /usr/bin/google-chrome ENOENT
```

**Fix:** Use `**cypress/browsers**` image which includes Chrome, or install Chrome manually:

```yaml
script:
  - apt-get update
  - apt-get install -y wget gnupg
  - wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | gpg --dearmor -o /usr/share/keyrings/google-chrome.gpg
  - echo "deb [signed-by=/usr/share/keyrings/google-chrome.gpg] http://dl.google.com/linux/chrome/deb/ stable main" > /etc/apt/sources.list.d/google.list
  - apt-get update
  - apt-get install -y google-chrome-stable
  - npm install -g @lhci/cli@0.15.x
  - lhci autorun
```

### Sandbox Errors

**Error:**

```text
Failed to move to new namespace: PID namespaces supported, Network namespace supported, but failed: errno = Operation not permitted
```

**Fix:** Add `**--no-sandbox**` to chrome flags:

```js
chromeFlags: '--no-sandbox'
```

### Out of Memory

**Error:**

```text
FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory
```

**Fix:** Increase memory in `**.gitlab-ci.yml**`:

```yaml
variables:
  NODE_OPTIONS: --max-old-space-size=4096
```

Or reduce `**numberOfRuns**`:

```js
const config9 = {
  collect: {
    numberOfRuns: 1
  }
}
```

### Shared Memory Issues

**Error:**

```text
Browser tab has unexpectedly crashed
```

**Fix:** [**~~Docker's default 64MB /dev/shm~~**](https://bugs.chromium.org/p/chromium/issues/detail?id=715363) is insufficient for Chrome. Either use `**--disable-dev-shm-usage**` flag (writes to disk, slower) or increase shared memory:

```yaml
services:
  - name: docker:dind
    command: [--shm-size=2g]
```

### Job Timeout

GitLab default timeout is 1 hour. For `**numberOfRuns: 5**`, jobs may timeout. Reduce runs or increase timeout:

```yaml
lighthouse:
  timeout: 2 hours
```

### Reports Not Generated

Check that `**upload.target**` is set:

```js
const config10 = {
  upload: {
    target: 'filesystem',
    outputDir: './lhci-reports'
  }
}
```

And artifacts path matches:

```yaml
artifacts:
  paths:
    - lhci-reports/
```

## Next Steps

- [**~~Configuration reference~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/configuration) - All `**lighthouserc.js**` options
- [**~~Performance budgets~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/budgets) - Assertion syntax and examples
- [**~~LHCI Server~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/server) - Historical tracking and comparison
- [**~~Troubleshooting~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/troubleshooting) - Common issues and fixes

## When Budgets Fail

If your assertions fail, use these guides to fix the basic issues:

- [**~~Fix LCP~~**](https://unlighthouse.dev/learn-lighthouse/lcp) - Largest Contentful Paint optimization
- [**~~Fix CLS~~**](https://unlighthouse.dev/learn-lighthouse/cls) - Cumulative Layout Shift fixes
- [**~~Fix INP~~**](https://unlighthouse.dev/learn-lighthouse/inp) - Interaction to Next Paint improvements
- [**~~Core Web Vitals Overview~~**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) - Understanding all metrics

[**GitHub Actions** Complete Lighthouse CI GitHub Actions documentation. Step-by-step YAML workflows, status checks, PR comments, and treosh/lighthouse-ci-action setup.](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/github-actions) [**Configuration** Complete guide to lighthouserc.js configuration options. Covers collect, assert, upload, and server settings for @lhci/cli.](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/configuration)

**On this page **

- [Quick Start](#quick-start)
- [Why --no-sandbox?](#why-no-sandbox)
- [Testing Different Targets](#testing-different-targets)
- [Adding Assertions](#adding-assertions)
- [Storing Reports as Artifacts](#storing-reports-as-artifacts)
- [Testing Review Apps](#testing-review-apps)
- [Reducing Variance with Multiple Runs](#reducing-variance-with-multiple-runs)
- [Full Production Pipeline](#full-production-pipeline)
- [Lighthouse CI Server Integration](#lighthouse-ci-server-integration)
- [Troubleshooting](#troubleshooting)
- [Next Steps](#next-steps)
- [When Budgets Fail](#when-budgets-fail)

---

- **Page:** Lighthouse CI Configuration Reference · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/configuration
- **Description:** Complete guide to lighthouserc.js configuration options. Covers collect, assert, upload, and server settings for @lhci/cli.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Lighthouse CI Configuration Reference**

Complete guide to lighthouserc.js configuration options. Covers collect, assert, upload, and server settings for @lhci/cli.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw) Published **Jan 24, 2025**

Lighthouse CI uses configuration files to define how it collects audits, evaluates assertions, and uploads results.

## Configuration File Formats

Lighthouse CI supports multiple configuration file formats, checked in priority order:

1. `**.lighthouserc.js**` - JavaScript module (supports dynamic config)
2. `**lighthouserc.js**`
3. `**.lighthouserc.cjs**` - CommonJS explicit
4. `**lighthouserc.cjs**`
5. `**.lighthouserc.json**` - JSON format
6. `**lighthouserc.json**`
7. `**.lighthouserc.yml**` - YAML format
8. `**lighthouserc.yml**`
9. `**.lighthouserc.yaml**`
10. `**lighthouserc.yaml**`

### JavaScript Config

```js
// lighthouserc.js
export default {
  ci: {
    collect: {
      url: ['https://example.com/', 'https://example.com/about'],
      numberOfRuns: 3,
    },
    assert: {
      preset: 'lighthouse:recommended',
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
}
```

### JSON Config

```json
{
  "ci": {
    "collect": {
      "url": ["https://example.com/"],
      "numberOfRuns": 5
    },
    "assert": {
      "preset": "lighthouse:recommended"
    }
  }
}
```

### Using CLI Flag

Override the default config file location:

```bash
lhci autorun --config=custom-config.js
```

## Environment Variables

All configuration options can be set via environment variables using the `**LHCI_**` prefix and double underscores for nesting:

```bash
# Equivalent to ci.collect.numberOfRuns
LHCI_COLLECT__NUMBER_OF_RUNS=5

# Equivalent to ci.upload.serverBaseUrl
LHCI_UPLOAD__SERVER_BASE_URL=https://lhci.example.com

# Equivalent to ci.upload.token
LHCI_UPLOAD__TOKEN=your-secret-token
```

Environment variables override config file values.

## Collect Options

The `**collect**` configuration controls how Lighthouse audits are run.

### Basic Collection

```js
const config2 = {
  ci: {
    collect: {
      // URLs to audit (required)
      url: [
        'https://example.com/',
        'https://example.com/products',
        'https://example.com/about',
      ],

      // Number of times to audit each URL (default: 3)
      // 5 runs = 2x more stable than 1 run (Google research)
      // 3 runs = 37% variance reduction (DebugBear analysis)
      numberOfRuns: 5,

      // Lighthouse settings object
      settings: {
        preset: 'desktop',
        onlyCategories: ['performance', 'accessibility'],
      },
    },
  },
}
```

### Static Site Collection

For auditing static builds before deployment:

```js
const config3 = {
  ci: {
    collect: {
      // Path to built static files
      staticDistDir: './dist',

      // URLs to audit (relative to staticDistDir)
      url: [
        'http://localhost/index.html',
        'http://localhost/about/index.html',
      ],

      numberOfRuns: 3,
    },
  },
}
```

### Server Command

Start a local server before collection:

```js
const config4 = {
  ci: {
    collect: {
      startServerCommand: 'npm run serve',
      startServerReadyPattern: 'Server listening on',
      startServerReadyTimeout: 10000, // ms

      url: ['http://localhost:8080/'],
      numberOfRuns: 3,
    },
  },
}
```

The server process is automatically killed after collection completes.

### Chrome Options

```js
const config5 = {
  ci: {
    collect: {
      // Path to Chrome executable
      chromePath: '/usr/bin/google-chrome',

      // Chrome launch flags
      chromeFlags: '--no-sandbox --disable-gpu',

      // Puppeteer script for authentication/setup
      puppeteerScript: './scripts/puppeteer-script.js',

      // Puppeteer launch options
      puppeteerLaunchOptions: {
        headless: true,
      },
    },
  },
}
```

### Puppeteer Script

For authenticated pages or complex setup:

```js
// scripts/puppeteer-script.js
export default async (browser, context) => {
  const page = await browser.newPage()
  await page.goto('https://example.com/login')
  await page.type('#username', 'user')
  await page.type('#password', 'pass')
  await page.click('#submit')
  await page.waitForNavigation()
}
```

### Advanced Settings

```js
const config6 = {
  ci: {
    collect: {
      // Disable headless mode for debugging
      headful: false,

      // Preserve previous collection data instead of replacing
      additive: false,

      // Maximum wait time for page load
      maxWaitForLoad: 45000, // ms

      // Lighthouse settings override
      // Note: simulated throttling (default) provides lowest variance
      // See: https://github.com/GoogleChrome/lighthouse/blob/main/docs/throttling.md
      settings: {
        throttling: {
          rttMs: 40,
          throughputKbps: 10240,
          cpuSlowdownMultiplier: 1,
        },
        screenEmulation: {
          mobile: false,
          width: 1350,
          height: 940,
          deviceScaleFactor: 1,
        },
      },
    },
  },
}
```

## Assert Options

The `**assert**` configuration defines performance budgets and quality gates.

### Presets

Three built-in presets provide baseline assertions:

```js
const config7 = {
  ci: {
    assert: {
      // All Lighthouse audits must pass
      preset: 'lighthouse:all',

      // OR recommended audits only
      // preset: 'lighthouse:recommended',

      // OR recommended excluding PWA audits
      // preset: 'lighthouse:no-pwa',
    },
  },
}
```

### Custom Assertions

Override preset or define custom assertions:

```js
const config8 = {
  ci: {
    assert: {
      preset: 'lighthouse:recommended',
      assertions: {
        // Category scores (0-1)
        'categories:performance': ['error', { minScore: 0.9 }],
        'categories:accessibility': ['warn', { minScore: 0.95 }],
        'categories:seo': ['error', { minScore: 1 }],

        // Specific audit scores
        'first-contentful-paint': ['error', { maxNumericValue: 2000 }],
        'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
        'cumulative-layout-shift': ['error', { maxNumericValue: 0.1 }],
        'total-blocking-time': ['error', { maxNumericValue: 300 }],

        // Resource budgets
        'resource-summary:script:size': ['error', { maxNumericValue: 300000 }],
        'resource-summary:image:size': ['error', { maxNumericValue: 500000 }],
        'resource-summary:document:size': ['error', { maxNumericValue: 50000 }],

        // Pass/fail audits
        'uses-http2': 'error',
        'uses-long-cache-ttl': 'warn',
        'offscreen-images': 'off',
      },
    },
  },
}
```

**Category assertions** cover different audit groups: [**~~Performance~~**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) evaluates speed metrics, [**~~Accessibility~~**](https://unlighthouse.dev/learn-lighthouse/accessibility) checks usability standards, [**~~SEO~~**](https://unlighthouse.dev/learn-lighthouse/seo) validates search optimization, and [**~~Best Practices~~**](https://unlighthouse.dev/learn-lighthouse/best-practices) validates modern web standards.

**Core Web Vitals assertions** target key user experience metrics. When these fail, see metric-specific guides: [**~~LCP~~**](https://unlighthouse.dev/learn-lighthouse/lcp), [**~~CLS~~**](https://unlighthouse.dev/learn-lighthouse/cls), [**~~INP~~**](https://unlighthouse.dev/learn-lighthouse/inp).

### Assertion Levels

- `**'error'**` - Fails the build
- `**'warn'**` - Logs warning but doesn't fail
- `**'off'**` - Disables the assertion

### Aggregation Methods

Choose how Lighthouse CI combines multiple runs:

```js
const config9 = {
  ci: {
    assert: {
      // How to aggregate multiple runs
      // 'optimistic' (default), 'median', 'pessimistic', 'median-run'
      aggregationMethod: 'median',

      assertions: {
        'first-contentful-paint': ['error', {
          maxNumericValue: 2000,
          aggregationMethod: 'pessimistic', // Override for this audit
        }],
      },
    },
  },
}
```

- `**median**` - Middle value across runs (recommended for stability)
- `**optimistic**` - Best value across runs (preset default)
- `**pessimistic**` - Worst value across runs (strictest)
- `**median-run**` - All values from the median run

**Why median?** Since the performance score is already a weighted average, taking the mean of scores compounds outlier effects. [**~~Lighthouse CI calculates median~~**](https://github.com/GoogleChrome/lighthouse/blob/main/core/lib/median-run.js) by finding the run closest to median FCP **and** median TTI (earliest + latest page lifecycle moments), not just the score.

**Never run concurrent Lighthouse audits** on the same machine. [**~~Concurrent runs skew results~~**](https://github.com/GoogleChrome/lighthouse/blob/main/docs/variability.md) due to resource contention.

### Assertion Syntax

```js
const config10 = {
  assertions: {
    // Boolean pass/fail
    'audit-id': 'error',

    // Score threshold
    // 'audit-id': ['error', { minScore: 0.9 }],

    // Numeric threshold
    // 'audit-id': ['warn', { maxNumericValue: 1000 }],

    // Both score and numeric
    // 'audit-id': ['error', {
    //   minScore: 0.8,
    //   maxNumericValue: 2000,
    // }],

    // Custom aggregation
    // 'audit-id': ['error', {
    //   maxNumericValue: 2000,
    //   aggregationMethod: 'pessimistic',
    // }],
  }
}
```

For detailed budget examples, see [**~~Performance Budgets~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/budgets).

## Upload Options

The `**upload**` configuration controls where Lighthouse CI stores audit results.

### Temporary Public Storage

Free temporary storage hosted by Google (7 days retention):

```js
const config11 = {
  ci: {
    upload: {
      target: 'temporary-public-storage',
    },
  },
}
```

Returns a public URL to view results.

### LHCI Server

Upload to your own Lighthouse CI server:

```js
const config12 = {
  ci: {
    upload: {
      target: 'lhci',
      serverBaseUrl: 'https://lhci.example.com',
      token: process.env.LHCI_TOKEN, // Build token from server

      // Optional: ignore status code failures
      ignoreDuplicateBuildFailure: true,
    },
  },
}
```

See [**~~LHCI Server Setup~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/server) for server configuration.

### Filesystem

Save results to local files:

```js
const config13 = {
  ci: {
    upload: {
      target: 'filesystem',
      outputDir: './lhci-reports',

      // Optional: report formats
      reportFilenamePattern: '%%PATHNAME%%-%%DATETIME%%-report.%%EXTENSION%%',
    },
  },
}
```

### Multiple Targets

Upload to multiple destinations:

```js
const config14 = {
  ci: {
    upload: {
      target: ['lhci', 'filesystem'],
      serverBaseUrl: 'https://lhci.example.com',
      token: process.env.LHCI_TOKEN,
      outputDir: './lhci-reports',
    },
  },
}
```

## Server Options

Configuration for running your own LHCI server.

### Basic Server

```js
const config15 = {
  ci: {
    server: {
      port: 9001,
      storage: {
        sqlDialect: 'SQLite',
        sqlDatabasePath: './lhci.db',
      },
    },
  },
}
```

### PostgreSQL Storage

```js
const config16 = {
  ci: {
    server: {
      port: 9001,
      storage: {
        sqlDialect: 'postgres',
        sqlConnectionUrl: 'postgresql://user:pass@localhost:5432/lhci',

        // Optional: SSL configuration
        sqlConnectionSsl: true,
        sqlDialectOptions: {
          ssl: {
            rejectUnauthorized: false,
          },
        },
      },
    },
  },
}
```

### MySQL Storage

```js
const config17 = {
  ci: {
    server: {
      port: 9001,
      storage: {
        sqlDialect: 'MySQL',
        sqlConnectionUrl: 'mysql://user:pass@localhost:3306/lhci',
      },
    },
  },
}
```

### Basic Authentication

```js
const config18 = {
  ci: {
    server: {
      port: 9001,
      basicAuth: {
        username: 'admin',
        password: process.env.LHCI_ADMIN_PASSWORD,
      },
      storage: {
        sqlDialect: 'SQLite',
        sqlDatabasePath: './lhci.db',
      },
    },
  },
}
```

## Build Context

Lighthouse CI can automatically detect CI environment information. Override or supplement with environment variables:

```bash
# Git branch
LHCI_BUILD_CONTEXT__CURRENT_BRANCH=main

# Commit hash
LHCI_BUILD_CONTEXT__COMMIT_SHA=abc123

# Commit message
LHCI_BUILD_CONTEXT__COMMIT_MESSAGE="feat: add new feature"

# Author information
LHCI_BUILD_CONTEXT__AUTHOR=user@example.com

# Avatar URL
LHCI_BUILD_CONTEXT__AVATAR_URL=https://github.com/user.png

# PR or build number
LHCI_BUILD_CONTEXT__EXTERNAL_BUILD_URL=https://github.com/org/repo/pull/123

# GitHub repository slug
LHCI_BUILD_CONTEXT__GITHUB_REPO_SLUG=org/repo
```

Auto-detected in:

- GitHub Actions
- Travis CI
- CircleCI
- GitLab CI
- Jenkins
- AppVeyor
- Azure Pipelines

## Configuration Examples

### Single Page App

```js
const config19 = {
  ci: {
    collect: {
      staticDistDir: './build',
      URL: ['http://localhost/index.html'],
      numberOfRuns: 5,
    },
    assert: {
      preset: 'lighthouse:no-pwa',
      assertions: {
        'categories:performance': ['error', { minScore: 0.9 }],
        'first-contentful-paint': ['error', { maxNumericValue: 2000 }],
        'speed-index': ['error', { maxNumericValue: 3000 }],
      },
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
}
```

These assertions measure initial load speed. For optimization strategies, see the [**~~FCP~~**](https://unlighthouse.dev/glossary/fcp) and [**~~Speed Index~~**](https://unlighthouse.dev/glossary/speed-index) definitions.

### Multi-Page Site

```js
const config20 = {
  ci: {
    collect: {
      startServerCommand: 'npm run serve',
      URL: [
        'http://localhost:8080/',
        'http://localhost:8080/products',
        'http://localhost:8080/about',
        'http://localhost:8080/contact',
      ],
      numberOfRuns: 3,
      settings: {
        preset: 'desktop',
      },
    },
    assert: {
      preset: 'lighthouse:recommended',
      assertions: {
        'categories:performance': ['warn', { minScore: 0.85 }],
        'categories:accessibility': ['error', { minScore: 0.95 }],
        'categories:SEO': ['error', { minScore: 1 }],
      },
    },
    upload: {
      target: 'lhci',
      serverBaseUrl: process.env.LHCI_SERVER_URL,
      token: process.env.LHCI_TOKEN,
    },
  },
}
```

### Production Site Monitoring

```js
const config21 = {
  ci: {
    collect: {
      URL: ['https://example.com/'],
      numberOfRuns: 5,
      settings: {
        preset: 'desktop',
        throttling: {
          rttMs: 40,
          throughputKbps: 10240,
          cpuSlowdownMultiplier: 1,
        },
      },
    },
    assert: {
      assertions: {
        'categories:performance': ['error', { minScore: 0.95 }],
        'first-contentful-paint': ['error', { maxNumericValue: 1500 }],
        'largest-contentful-paint': ['error', { maxNumericValue: 2000 }],
        'cumulative-layout-shift': ['error', { maxNumericValue: 0.05 }],
        'total-blocking-time': ['error', { maxNumericValue: 200 }],
      },
      aggregationMethod: 'pessimistic',
    },
    upload: {
      target: ['lhci', 'filesystem'],
      serverBaseUrl: process.env.LHCI_SERVER_URL,
      token: process.env.LHCI_TOKEN,
      outputDir: './reports',
    },
  },
}
```

Strict production budgets require optimization across all [**~~Core Web Vitals~~**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals). Target values: [**~~LCP~~**](https://unlighthouse.dev/learn-lighthouse/lcp) under 2.5s, [**~~CLS~~**](https://unlighthouse.dev/learn-lighthouse/cls) under 0.1, [**~~TBT~~**](https://unlighthouse.dev/glossary/tbt) under 200ms.

### Authenticated Pages

```js
// lighthouserc.js
const config22 = {
  ci: {
    collect: {
      URL: [
        'http://localhost:3000/dashboard',
        'http://localhost:3000/profile',
      ],
      startServerCommand: 'npm start',
      puppeteerScript: './scripts/login.js',
      numberOfRuns: 3,
    },
    assert: {
      preset: 'lighthouse:recommended',
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
}
```

```js
// scripts/login.js
export default async (browser, context) => {
  const page = await browser.newPage()
  await page.goto('http://localhost:3000/login')
  await page.type('#email', 'test@example.com')
  await page.type('#password', 'password123')
  await page.click('button[type="submit"]')
  await page.waitForNavigation()
}
```

## CI Integration

### GitHub Actions

```yaml
- name: Run Lighthouse CI
  run: |
    [npm](https://npmjs.com) install -g @lhci/cli
    lhci autorun
  env:
    LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}
    LHCI_TOKEN: ${{ secrets.LHCI_TOKEN }}
```

See [**~~GitHub Actions Integration~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/github-actions).

### GitLab CI

```yaml
lighthouse:
  script:
    - npm install -g @lhci/cli
    - lhci autorun
  variables:
    LHCI_TOKEN: $LHCI_TOKEN
```

See [**~~GitLab CI Integration~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/gitlab-ci).

## Next Steps

- [**~~Performance Budgets~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/budgets) - Deep look at assertion strategies
- [**~~LHCI Server Setup~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/server) - Self-host result storage
- [**~~GitHub Actions~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/github-actions) - CI/CD integration
- [**~~GitLab CI~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/gitlab-ci) - [**~~GitLab~~**](https://gitlab.com) integration

[**GitLab CI** Configure Lighthouse CI for GitLab pipelines. Includes .gitlab-ci.yml examples, merge request integration, and artifact storage.](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/gitlab-ci) [**Performance Budgets** Set and enforce performance budgets with Lighthouse CI. Configure assertions, presets, custom thresholds, and budget.json to prevent regressions in CI/CD.](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/budgets)

**On this page **

- [Configuration File Formats](#configuration-file-formats)
- [Environment Variables](#environment-variables)
- [Collect Options](#collect-options)
- [Assert Options](#assert-options)
- [Upload Options](#upload-options)
- [Server Options](#server-options)
- [Build Context](#build-context)
- [Configuration Examples](#configuration-examples)
- [CI Integration](#ci-integration)
- [Next Steps](#next-steps)

---

- **Page:** LHCI Server: Self-Host Lighthouse CI Dashboard · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/server
- **Description:** Deploy your own Lighthouse CI server for historical tracking, build comparisons, and team dashboards. Covers Docker, Heroku, and database setup.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **LHCI Server: Self-Host Lighthouse CI Dashboard**

Deploy your own Lighthouse CI server for historical tracking, build comparisons, and team dashboards. Covers Docker, Heroku, and database setup.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw) Published **Jan 24, 2025**

LHCI Server provides a hosted dashboard for your Lighthouse CI results. While the CLI can run locally and output to the console, the server component gives you persistent historical data, trend analysis, and a web UI for comparing builds over time.

## What LHCI Server Provides

**Historical Tracking**

- Store Lighthouse reports across all builds
- Track performance trends over weeks and months
- Compare any two builds side-by-side
- View metric changes across deployments

**Team Dashboards**

- Centralized view of all projects
- Multiple projects per server instance
- Per-project build tokens for security
- Web UI accessible to entire team

**Build Comparison**

- Visual diff between baseline and current build
- Identify regressions before they ship
- Track improvement over time
- Export comparison data

## Requirements

**Runtime**

- [**~~Node.js~~**](https://nodejs.org) 18+ (20+ recommended)
- Database: [**~~SQLite~~**](https://sqlite.org), [**~~MySQL~~**](https://mysql.com), or [**~~PostgreSQL~~**](https://www.postgresql.org/)
- 512MB RAM minimum (1GB+ recommended)
- Storage scales with report retention

**Network**

- HTTP server accessible to CI runners
- Optional: reverse proxy for HTTPS
- Optional: basic auth for protection

## Local Deployment

Quickest way to test LHCI Server locally.

**Using npx**

```bash
# SQLite database (easiest for testing)
npx @lhci/server --storage.sqlDatabasePath=./lhci.db

# Custom port
npx @lhci/server --port=9001 --storage.sqlDatabasePath=./lhci.db
```

**Using npm**

```bash
# Install globally
npm install -g @lhci/server

# Run with SQLite
lhci server --storage.sqlDatabasePath=./lhci.db

# Run with MySQL
lhci server \
  --storage.sqlDialect=mysql \
  --storage.sqlConnectionUrl=mysql://user:pass@localhost/lhci
```

Server runs on `**http://localhost:9001**` by default.

## Docker Deployment

Pre-built [**~~Docker~~**](https://docker.com) image makes deployment straightforward.

**Docker Run**

```bash
# SQLite (data persists in volume)
docker run -d \
 -p 9001:9001 \
 -v lhci-data:/data \
  --name lhci-server \
  patrickhulce/lhci-server

# With custom port
docker run -d \
 -p 8080:9001 \
 -v lhci-data:/data \
  --name lhci-server \
  patrickhulce/lhci-server
```

**Docker Compose**

```yaml
version: '3'
services:
  lhci-server:
    image: patrickhulce/lhci-server
    ports:
      - '9001:9001'
    volumes:
      - lhci-data:/data
    environment:
      - LHCI_STORAGE__SQL_DATABASE_PATH=/data/lhci.db
    restart: unless-stopped

volumes:
  lhci-data:
```

**With PostgreSQL**

```yaml
version: '3'
services:
  lhci-server:
    image: patrickhulce/lhci-server
    ports:
      - '9001:9001'
    environment:
      - LHCI_STORAGE__SQL_DIALECT=postgres
      - LHCI_STORAGE__SQL_CONNECTION_URL=postgres://lhci:password@postgres:5432/lhci
    depends_on:
      - postgres
    restart: unless-stopped

  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=lhci
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=lhci
    volumes:
      - postgres-data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  postgres-data:
```

## Heroku Deployment

Heroku provides managed hosting with automatic HTTPS. Note that Heroku discontinued its free tier in November 2022 - all deployments now require paid plans.

**One-Click Deploy**

Use the official Heroku button:

```text
https://heroku.com/deploy?template=https://github.com/GoogleChrome/lighthouse-ci/tree/main/docs/recipes/heroku-server
```

**Manual Deploy**

```bash
# Install Heroku CLI
npm install -g heroku

# Create app
heroku create your-lhci-server

# Add PostgreSQL (Essential tier, starts at $5/month)
heroku addons:create heroku-postgresql:essential-0

# Set buildpack
heroku buildpacks:set heroku/nodejs

# Deploy
git clone https://github.com/GoogleChrome/lighthouse-ci.git
cd lighthouse-ci
git subtree push --prefix packages/server heroku main

# Open dashboard
heroku open
```

Heroku automatically sets `**DATABASE_URL**` for [**~~PostgreSQL~~**](https://postgresql.org) connection.

## Database Configuration

LHCI Server supports three database backends.

**SQLite (Default)**

Best for single-server deployments, testing, and low traffic. [**~~Works well for small teams~~**](https://github.com/GoogleChrome/lighthouse-ci/blob/main/docs/server.md) but gets bigger and slower over time.

```bash
lhci server --storage.sqlDatabasePath=/data/lhci.db
```

Environment variable:

```bash
LHCI_STORAGE__SQL_DATABASE_PATH=/data/lhci.db
```

**SQLite limitations**: Not optimized for high write volumes. [**~~Azure storage file shares are incompatible with SQLite~~**](https://learn.microsoft.com/en-us/azure/app-service/configure-connect-to-azure-storage#best-practices) - use PostgreSQL for cloud deployments.

**MySQL**

Better for multi-server deployments and higher traffic.

```bash
lhci server \
  --storage.sqlDialect=mysql \
  --storage.sqlConnectionUrl=mysql://user:password@host:3306/lhci
```

Environment variables:

```bash
LHCI_STORAGE__SQL_DIALECT=mysql
LHCI_STORAGE__SQL_CONNECTION_URL=mysql://user:password@host:3306/lhci
```

**PostgreSQL**

Recommended for production deployments. [**~~Better query performance~~**](https://www.sqlite.org/whentouse.html) and handles concurrent writes from multiple CI pipelines.

```bash
lhci server \
  --storage.sqlDialect=postgres \
  --storage.sqlConnectionUrl=postgres://user:password@host:5432/lhci
```

Environment variables:

```bash
LHCI_STORAGE__SQL_DIALECT=postgres
LHCI_STORAGE__SQL_CONNECTION_URL=postgres://user:password@host:5432/lhci
```

Connection string format:

```text
postgres://username:password@hostname:port/database?ssl=true
```

## Creating Projects

Use the wizard to create projects and generate tokens.

**Interactive Wizard**

```bash
lhci wizard
```

Follow prompts:

1. Enter server URL (e.g., `**https://lhci.yourdomain.com**`)
2. Create new project or select existing
3. Project name (e.g., "Marketing Site")
4. Receive build token and admin token

**Output Example**

```text
Created project Marketing Site (id: abc123)!

Build Token: def456789...
Admin Token: ghi012345...

Use build token in your CI configuration:
LHCI_TOKEN=def456789...
```

**Manual Project Creation**

Via API after server is running:

```bash
curl -X POST https://lhci.yourdomain.com/v1/projects \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Marketing Site",
    "externalUrl": "https://marketing.example.com",
    "slug": "marketing-site"
  }'
```

Returns project ID and tokens in JSON response.

## Token Security Model

LHCI uses two types of tokens with different permissions.

**Build Token**

- Used by CI to upload Lighthouse reports
- Can only write data, cannot read
- Safe to use in CI environment variables
- One per project

Example in GitHub Actions:

```yaml
env:
  LHCI_TOKEN: ${{ secrets.LHCI_BUILD_TOKEN }}
```

**Admin Token**

- Full read/write access to project
- Can create/delete builds
- Manage project settings
- Keep secure, never commit

Use admin token sparingly:

```bash
# Delete old builds (use admin token)
curl -X DELETE https://lhci.yourdomain.com/v1/projects/abc123/builds/789 \
 -H "Authorization: Bearer $ADMIN_TOKEN"
```

Store tokens in:

- CI secrets (GitHub Secrets, GitLab Variables)
- Environment variables
- Secret management tools (Vault, AWS Secrets Manager)

Never hardcode tokens in `**lighthouserc.js**`.

## Configuring Upload Target

Point your CI configuration to your LHCI Server.

**lighthouserc.js**

```js
export default {
  ci: {
    collect: {
      url: ['http://localhost:3000'],
      numberOfRuns: 3
    },
    upload: {
      target: 'lhci',
      serverBaseUrl: 'https://lhci.yourdomain.com',
      token: process.env.LHCI_TOKEN // Build token from env
    },
    assert: {
      preset: 'lighthouse:recommended',
      assertions: {
        'categories:performance': ['error', { minScore: 0.9 }]
      }
    }
  }
}
```

**Upload Options**

```js
const config2 = {
  upload: {
    target: 'lhci',
    serverBaseUrl: 'https://lhci.yourdomain.com',
    token: process.env.LHCI_TOKEN,

    // Optional: GitHub App integration
    githubAppToken: process.env.LHCI_GITHUB_APP_TOKEN,

    // Optional: ignore HTTPS certificate errors (not recommended)
    ignoreDuplicateBuildFailure: true
  }
}
```

See [**~~configuration guide~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/configuration) for all upload options.

**Verify Upload**

After CI runs:

```bash
lhci upload \
  --serverBaseUrl=https://lhci.yourdomain.com \
  --token=$LHCI_TOKEN
```

Check logs for:

```text
Saving CI project Marketing Site (abc123)
Saved LHR to https://lhci.yourdomain.com (build: def456)
Done saving build results to Lighthouse CI
```

## Basic Auth Protection

Add basic authentication to protect your dashboard.

**Environment Variables**

```bash
LHCI_BASIC_AUTH__USERNAME=admin
LHCI_BASIC_AUTH__PASSWORD=secure-password-here
```

**Docker Compose**

```yaml
services:
  lhci-server:
    image: patrickhulce/lhci-server
    environment:
      - LHCI_BASIC_AUTH__USERNAME=admin
      - LHCI_BASIC_AUTH__PASSWORD=${LHCI_PASSWORD}
```

**CLI Arguments**

```bash
lhci server \
  --basicAuth.username=admin \
  --basicAuth.password=secure-password \
  --storage.sqlDatabasePath=./lhci.db
```

Basic auth applies to web UI only. API token authentication still works for uploads.

**Uploading with Basic Auth**

If your server has basic auth, CI uploads use token authentication and bypass basic auth automatically. No additional configuration needed.

## Reverse Proxy Setup

Run LHCI Server behind nginx or Caddy for HTTPS.

**Nginx**

```nginx
server {
  listen 443 ssl http2;
  server_name lhci.yourdomain.com;

  ssl_certificate /path/to/cert.pem;
  ssl_certificate_key /path/to/key.pem;

  location / {
    proxy_pass http://localhost:9001;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_cache_bypass $http_upgrade;
  }
}
```

**Caddy**

```text
lhci.yourdomain.com {
  reverse_proxy localhost:9001
}
```

Caddy handles HTTPS automatically with Let's Encrypt.

**Docker with Traefik**

```yaml
services:
  lhci-server:
    image: patrickhulce/lhci-server
    labels:
      - traefik.enable=true
      - traefik.http.routers.lhci.rule=Host(`lhci.yourdomain.com`)
      - traefik.http.routers.lhci.entrypoints=websecure
      - traefik.http.routers.lhci.tls.certresolver=letsencrypt
```

## Storage Considerations

LHCI Server storage grows with report retention.

**Storage Estimates**

Per build (3 runs):

- Raw Lighthouse reports: \~2-3 MB
- Screenshots: \~500 KB - 1 MB
- Metadata: \~50 KB

Example: 100 builds/month = \~300-400 MB/month

**Database Maintenance**

SQLite:

```bash
# Vacuum database to reclaim space
sqlite3 /data/lhci.db "VACUUM;"
```

PostgreSQL:

```sql
-- Vacuum and analyze
VACUUM ANALYZE;
```

**Manual Cleanup**

Delete old builds via API:

```bash
# List builds
curl https://lhci.yourdomain.com/v1/projects/abc123/builds \
 -H "Authorization: Bearer $ADMIN_TOKEN"

# Delete specific build
curl -X DELETE https://lhci.yourdomain.com/v1/projects/abc123/builds/789 \
 -H "Authorization: Bearer $ADMIN_TOKEN"
```

**Retention Policy**

Industry standard for performance monitoring: [**~~raw metrics for 30 days, aggregated data for 13 months~~**](https://docs.newrelic.com/docs/data-apis/manage-data/manage-data-retention/). Disk space is a [**~~common issue~~**](https://github.com/GoogleChrome/lighthouse-ci/issues/794) - plan for automated cleanup.

Set up automated cleanup with cron:

```bash
#!/bin/bash
# cleanup-old-builds.sh
# Delete builds older than 90 days

ADMIN_TOKEN="your-admin-token"
SERVER="https://lhci.yourdomain.com"
PROJECT_ID="abc123"
CUTOFF_DATE=$(date -d '90 days ago' +%s)

# Fetch builds and filter by date
curl "$SERVER/v1/projects/$PROJECT_ID/builds" \
 -H "Authorization: Bearer $ADMIN_TOKEN" | \
  jq -r ".[] | select(.createdAt < $CUTOFF_DATE) | .id" | \
  while read BUILD_ID; do
    curl -X DELETE "$SERVER/v1/projects/$PROJECT_ID/builds/$BUILD_ID" \
      -H "Authorization: Bearer $ADMIN_TOKEN"
    echo "Deleted build $BUILD_ID"
  done
```

Cron entry:

```text
0 2 * * 0 /path/to/cleanup-old-builds.sh
```

## Updating the Server

Keep LHCI Server up to date for bug fixes and features.

**Docker**

```bash
# Pull latest image
docker pull patrickhulce/lhci-server:latest

# Restart container
docker compose down
docker compose up -d
```

**npm/npx**

```bash
# Update global installation
npm update -g @lhci/server

# Or update in package.json
npm install @lhci/server@latest
```

**Heroku**

```bash
# Pull latest code
git pull origin main

# Deploy
git push heroku main
```

**Database Migrations**

LHCI Server handles schema migrations automatically on startup. Backup your database before major version upgrades:

```bash
# SQLite backup
cp /data/lhci.db /data/lhci.db.backup

# PostgreSQL backup
pg_dump lhci > lhci-backup.sql
```

## Production Checklist

Before deploying to production:

- Use PostgreSQL or MySQL (not SQLite for multi-server)
- Enable basic auth or place behind VPN
- Set up HTTPS via reverse proxy
- Configure database backups
- Store tokens in secrets manager
- Set up monitoring (uptime, disk space)
- Plan retention policy and cleanup automation
- Document server URL and project IDs for team
- Test upload from CI environment
- Configure GitHub App integration (optional)

## Common Deployment Issues

**Database Connection Fails**

Check connection string format:

```bash
# Wrong
postgres://localhost/lhci

# Right
postgres://username:password@localhost:5432/lhci
```

**Uploads Timeout**

Increase client timeout in `**lighthouserc.js**`:

```js
const config3 = {
  upload: {
    target: 'lhci',
    serverBaseUrl: 'https://lhci.yourdomain.com',
    token: process.env.LHCI_TOKEN,
    uploadUrlTimeout: 120000 // 2 minutes
  }
}
```

**Server Crashes on Start**

Check Node version (16+ required):

```bash
node --version
```

Verify database permissions and disk space.

**Port Already in Use**

Change port:

```bash
lhci server --port=9002
```

Or find and kill process on port 9001:

```bash
lsof -ti:9001 | xargs kill -9
```

## Next Steps

- [**~~Configuration guide~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/configuration) - Configure assertions and upload options
- [**~~Performance budgets~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/budgets) - Set thresholds for your metrics
- [**~~GitHub Actions integration~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/github-actions) - Set up CI/CD pipeline
- [**~~Troubleshooting~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/troubleshooting) - Debug common issues
- [**~~Core Web Vitals guide~~**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) - Understand the metrics you're tracking

## Resources

- [**~~LHCI Server GitHub~~**](https://github.com/GoogleChrome/lighthouse-ci/tree/main/packages/server)
- [**~~Official Docker Image~~**](https://hub.docker.com/r/patrickhulce/lhci-server)
- [**~~Server API Documentation~~**](https://github.com/GoogleChrome/lighthouse-ci/blob/main/docs/server.md)

[**Performance Budgets** Set and enforce performance budgets with Lighthouse CI. Configure assertions, presets, custom thresholds, and budget.json to prevent regressions in CI/CD.](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/budgets) [**Troubleshooting** Fix common Lighthouse CI issues: Chrome launch failures, score variance, shallow clone errors, upload problems, and more.](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/troubleshooting)

**On this page **

- [What LHCI Server Provides](#what-lhci-server-provides)
- [Requirements](#requirements)
- [Local Deployment](#local-deployment)
- [Docker Deployment](#docker-deployment)
- [Heroku Deployment](#heroku-deployment)
- [Database Configuration](#database-configuration)
- [Creating Projects](#creating-projects)
- [Token Security Model](#token-security-model)
- [Configuring Upload Target](#configuring-upload-target)
- [Basic Auth Protection](#basic-auth-protection)
- [Reverse Proxy Setup](#reverse-proxy-setup)
- [Storage Considerations](#storage-considerations)
- [Updating the Server](#updating-the-server)
- [Production Checklist](#production-checklist)
- [Common Deployment Issues](#common-deployment-issues)
- [Next Steps](#next-steps)
- [Resources](#resources)

---

- **Page:** Performance Budgets with Lighthouse CI: Assertions &amp; budget.json · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/budgets
- **Description:** Set and enforce performance budgets with Lighthouse CI. Configure assertions, presets, custom thresholds, and budget.json to prevent regressions in CI/CD.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Performance Budgets with Lighthouse CI: Assertions & budget.json**

Set and enforce performance budgets with Lighthouse CI. Configure assertions, presets, custom thresholds, and budget.json to prevent regressions in CI/CD.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw) Published **Jan 24, 2025**

Performance budgets enforce web performance standards in your CI pipeline. Lighthouse CI fails builds when metrics exceed thresholds, preventing performance regressions from reaching production.

## Why Performance Budgets Matter

Performance budgets translate business requirements into measurable technical constraints:

- **Prevent regressions**: Catch performance degradation before deployment
- **Objective standards**: Replace subjective "feels slow" with measurable thresholds
- **Team accountability**: Make performance a first-class concern alongside features
- **User experience**: Maintain fast load times as codebases grow

Without budgets, performance degrades incrementally. A 50KB script here, an unoptimized image there - each change seems minor, but compound effects destroy user experience.

### The Business Case

Research shows direct revenue impact from performance:

| **Finding** | **Source** |
| --- | --- |
| **0.1s improvement = 8.4% retail conversion increase** | [**~~Google's research on the business impact of Core Web Vitals~~**](https://web.dev/case-studies/vitals-business-impact) |
| **Every 100ms costs Amazon 1% in sales** | [**~~Cloudflare~~**](https://www.cloudflare.com/en-au/learning/performance/more/website-performance-conversion-rates/) |
| **BBC loses 10% of users per additional second** | [**~~Google Research~~**](https://web.dev/learn/performance/why-speed-matters) |
| **Bounce probability increases 90% as load goes 1s→5s** | [**~~Google Research~~**](https://web.dev/learn/performance/why-speed-matters) |
| **Good LCP = 61% conversion increase for Rakuten** | [**~~web.dev Case Study~~**](https://web.dev/case-studies/rakuten) |

### The Page Weight Problem

[**~~Page weight has grown significantly over the last decade~~**](https://almanac.httparchive.org/en/2024/page-weight) (484KB → 2.2MB average). The [**~~2024 Web Almanac~~**](https://almanac.httparchive.org/en/2024/page-weight) reports median page weight at 2,675 KB (+8% YoY) with median JavaScript at 558 KB on mobile.

[**~~Alex Russell's research~~**](https://almanac.httparchive.org/en/2024/performance) suggests a **365 KB JavaScript budget** for sub-3-second loads on typical mobile devices - yet the 75th percentile exceeds 650 KB. Before setting budgets, measure your current baseline with the [**~~Page Size Checker~~**](https://unlighthouse.dev/tools/page-size).

## Two Approaches to Budgets

Lighthouse CI supports two budget methods:

### 1. Assertions in lighthouserc.js

Define budgets directly in your Lighthouse CI configuration:

```js
// lighthouserc.js
export default {
  ci: {
    assert: {
      preset: 'lighthouse:recommended',
      assertions: {
        'categories:performance': ['error', { minScore: 0.9 }],
        'first-contentful-paint': ['warn', { maxNumericValue: 2000 }],
      }
    }
  }
}
```

Best for simple budgets integrated with CI configuration.

### 2. Separate budget.json

Use Lighthouse's native budget format:

```json
// budget.json
[
  {
    "path": "/*",
    "resourceSizes": [
      { "resourceType": "script", "budget": 300 },
      { "resourceType": "image", "budget": 500 }
    ],
    "timings": [
      { "metric": "interactive", "budget": 3000 }
    ]
  }
]
```

Reference it in lighthouserc.js:

```js
const config2 = {
  ci: {
    assert: {
      budgetsFile: './budget.json'
    }
  }
}
```

Best for complex budgets, especially multiple URL patterns or resource-level constraints.

## Assertion Presets

Lighthouse CI includes three presets based on common use cases.

### lighthouse:all

Strictest preset - every audit must pass:

```js
const config3 = {
  ci: {
    assert: {
      preset: 'lighthouse:all'
    }
  }
}
```

Enforces all 100+ Lighthouse audits. Extremely difficult to pass. Use for greenfield projects with aggressive performance goals.

### lighthouse:recommended

Balanced preset - focuses on critical metrics:

```js
const config4 = {
  ci: {
    assert: {
      preset: 'lighthouse:recommended'
    }
  }
}
```

Behavior:

- **Errors** when accessibility, best practices, or SEO audits fail (perfect scores required)
- **Warns** when performance metrics fall below a score of 90
- Covers critical audits without being overly strict on performance variance

Most common starting point. Reasonable for production sites.

### lighthouse:no-pwa

Recommended preset without PWA requirements:

```js
const config5 = {
  ci: {
    assert: {
      preset: 'lighthouse:no-pwa'
    }
  }
}
```

Same as `**lighthouse:recommended**` but excludes Progressive Web App audits. Use for standard websites that don't need PWA capabilities.

## Assertion Syntax

Lighthouse CI uses ESLint-style assertion levels.

### Assertion Levels

Three severity levels control build status:

```js
const config6 = {
  assertions: {
    'first-contentful-paint': 'off', // Ignore this audit
    'largest-contentful-paint': 'warn', // Log warning, don't fail build
    'cumulative-layout-shift': 'error' // Fail build if threshold exceeded
  }
}
```

- **off**: Skip assertion entirely
- **warn**: Report violations without failing build
- **error**: Fail build on violations (default for preset assertions)

### minScore vs maxNumericValue

Two threshold types handle different metric formats:

**minScore** for 0-1 scores (categories, some audits):

```js
const config7 = {
  assertions: {
    'categories:performance': ['error', { minScore: 0.9 }],
    'categories:accessibility': ['error', { minScore: 0.95 }],
    'categories:seo': ['warn', { minScore: 0.8 }]
  }
}
```

Score must meet or exceed threshold. 0.9 means 90/100 in Lighthouse reports.

**maxNumericValue** for millisecond/byte values:

```js
const config8 = {
  assertions: {
    'first-contentful-paint': ['error', { maxNumericValue: 1800 }],
    'speed-index': ['error', { maxNumericValue: 3000 }],
    'total-byte-weight': ['warn', { maxNumericValue: 1500000 }]
  }
}
```

Value must be at or below threshold. FCP example allows up to 1800ms.

## Aggregation Methods

Lighthouse CI runs multiple audits per URL. Aggregation determines which run's value to compare against budgets.

```js
const config9 = {
  ci: {
    assert: {
      assertions: { /* ... */ }
    },
    collect: {
      numberOfRuns: 5
    },
    upload: {
      target: 'temporary-public-storage'
    }
  }
}
```

Four aggregation strategies:

### optimistic (default)

Uses best (fastest) value from sorted runs. Presets like `**lighthouse:recommended**` use this by default.

### median

Uses middle value from sorted runs:

```js
const config10 = {
  assert: {
    assertMatrix: [{ matchingUrlPattern: '.*', assertions: { /* ... */ } }],
    // median is default, explicit:
    preset: 'lighthouse:recommended'
  }
}
```

Most stable - ignores outliers. Best for typical use when you want consistent results.

### pessimistic

Uses worst (slowest) run:

```js
const config11 = {
  assert: {
    assertions: {
      'largest-contentful-paint': ['error', {
        maxNumericValue: 2500,
        aggregationMethod: 'pessimistic'
      }]
    }
  }
}
```

Strictest - makes sure worst case meets budget. Good for critical paths.

### median-run

Uses all values from the median run (not per-metric median):

```js
const config12 = {
  assert: {
    assertions: {
      interactive: ['error', {
        maxNumericValue: 3500,
        aggregationMethod: 'median-run'
      }]
    }
  }
}
```

Checks that metric correlations are preserved. Use when metrics interrelate.

## Category Assertions

Category assertions set thresholds for Lighthouse's five main scores.

```js
const config13 = {
  assertions: {
    'categories:performance': ['error', { minScore: 0.9 }],
    'categories:accessibility': ['error', { minScore: 0.95 }],
    'categories:best-practices': ['error', { minScore: 0.9 }],
    'categories:seo': ['error', { minScore: 0.9 }],
    'categories:pwa': ['warn', { minScore: 0.5 }]
  }
}
```

Categories aggregate multiple audits. Performance category includes [**~~FCP~~**](https://unlighthouse.dev/glossary/fcp), [**~~LCP~~**](https://unlighthouse.dev/learn-lighthouse/lcp), [**~~TBT~~**](https://unlighthouse.dev/glossary/tbt), [**~~CLS~~**](https://unlighthouse.dev/learn-lighthouse/cls), and [**~~Speed Index~~**](https://unlighthouse.dev/glossary/speed-index).

Use categories for high-level budgets. Override with individual audit assertions for granular control.

## Individual Audit Assertions

Target specific Lighthouse audits for precise budgets.

### Core Web Vitals

```js
const config14 = {
  assertions: {
    'first-contentful-paint': ['error', { maxNumericValue: 1800 }],
    'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
    'cumulative-layout-shift': ['error', { maxNumericValue: 0.1 }],
    'total-blocking-time': ['error', { maxNumericValue: 200 }],
    'speed-index': ['error', { maxNumericValue: 3400 }]
  }
}
```

Align with Google's [**~~Core Web Vitals~~**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) thresholds for good user experience. See detailed guides for [**~~LCP~~**](https://unlighthouse.dev/learn-lighthouse/lcp), [**~~CLS~~**](https://unlighthouse.dev/learn-lighthouse/cls), and [**~~INP~~**](https://unlighthouse.dev/learn-lighthouse/inp) optimization.

**Lab scores ≠ field performance**: [**~~Analysis of real-world CrUX data~~**](https://web.dev/articles/lab-and-field-data-differences) found that a significant portion of pages scoring high in Lighthouse may still fail one or more Core Web Vitals thresholds in real-world conditions. Use [**~~RUM monitoring~~**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) alongside synthetic testing.

### Resource Metrics

```js
const config15 = {
  assertions: {
    'total-byte-weight': ['error', { maxNumericValue: 1600000 }], // 1.6MB
    'dom-size': ['warn', { maxNumericValue: 1500 }],
    'bootup-time': ['warn', { maxNumericValue: 3500 }],
    'mainthread-work-breakdown': ['warn', { maxNumericValue: 4000 }]
  }
}
```

Control page weight and computational cost. High [**~~total byte weight~~**](https://unlighthouse.dev/learn-lighthouse/lcp/total-byte-weight) directly impacts load performance.

### Resource Budgets by Type

```js
const config16 = {
  assertions: {
    'resource-summary:script:size': ['error', { maxNumericValue: 300000 }], // 300KB JS
    'resource-summary:stylesheet:size': ['error', { maxNumericValue: 100000 }], // 100KB CSS
    'resource-summary:image:size': ['warn', { maxNumericValue: 500000 }], // 500KB images
    'resource-summary:font:size': ['warn', { maxNumericValue: 100000 }], // 100KB fonts
    'resource-summary:total:size': ['error', { maxNumericValue: 1500000 }] // 1.5MB total
  }
}
```

Granular control over asset budgets. Prevents JavaScript bloat from [**~~unused JavaScript~~**](https://unlighthouse.dev/learn-lighthouse/lcp/unused-javascript) or [**~~unminified scripts~~**](https://unlighthouse.dev/learn-lighthouse/lcp/unminified-javascript).

**Recommended JS budget**: [**~~Alex Russell's performance inequality research~~**](https://almanac.httparchive.org/en/2024/performance) suggests 365 KB total JavaScript for sub-3-second loads on median mobile devices. The 300KB budget above is aggressive but achievable for content sites.

### Accessibility Audits

```js
const config17 = {
  assertions: {
    'color-contrast': 'error',
    'image-alt': 'error',
    'label': 'error',
    'link-name': 'error',
    'tabindex': 'warn'
  }
}
```

Binary pass/fail audits don't need thresholds. See the [**~~accessibility guide~~**](https://unlighthouse.dev/learn-lighthouse/accessibility) for complete audit details.

## budget.json Format

Lighthouse's native budget format supports per-path budgets.

### Basic Structure

```json
[
  {
    "path": "/*",
    "resourceSizes": [
      {
        "resourceType": "script",
        "budget": 300
      },
      {
        "resourceType": "stylesheet",
        "budget": 50
      },
      {
        "resourceType": "image",
        "budget": 500
      },
      {
        "resourceType": "font",
        "budget": 100
      },
      {
        "resourceType": "total",
        "budget": 1500
      }
    ],
    "timings": [
      {
        "metric": "first-contentful-paint",
        "budget": 2000
      },
      {
        "metric": "largest-contentful-paint",
        "budget": 2500
      },
      {
        "metric": "interactive",
        "budget": 3500
      },
      {
        "metric": "total-blocking-time",
        "budget": 200
      }
    ]
  }
]
```

### Resource Types

Available `**resourceType**` values:

- `**script**` - JavaScript bundles
- `**stylesheet**` - CSS files
- `**image**` - All image formats
- `**media**` - Video/audio
- `**font**` - Web fonts
- `**document**` - HTML documents
- `**other**` - Everything else
- `**third-party**` - External domain resources
- `**total**` - Combined size

### Timing Metrics

Available `**metric**` values:

- `**first-contentful-paint**`
- `**largest-contentful-paint**`
- `**interactive**`
- `**total-blocking-time**`
- `**cumulative-layout-shift**`
- `**max-potential-fid**`
- `**speed-index**`

### Multiple URL Budgets

Define different budgets per page type:

```json
[
  {
    "path": "/",
    "resourceSizes": [
      { "resourceType": "script", "budget": 400 },
      { "resourceType": "total", "budget": 2000 }
    ]
  },
  {
    "path": "/blog/*",
    "resourceSizes": [
      { "resourceType": "script", "budget": 200 },
      { "resourceType": "image", "budget": 800 }
    ]
  },
  {
    "path": "/app/*",
    "resourceSizes": [
      { "resourceType": "script", "budget": 600 },
      { "resourceType": "total", "budget": 1800 }
    ]
  }
]
```

Match patterns use glob syntax. First matching path applies.

### Using budget.json

Reference budget file in lighthouserc.js:

```js
const config18 = {
  ci: {
    assert: {
      budgetsFile: './budget.json'
    },
    collect: {
      url: [
        'http://localhost:3000/',
        'http://localhost:3000/blog/post-1',
        'http://localhost:3000/app/dashboard'
      ]
    }
  }
}
```

Budget.json takes precedence over assertion configuration.

## Combining Presets with Overrides

Start with preset, override specific assertions:

```js
const config19 = {
  ci: {
    assert: {
      preset: 'lighthouse:no-pwa',
      assertions: {
        // Relax performance requirement
        'categories:performance': ['warn', { minScore: 0.85 }],

        // Stricter Core Web Vitals
        'largest-contentful-paint': ['error', { maxNumericValue: 2000 }],
        'cumulative-layout-shift': ['error', { maxNumericValue: 0.05 }],

        // Resource budgets
        'resource-summary:script:size': ['error', { maxNumericValue: 350000 }],
        'resource-summary:total:size': ['error', { maxNumericValue: 1800000 }],

        // Disable problematic audits
        'uses-http2': 'off',
        'redirects': 'off'
      }
    }
  }
}
```

Presets provide baseline. Overrides customize for your application.

## Setting Realistic Budgets

Don't guess budgets. Base them on current performance:

### 1. Run Lighthouse CI Locally

```bash
lhci collect --url=http://localhost:3000
lhci assert --preset=lighthouse:recommended
```

Review failures to see current metric values.

### 2. Set Budgets Above Current

Add 10-20% buffer to current values:

```js
const config20 = {
  // Current FCP: 1600ms
  // Budget: 1600 * 1.15 = 1840ms
  'first-contentful-paint': ['error', { maxNumericValue: 1840 }]
}
```

Prevents immediate failures while preventing regressions.

### 3. Tighten Over Time

Gradually reduce budgets as performance improves:

```js
const config21 = {
  // Week 1
  'largest-contentful-paint': ['warn', { maxNumericValue: 3000 }]
}

const config22 = {
  // Week 4
  'largest-contentful-paint': ['warn', { maxNumericValue: 2500 }]
}

const config23 = {
  // Week 8
  'largest-contentful-paint': ['error', { maxNumericValue: 2500 }]
}
```

Move from warn to error as team adapts.

## Practical Examples

### Marketing Site

```js
const config24 = {
  ci: {
    assert: {
      preset: 'lighthouse:no-pwa',
      assertions: {
        'categories:performance': ['error', { minScore: 0.9 }],
        'categories:accessibility': ['error', { minScore: 0.95 }],
        'categories:seo': ['error', { minScore: 0.95 }],

        'first-contentful-paint': ['error', { maxNumericValue: 1500 }],
        'largest-contentful-paint': ['error', { maxNumericValue: 2000 }],
        'cumulative-layout-shift': ['error', { maxNumericValue: 0.05 }],

        'resource-summary:script:size': ['error', { maxNumericValue: 250000 }],
        'resource-summary:image:size': ['warn', { maxNumericValue: 600000 }]
      }
    }
  }
}
```

Priorities: [**~~SEO~~**](https://unlighthouse.dev/learn-lighthouse/seo), [**~~accessibility~~**](https://unlighthouse.dev/learn-lighthouse/accessibility), fast [**~~LCP~~**](https://unlighthouse.dev/learn-lighthouse/lcp) for conversions.

### SaaS Application

```js
const config25 = {
  ci: {
    assert: {
      preset: 'lighthouse:no-pwa',
      assertions: {
        'categories:performance': ['warn', { minScore: 0.8 }],
        'categories:accessibility': ['error', { minScore: 0.9 }],

        'interactive': ['error', { maxNumericValue: 3500 }],
        'total-blocking-time': ['error', { maxNumericValue: 300 }],

        'resource-summary:script:size': ['warn', { maxNumericValue: 500000 }],
        'bootup-time': ['warn', { maxNumericValue: 4000 }]
      }
    }
  }
}
```

Priorities: Interactivity, reasonable bundle size for complex UI.

### Content Site

```js
const config26 = {
  ci: {
    assert: {
      budgetsFile: './budget.json'
    }
  }
}
```

```json
[
  {
    "path": "/",
    "resourceSizes": [
      { "resourceType": "script", "budget": 200 },
      { "resourceType": "image", "budget": 400 },
      { "resourceType": "total", "budget": 1200 }
    ],
    "timings": [
      { "metric": "first-contentful-paint", "budget": 1500 },
      { "metric": "largest-contentful-paint", "budget": 2000 }
    ]
  },
  {
    "path": "/article/*",
    "resourceSizes": [
      { "resourceType": "script", "budget": 150 },
      { "resourceType": "image", "budget": 800 },
      { "resourceType": "total", "budget": 1500 }
    ],
    "timings": [
      { "metric": "first-contentful-paint", "budget": 1200 },
      { "metric": "largest-contentful-paint", "budget": 1800 }
    ]
  }
]
```

Priorities: Fast content delivery, article images allowed, minimal JavaScript.

### E-commerce Site

```js
const config27 = {
  module: {
    exports: {
      ci: {
        assert: {
          preset: 'lighthouse:no-pwa',
          assertions: {
            'categories:performance': ['error', { minScore: 0.85 }],
            'categories:accessibility': ['error', { minScore: 0.9 }],

            'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
            'cumulative-layout-shift': ['error', { maxNumericValue: 0.1 }],
            'total-blocking-time': ['warn', { maxNumericValue: 350 }],

            'resource-summary:script:size': ['warn', { maxNumericValue: 400000 }],
            'resource-summary:image:size': ['error', { maxNumericValue: 1000000 }],
            'resource-summary:third-party:size': ['warn', { maxNumericValue: 300000 }]
          }
        }
      }
    }
  }
}
```

Priorities: [**~~LCP~~**](https://unlighthouse.dev/learn-lighthouse/lcp) (product images), [**~~CLS~~**](https://unlighthouse.dev/learn-lighthouse/cls) (prevent layout shifts during checkout), third-party control (analytics/ads).

## When Budgets Fail

Budget violations point to specific performance problems. These diagnostic guides help identify root causes and implement fixes:

**Core Web Vitals Failures**

- [**~~Largest Contentful Paint (LCP)~~**](https://unlighthouse.dev/learn-lighthouse/lcp) - Slow loading of main content
  - [**~~Total byte weight~~**](https://unlighthouse.dev/learn-lighthouse/lcp/total-byte-weight) - Excessive page resources
  - [**~~Unused JavaScript~~**](https://unlighthouse.dev/learn-lighthouse/lcp/unused-javascript) - Dead code bloating bundles
  - [**~~Unminified JavaScript~~**](https://unlighthouse.dev/learn-lighthouse/lcp/unminified-javascript) - Missing compression
- [**~~Cumulative Layout Shift (CLS)~~**](https://unlighthouse.dev/learn-lighthouse/cls) - Visual instability and layout shifts
- [**~~Interaction to Next Paint (INP)~~**](https://unlighthouse.dev/learn-lighthouse/inp) - Poor interactivity and responsiveness

**Category Score Failures**

- [**~~Accessibility~~**](https://unlighthouse.dev/learn-lighthouse/accessibility) - WCAG violations, missing labels, color contrast
- [**~~SEO~~**](https://unlighthouse.dev/learn-lighthouse/seo) - Meta tags, structured data, mobile usability
- [**~~Best Practices~~**](https://unlighthouse.dev/learn-lighthouse/best-practices) - Security, browser compatibility, console errors

**Resource Budget Failures**

- JavaScript size violations: Check [**~~unused JavaScript~~**](https://unlighthouse.dev/learn-lighthouse/lcp/unused-javascript) and [**~~unminified JavaScript~~**](https://unlighthouse.dev/learn-lighthouse/lcp/unminified-javascript)
- Total size violations: Review [**~~total byte weight~~**](https://unlighthouse.dev/learn-lighthouse/lcp/total-byte-weight) optimization strategies
- Image budgets: Optimize formats, implement responsive images, lazy loading

Start with [**~~Core Web Vitals~~**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) guide for prioritized optimization strategies.

## Next Steps

- [**~~Configuration~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/configuration) - Full lighthouserc.js options
- [**~~GitHub Actions~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/github-actions) - Automate budgets in CI
- [**~~GitLab CI~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/gitlab-ci) - GitLab CI integration tion

[**Configuration** Complete guide to lighthouserc.js configuration options. Covers collect, assert, upload, and server settings for @lhci/cli.](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/configuration) [**LHCI Server** Deploy your own Lighthouse CI server for historical tracking, build comparisons, and team dashboards. Covers Docker, Heroku, and database setup.](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/server)

**On this page **

- [Why Performance Budgets Matter](#why-performance-budgets-matter)
- [Two Approaches to Budgets](#two-approaches-to-budgets)
- [Assertion Presets](#assertion-presets)
- [Assertion Syntax](#assertion-syntax)
- [Aggregation Methods](#aggregation-methods)
- [Category Assertions](#category-assertions)
- [Individual Audit Assertions](#individual-audit-assertions)
- [budget.json Format](#budgetjson-format)
- [Combining Presets with Overrides](#combining-presets-with-overrides)
- [Setting Realistic Budgets](#setting-realistic-budgets)
- [Practical Examples](#practical-examples)
- [When Budgets Fail](#when-budgets-fail)
- [Next Steps](#next-steps)

---

- **Page:** LHCI vs Unlighthouse: Which Lighthouse CI Tool Should You Use? · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/lhci-vs-unlighthouse
- **Description:** Honest side-by-side comparison of @lhci/cli and Unlighthouse. Setup, URL discovery, budgets, reporting, and when each tool fits your workflow.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **LHCI vs Unlighthouse: Which Lighthouse CI Tool Should You Use?**

Honest side-by-side comparison of @lhci/cli and Unlighthouse. Setup, URL discovery, budgets, reporting, and when each tool fits your workflow.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)8 min read Published **Apr 13, 2026**

`**@lhci/cli**` (from Google) is best for tracking a known list of critical URLs over time with performance budgets and historical dashboards. Unlighthouse is best for auditing every page of a site at once via auto-discovery. The two tools solve different problems.

## The two tools

Google's official Lighthouse CI. You provide a list of URLs, it runs Lighthouse N times per URL, asserts against budgets, and uploads results to temporary storage, the filesystem, or an LHCI server. Around [**~~2.3M monthly npm downloads~~**](https://www.npmjs.com/package/@lhci/cli) in 2026 (following the Feb 2026 registry bot-filtering event).

```bash
npm install -g @lhci/cli
lhci autorun
```

## Side-by-side comparison

|  | **@lhci/cli** | **Unlighthouse** |
| --- | --- | --- |
| **Made by** | Google Chrome team | Harlan Wilton (OSS) |
| **Setup time** | 10-30 min (config file + budgets) | Under 1 min (zero config) |
| **URL discovery** | Manual list in `**lighthouserc.js**` | Auto-crawl via sitemap, robots.txt, links |
| **Default URLs tested** | Only what you specify | Every internal route found |
| **Performance budgets** | Yes, per URL, rich assertions | Yes, global score thresholds |
| **Architecture** | Sequential/Isolated for precision | **Smart Sampling** for site-wide speed |
| **Historical tracking** | Yes via @lhci/server | No built-in dashboard |
| **Local HTML UI** | Static report per URL | Interactive client, sortable, filterable |
| **CI integration** | First-party GitHub App, status checks | `**unlighthouse-ci**` command, JSON output |
| **PR comments** | Via GitHub App | Via third-party actions |
| **Variance reduction** | Runs N times, uses median | Configurable, defaults to 1 run |
| **Server/DB required** | Optional (LHCI server) | No |
| **npm downloads (monthly)** | \~2.3M | \~100k |
| **Best for** | Regression tracking on key URLs | Site-wide audits, catching outliers |

## When to use @lhci/cli

Pick LHCI when:

- You have a handful of critical URLs (homepage, checkout, product page) and want to track them over weeks or months.
- You need [**~~hard performance budgets enforced on every PR~~**](https://web.dev/articles/lighthouse-ci#budgets), with builds failing when thresholds break.
- You want to use **Lighthouse 13** diagnostics (requires LHCI v0.15+ and [**~~Node.js 22+~~**](https://nodejs.org/en/blog/release/v22.0.0)).
- You want a historical dashboard showing score trends, and you're willing to [**~~host @lhci/server~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/server) or use temporary public storage.
- You're already invested in the Google Chrome tooling ecosystem and want [**~~first-party GitHub App integration~~**](https://github.com/apps/lighthouse-ci).

LHCI's strength is depth on a narrow set of pages. It was designed for the workflow where a team picks 5 to 10 representative URLs, sets budgets, and watches for regressions commit by commit. In 2026, the roadmap focuses on [**~~SHA-pinning security~~**](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-third-party-actions) for all CI actions to prevent supply chain attacks.

## When to use Unlighthouse

Pick Unlighthouse when:

- You want to audit the entire site, not just a predefined list.
- You don't know which pages are slowest, and you want to find out.
- You need to audit 1,000+ pages; Unlighthouse's **Smart Sampling** identifies route patterns and only audits representative samples, making it [**~~10x faster than sequential testing~~**](https://unlighthouse.dev/guide/guides/dynamic-sampling).
- Setup speed matters; you want to go from install to results in under a minute.
- You need to spot patterns across routes, for example a shared layout causing [**~~CLS~~**](https://unlighthouse.dev/learn-lighthouse/cls) on 200 blog posts.
- You want an interactive UI for browsing per-page results, not static HTML reports.

Unlighthouse's strength is breadth. It finds problems you didn't know to look for. The homepage might score 95, while `**/pricing/enterprise**` scores 62 because a marketing tag manager ships 400KB of JavaScript that never hit the homepage.

## Running both in parallel

The tools complement each other. A common setup:

- **Every PR**: `**@lhci/cli**` runs on 5-10 critical URLs with strict budgets. Fast feedback, historical tracking via LHCI server.
- **Weekly scheduled job**: Unlighthouse scans the full site, posts a summary to Slack, flags any page scoring below 70.

```yaml
name: Lighthouse CI
on: [pull_request]
jobs:
  lhci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx @lhci/cli@latest autorun
```

## Summary

Pick `**@lhci/cli**` for deep regression tracking on a curated URL list with historical dashboards. Pick Unlighthouse for fast, site-wide audits that surface problems across every route. Run both if you want per-PR gates plus scheduled full-site coverage.

[Try Unlighthouse](https://unlighthouse.dev/)

### **Related **

[**Lighthouse CI Guide**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci) [**Unlighthouse CI Integration**](https://unlighthouse.dev/integrations/ci) [**Bulk Lighthouse Testing**](https://unlighthouse.dev/learn-lighthouse/bulk-lighthouse-testing) [**Bulk PageSpeed Test**](https://unlighthouse.dev/tools/bulk-pagespeed)

[**Redirects** Eliminate redirect chains that delay LCP. Learn to identify and fix 301/302 redirects, canonical URL issues, and trailing slash mismatches.](https://unlighthouse.dev/learn-lighthouse/lcp/redirects) [**Lighthouse CI** Complete guide to Lighthouse CI (@lhci/cli) from Google. Automate Lighthouse audits in CI/CD, enforce performance budgets, prevent regressions. Install, configure, GitHub Actions.](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci)

**On this page **

- [The two tools](#the-two-tools)
- [Side-by-side comparison](#side-by-side-comparison)
- [When to use @lhci/cli](#when-to-use-lhcicli)
- [When to use Unlighthouse](#when-to-use-unlighthouse)
- [Running both in parallel](#running-both-in-parallel)
- [Summary](#summary)

---

- **Page:** Lighthouse CI Troubleshooting Guide · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/troubleshooting
- **Description:** Fix common Lighthouse CI issues: Chrome launch failures, score variance, shallow clone errors, upload problems, and more.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Lighthouse CI Troubleshooting Guide**

Fix common Lighthouse CI issues: Chrome launch failures, score variance, shallow clone errors, upload problems, and more.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw) Published **Jan 24, 2025**

Common issues when running Lighthouse CI and how to fix them.

## Recommended Chrome Flags for CI

Most CI Chrome issues can be solved with this flag combination:

```js
settings: {
  chromeFlags: [
    '--no-sandbox', // Required in containers
    '--disable-setuid-sandbox', // Backup for setuid sandbox issues
    '--disable-dev-shm-usage', // Avoid /dev/shm size issues
    '--disable-gpu', // GPU not available in most CI
  ].join(' ')
}
```

## Chrome Launch Failures

### Chrome Not Found

**Problem:** `**Error: Unable to find Chrome**` or `**Chrome could not be found on the system**`

**Solution:** Install Chrome on your CI runner:

```bash
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y wget gnupg
wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
sudo sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list'
sudo apt-get update
sudo apt-get install -y google-chrome-stable

# Or use puppeteer's Chrome
npx @puppeteer/browsers install chrome@stable
```

For GitHub Actions, use the pre-installed Chrome:

```yaml
- name: Run Lighthouse CI
  run: npx lhci autorun
  env:
    CHROME_PATH: /usr/bin/google-chrome
```

### Protocol Error: X.Y wasn't found

**Problem:** `**Protocol error (X.Y): Z wasn't found**` or Chrome DevTools Protocol errors

**Solution:** Update to latest Lighthouse CI version (Chrome DevTools Protocol changes frequently):

```bash
npm install -D @lhci/cli@latest
```

If using an older Node version, you may need to upgrade [**~~Node.js~~**](https://nodejs.org) to match the Chrome version installed on your system.

### No usable sandbox

**Problem:** `**Failed to move to new namespace: PID namespaces supported, Network namespace supported, but failed: errno = Operation not permitted**` or `**No usable sandbox!**`

**Why this happens:** [**~~Chrome's sandbox~~**](https://chromium.googlesource.com/chromium/src/+/0e94f26e8/docs/linux_sandboxing.md) uses Linux user namespaces for isolation. Docker's default seccomp profile blocks these syscalls because the container already provides isolation - creating a conflict. On [**~~Ubuntu 24.04+, AppArmor restrictions~~**](https://ubuntu.com/blog/whats-new-in-security-for-ubuntu-24-04-lts) add another layer requiring explicit profiles.

**Solution:** Add `**--no-sandbox**` flag in CI environments without proper sandboxing:

```js
// lighthouserc.js
export default {
  ci: {
    collect: {
      chromePath: process.env.CHROME_PATH,
      settings: {
        chromeFlags: '--no-sandbox --disable-gpu'
      }
    }
  }
}
```

**Warning:** Only use `**--no-sandbox**` in trusted CI environments running your own code. If auditing untrusted sites, [**~~malicious pages could escape~~**](https://googlechrome.github.io/lighthouse-ci/docs/recipes/docker-client/). For maximum security, use [**~~Jess Frazelle's Chrome seccomp profile~~**](https://github.com/jessfraz/dotfiles/blob/main/etc/docker/seccomp/chrome.json).

### Browser Crashes in Docker (TARGET\_CRASHED)

**Problem:** `**Browser tab has unexpectedly crashed**` or `**TARGET_CRASHED**` errors in [**~~Docker~~**](https://docker.com)

**Why this happens:** [**~~Docker's default 64MB /dev/shm~~**](https://bugs.chromium.org/p/chromium/issues/detail?id=715363) is too small for Chrome's shared memory requirements when rendering large pages.

**Solution:** Chrome needs adequate shared memory. Add `**--disable-dev-shm-usage**` flag (writes to disk instead, slower):

```js
// lighthouserc.js
const config2 = {
  ci: {
    collect: {
      settings: {
        chromeFlags: '--no-sandbox --disable-dev-shm-usage --disable-gpu'
      }
    }
  }
}
```

Or mount a larger `**/dev/shm**` volume when running Docker (better performance):

```bash
docker run --shm-size=2g your-image
```

Docker Desktop with WSL2 has an [**~~additional issue~~**](https://github.com/SeleniumHQ/docker-selenium/issues/1309) where /dev/shm may lack execution permissions.

## Bot Detection and 403 Errors

**Problem:** `**403 Forbidden**` errors when auditing production sites with bot protection

**Why this happens:** Lighthouse's automated Chrome requests score 1-29 on [**~~Cloudflare's bot score~~**](https://developers.cloudflare.com/waf/custom-rules/use-cases/challenge-bad-bots/), triggering blocks. [**~~Bot Fight Mode specifically blocks Lighthouse~~**](https://community.cloudflare.com/t/bot-fight-mode-challenging-chrome-lighthouse/368829) and causes TBT to spike.

**Solution:** Sites with [**~~Cloudflare~~**](https://cloudflare.com), WAFs, or bot detection may block Lighthouse's requests.

Options:

1. **Disable Bot Fight Mode** (Cloudflare) - it's [**~~meant for active attacks only~~**](https://community.cloudflare.com/t/bot-fight-mode-challenging-chrome-lighthouse/368829)
2. **Test against origin**: bypass CDN for CI testing
3. **Whitelist CI runner IPs**: but be aware IPs change on shared runners
4. **Test staging environments** without bot protection enabled

[**~~Skip rules don't work for Super Bot Fight Mode~~**](https://community.cloudflare.com/t/turn-off-bot-detection-for-specific-url/565739). You must disable SBFM or test a different endpoint.

This cannot be fixed in Lighthouse CI configuration - it requires changes on the target site's security settings.

## Shallow Clone Issues

### Ancestor hash not found

**Problem:** `**Could not find hash XXXXXX**` or `**fatal: bad object**` when comparing branches

**Solution:** Increase fetch depth in GitHub Actions:

```yaml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0 # Full history (safest)
    # Or use minimum depth for faster checkout:
    # fetch-depth: 20
```

For GitLab CI:

```yaml
variables:
  GIT_DEPTH: 0
```

Lighthouse CI needs git history to compare against base branch commits. See [**~~GitHub Actions setup~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/github-actions) for complete configuration.

## Score Variance

### Inconsistent scores across runs

**Problem:** Performance scores vary by 5-15 points between identical runs

**Why this happens:** [**~~Google identifies 7 primary sources of variability~~**](https://developers.google.com/web/tools/lighthouse/variability):

| **Source** | **Impact** |
| --- | --- |
| Page nondeterminism (A/B tests, ads) | High |
| Local network variability | High |
| Client hardware variability | High |
| Client resource contention | High |
| Tier-1 network variability | Medium |
| Browser nondeterminism | Medium |
| Web server variability | Low |

**Solution:** Increase `**numberOfRuns**` and use consistent hardware:

```js
// lighthouserc.js
const config3 = {
  ci: {
    collect: {
      numberOfRuns: 5, // Run 5 times, take median
      settings: {
        onlyCategories: ['performance'],
        // Disable CPU throttling variance
        throttling: {
          cpuSlowdownMultiplier: 1
        }
      }
    },
    assert: {
      assertions: {
        // Use ranges for flaky metrics
        'first-contentful-paint': ['error', { maxNumericValue: 2000 }],
        'interactive': ['warn', { maxNumericValue: 5000 }]
      }
    }
  }
}
```

**Best practices to reduce variance:**

- Use dedicated CI runners (not shared)
- Minimum [**~~2 cores and 4GB RAM~~**](https://googlechrome.github.io/lighthouse-ci/docs/troubleshooting.html) - avoid burstable instances
- Use [**~~simulated throttling~~**](https://github.com/GoogleChrome/lighthouse/blob/master/docs/throttling.md) (default) for lowest variance
- [**~~5 runs is 2x more stable~~**](https://developers.google.com/web/tools/lighthouse/variability) than 1 run; 3 runs reduces variance by 37%
- Avoid testing on CI for precise performance measurements (consider real user monitoring instead)

Performance scores naturally vary ±5 points even on identical hardware. Focus on trends over time rather than individual runs.

**December 2024 change**: [**~~PageSpeed Insights changed CPU throttling from 4x to 1.2x~~**](https://developers.google.com/speed/docs/insights/release_notes) to better match production environments. If your PSI scores suddenly improved, this is why.

Understanding the metrics you're testing helps interpret variance. See guides for [**~~LCP~~**](https://unlighthouse.dev/learn-lighthouse/lcp), [**~~CLS~~**](https://unlighthouse.dev/learn-lighthouse/cls), and [**~~INP~~**](https://unlighthouse.dev/learn-lighthouse/inp).

## Upload Issues

### GitHub App not working on fork PRs

**Problem:** Status checks don't appear on pull requests from forks

**Solution:** This is a security limitation. Forks can't access repository secrets or GitHub Apps. Options:

1. **Require PR authors to create issues instead of PRs** (community contributions workflow)
2. **Use pull\_request\_target with caution:**

```yaml
on:
  pull_request_target: # Runs in base repo context

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      # DANGER: Only checkout base branch, never fork code
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.base_ref }}

      - name: Run Lighthouse CI
        run: npx lhci autorun
        env:
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}
```

**Warning:** `**pull_request_target**` runs with write access. Never checkout or execute fork code.

### Token security for public repos

**Problem:** Don't want to expose server token in public repo

**Solution:** Use GitHub Secrets and the Lighthouse CI GitHub App:

```yaml
env:
  LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}
```

Never hardcode tokens in `**lighthouserc.js**`. For public repos, the GitHub App is safer than `**upload.token**` because it scopes permissions to status checks only.

## URL Normalization

### Dynamic URLs with ports or UUIDs

**Problem:** Each CI run creates different URLs (localhost:34567, [**~~preview-abc123.app.com~~**](http://preview-abc123.app.com)) that can't be compared historically

**Solution:** Use `**--url-replacement-patterns**` to normalize URLs:

```bash
# Normalize port numbers
lhci collect --url-replacement-patterns='http://localhost:[0-9]+/=//'

# Normalize preview UUIDs
lhci collect --url-replacement-patterns='https://preview-[a-f0-9]+.app.com/=//'
```

Or in configuration:

```js
// lighthouserc.js
const config4 = {
  ci: {
    collect: {
      url: ['http://localhost:8080'],
      urlReplacementPatterns: [
        's/localhost:[0-9]+/localhost:PORT/g',
        's/preview-[a-f0-9]+/preview-UUID/g'
      ]
    }
  }
}
```

This makes sure historical data aggregates properly across different deployments.

## Lost Tokens

### Recovering Lost GitHub App Token

**Problem:** Lost GitHub App token after initial setup

**Solution:** Uninstall and reinstall the [**~~Lighthouse CI GitHub App~~**](https://github.com/apps/lighthouse-ci) on your repository to get a new token.

### Recovering Lost Build Token (LHCI Server)

**Problem:** Lost build token for uploading to your LHCI server

**Solution:** Reset the build token via wizard:

```bash
# Connect to your LHCI server and run:
lhci wizard --wizard=reset-build-token
```

Or create a new project via API if you have admin token:

```bash
curl -X POST https://your-lhci-server.com/v1/projects \
 -H "Authorization: Bearer $LHCI_ADMIN_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"name": "my-project", "externalUrl": "https://github.com/user/repo"}'
```

### Admin vs Build tokens

- **Admin token:** Full server access, manage projects. Keep secret, never commit.
- **Build token:** Upload-only for specific project. Safe in CI secrets.
- **GitHub App token:** Status check posting only. Safest for public repos.

## Configuration Issues

### lighthouserc.js not found

**Problem:** `**Could not find configuration file**`

**Solution**: Check that file is in project root and properly named:

```bash
# Must be one of these names
lighthouserc.js
lighthouserc.json
.lighthouserc.js
.lighthouserc.json

# Or specify explicitly
lhci autorun --config=./path/to/lighthouserc.js
```

### Invalid configuration format

**Problem:** `**Configuration parsing failed**` or `**Invalid config**`

**Solution:** Validate syntax. Configuration must export an object with `**ci**` key:

```js
// ✅ Correct
const config5 = {
  ci: {
    collect: { /* ... */ }
  }
}

// ❌ Wrong - missing 'ci' wrapper
const config6 = {
  collect: { /* ... */ }
}
```

See [**~~configuration reference~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/configuration) for complete schema.

## Memory and Timeout Issues

### Out of memory on large sites

**Problem:** `**JavaScript heap out of memory**` or CI runner killed

**Solution:** Increase Node memory and reduce concurrent audits:

```bash
# Increase Node memory
NODE_OPTIONS=--max-old-space-size=4096 lhci autorun
```

```js
// lighthouserc.js - reduce load
const config7 = {
  ci: {
    collect: {
      numberOfRuns: 3, // Reduce from 5
      url: [
        // Audit fewer pages
        'http://localhost:8080',
        'http://localhost:8080/about'
      ]
    }
  }
}
```

For large sites (50+ pages), consider:

- Split audits across multiple jobs
- Use more powerful CI runners
- Audit subset of critical pages only

### CI timeout on slow runners

**Problem:** CI job exceeds time limit (30min default on GitHub Actions)

**Solution:** Optimize collection or increase timeout:

```yaml
jobs:
  lighthouse:
    timeout-minutes: 60 # Default is 360 (6h), reduce for faster failure detection
```

```js
// lighthouserc.js - faster collection
const config8 = {
  ci: {
    collect: {
      numberOfRuns: 3, // Reduce runs
      settings: {
        onlyCategories: ['performance'], // Single category
        skipAudits: ['screenshot-thumbnails', 'final-screenshot'] // Skip slow audits
      }
    }
  }
}
```

## startServerCommand Issues

### Server not starting

**Problem:** `**startServerCommand**` runs but server never becomes available

**Solution:** Add explicit readiness check:

```js
// lighthouserc.js
const config9 = {
  ci: {
    collect: {
      startServerCommand: 'npm run serve',
      startServerReadyPattern: 'Local:.*http://localhost:8080', // Wait for this log
      startServerReadyTimeout: 30000, // 30s timeout
      url: ['http://localhost:8080']
    }
  }
}
```

Common patterns:

- [**~~Vite~~**](https://vite.dev): `**Local:.*http://localhost**`
- [**~~Next.js~~**](https://nextjs.org): `**ready on**`
- Express: `**listening on**`

### Wrong port

**Problem:** Server starts on random port, hardcoded URL fails

**Solution:** Force specific port in start command:

```bash
# package.json
{
  "scripts": {
    "serve": "vite preview --port 8080 --strictPort"
  }
}
```

Or set port via environment variable:

```js
// lighthouserc.js
const config10 = {
  ci: {
    collect: {
      startServerCommand: 'PORT=8080 npm run serve',
      startServerReadyPattern: 'http://localhost',
      url: ['http://localhost:8080']
    }
  }
}
```

## Assertion Failures

### Understanding error vs warn

Assertions can `**'error'**` (fail build) or `**'warn'**` (log only):

```js
// lighthouserc.js
const config11 = {
  ci: {
    assert: {
      assertions: {
        'categories:performance': ['error', { minScore: 0.9 }], // Fail if < 90
        'first-contentful-paint': ['warn', { maxNumericValue: 2000 }], // Log if > 2s

        // Use warn for flaky metrics
        'speed-index': ['warn', { maxNumericValue: 4000 }],

        // Use error for critical issues
        'errors-in-console': ['error', { maxLength: 0 }]
      }
    }
  }
}
```

### Setting realistic budgets

**Problem:** Assertions constantly fail, blocking PRs

**Solution:** Set budgets based on current performance, then gradually improve:

```bash
# Get baseline scores
lhci collect --url=http://localhost:8080
lhci assert --preset=lighthouse:no-pwa

# Set budgets 10% better than current
# If current performance score is 75, set minScore: 0.7
```

Start with `**preset: 'lighthouse:recommended'**` and relax failing assertions until stable, then tighten over time.

**Recommended approach:**

1. Start with warnings only
2. Collect 1 week of data
3. Set error thresholds at P90 (90th percentile)
4. Gradually lower thresholds

See [**~~GitHub Actions setup~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/github-actions) and [**~~GitLab CI setup~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/gitlab-ci) for working examples.

## Next Steps

Once your CI setup is working:

- **Understand what you're measuring:** [**~~Core Web Vitals overview~~**](https://unlighthouse.dev/learn-lighthouse/core-web-vitals) explains the performance metrics
- **Debug specific issues:** Use [**~~LCP Finder~~**](https://unlighthouse.dev/tools/lcp-finder), [**~~CLS Debugger~~**](https://unlighthouse.dev/tools/cls-debugger), or [**~~INP Analyzer~~**](https://unlighthouse.dev/tools/inp-analyzer) to diagnose failures
- **Fix the issues:** Look at [**~~LCP~~**](https://unlighthouse.dev/learn-lighthouse/lcp), [**~~CLS~~**](https://unlighthouse.dev/learn-lighthouse/cls), and [**~~INP~~**](https://unlighthouse.dev/learn-lighthouse/inp) optimization guides
- **Set realistic thresholds:** Use [**~~budgets~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/budgets) to define performance standards without blocking every PR

## PROTOCOL\_TIMEOUT Errors

**Problem:** Chrome hangs during audit with `**PROTOCOL_TIMEOUT**` error

**Solution:** This is a [**~~known unfixable issue~~**](https://github.com/GoogleChrome/lighthouse-ci/issues/428) - Chrome occasionally hangs and nothing can be done on the Lighthouse side. The only solution is to retry:

```js
// In CI, wrap with retry logic
// Or increase numberOfRuns and accept occasional failures
const config12 = {
  ci: {
    collect: {
      numberOfRuns: 5, // More runs = better chance of success
    }
  }
}
```

## Chrome Headless Mode Changes

**Problem:** Deprecation warnings about `**--headless**` or crashes with Chrome 132+

**Solution:** [**~~Chrome 132 removed ~~**`**--headless=old**`](https://developer.chrome.com/blog/removing-headless-old-from-chrome) from the main binary. LHCI 0.14+ uses `**headless: "new"**` by default. If you need old headless behavior, use the separate `**chrome-headless-shell**` binary.

## Still Having Issues?

- Check [**~~GoogleChrome/lighthouse-ci GitHub Issues~~**](https://github.com/GoogleChrome/lighthouse-ci/issues)
- Review [**~~Lighthouse CI documentation~~**](https://github.com/GoogleChrome/lighthouse-ci/blob/main/docs/getting-started.md)
- Verify [**~~configuration reference~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/configuration) syntax
- Enable verbose logging: `**lhci autorun --verbose**`

[**LHCI Server** Deploy your own Lighthouse CI server for historical tracking, build comparisons, and team dashboards. Covers Docker, Heroku, and database setup.](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/server) [**API Guide** Complete guide to using the PageSpeed Insights API. Get Lighthouse performance data programmatically with 25,000 free requests per day.](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api)

**On this page **

- [Recommended Chrome Flags for CI](#recommended-chrome-flags-for-ci)
- [Chrome Launch Failures](#chrome-launch-failures)
- [Bot Detection and 403 Errors](#bot-detection-and-403-errors)
- [Shallow Clone Issues](#shallow-clone-issues)
- [Score Variance](#score-variance)
- [Upload Issues](#upload-issues)
- [URL Normalization](#url-normalization)
- [Lost Tokens](#lost-tokens)
- [Configuration Issues](#configuration-issues)
- [Memory and Timeout Issues](#memory-and-timeout-issues)
- [startServerCommand Issues](#startservercommand-issues)
- [Assertion Failures](#assertion-failures)
- [Next Steps](#next-steps)
- PROTOCOL\_TIMEOUT Errors
- [Chrome Headless Mode Changes](#chrome-headless-mode-changes)
- [Still Having Issues?](#still-having-issues)

---

- **Page:** Fix Chrome DevTools Issues for Better Best Practices Score · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/best-practices/inspector-issues
- **Description:** Resolve browser-detected problems including mixed content, cookie issues, CSP violations, and cross-origin blocks that appear in Chrome's Issues panel.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Chrome DevTools Issues for Better Best Practices Score**

Resolve browser-detected problems including mixed content, cookie issues, CSP violations, and cross-origin blocks that appear in Chrome's Issues panel.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)3 min read Published **Jan 18, 2025**

When Chrome flags problems in its Issues panel, something's wrong with your site's security, privacy, or standards compliance. Lighthouse surfaces these issues because they indicate real problems that affect users.

## What's Happening

Chrome's browser engine detects problems during page load: insecure resource loading, cookie configuration errors, cross-origin policy violations, and more. These aren't just warnings - they often mean features are broken or security is compromised.

Lighthouse collects these issues and fails the audit if any exist. The specific issues vary:

- **Mixed content** - HTTPS page loading HTTP resources
- **Cookie issues** - Missing SameSite, Secure flags, or other problems
- **Blocked by cross-origin policy** - Resources blocked due to CORS/CORP
- **Heavy ads** - Ad frames consuming excessive resources
- **CSP violations** - Content blocked by Content Security Policy

### 2025 Watchlist: Deprecations & Compliance

The Issues panel is your early warning system for upcoming platform changes.

- **Schema Deprecations:** Watch for warnings about **Course Info**, **Vehicle Listing**, and **Practice Problems** schema, which Google is sunsetting in September 2025.
- **Accessibility Compliance:** With the **European Accessibility Act 2025** taking effect, accessibility issues flagged here are now potential legal compliance risks for any site doing business in the EU.

## Diagnose

### Chrome DevTools Issues Panel

1. Open DevTools (F12)
2. Click the **Issues** tab (might be in the overflow menu)
3. Reload the page
4. Review each issue - Chrome explains what's wrong and links to affected resources

Each issue includes:

- What triggered it
- Which resource/request is affected
- Link to documentation
- Specific remediation steps

### Quick Console Check

```js
// Issues don't appear in console by default
// Open the Issues panel or check Network tab for blocked requests
```

Look in the Network tab for:

- Requests with status `**(blocked:mixed-content)**`
- Requests with `**(blocked:csp)**`
- Failed CORS requests

## Fix

### 1. Mixed Content

HTTPS pages loading HTTP resources. Browsers block these or warn users.

**Symptoms:** Images not loading, scripts failing, "Not Secure" warnings.

```html
<!-- Bad: HTTP on HTTPS page -->
<img src="http://example.com/image.jpg">
<script src="http://cdn.example.com/lib.js"></script>

<!-- Good: HTTPS everywhere -->
<img src="https://example.com/image.jpg">
<script src="https://cdn.example.com/lib.js"></script>

<!-- Better: Protocol-relative (inherits page protocol) -->
<img src="//example.com/image.jpg">
```

**Fix checklist:**

1. Audit all external resources - images, scripts, stylesheets, fonts, iframes
2. Update URLs to HTTPS
3. For third-party resources, verify they support HTTPS
4. Add upgrade-insecure-requests header as backstop:

```http
Content-Security-Policy: upgrade-insecure-requests
```

This tells browsers to automatically upgrade HTTP to HTTPS.

### 2. Cookie Issues

Modern browsers require explicit cookie configuration.

**Common problems:**

```http
Set-Cookie: session=abc123
```

**Fixed:**

```http
Set-Cookie: session=abc123; Secure; HttpOnly; SameSite=Lax; Path=/
```

**Required attributes:**

- `**Secure**` - Only send over HTTPS (required for SameSite=None)
- `**SameSite=Lax**` - Prevents CSRF, allows top-level navigation
- `**SameSite=Strict**` - Tighter, blocks all cross-site
- `**SameSite=None; Secure**` - Cross-site allowed (requires Secure)
- `**HttpOnly**` - JavaScript can't read (for session cookies)

**Third-party cookies:** If you embed widgets that set cookies, they need `**SameSite=None; Secure**`. Without it, cookies are blocked in cross-site contexts.

### 3. Cross-Origin Policy Blocks

Resources blocked due to CORS or CORP headers.

**CORS issues:**

```text
Access to fetch at 'https://api.example.com/data' from origin 'https://mysite.com'
has been blocked by CORS policy
```

**Fix on the server returning the resource:**

```http
Access-Control-Allow-Origin: https://mysite.com
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: Content-Type
```

Or for public APIs:

```http
Access-Control-Allow-Origin: *
```

**CORP issues:**

Cross-Origin-Resource-Policy blocks embedding.

```http
Cross-Origin-Resource-Policy: same-origin

Cross-Origin-Resource-Policy: same-site

Cross-Origin-Resource-Policy: cross-origin
```

For images/resources you want embeddable, use `**cross-origin**`.

### 4. Heavy Ads

Chrome intervenes when ad iframes use excessive CPU or network.

**Thresholds:**

- 4MB network usage
- 15 seconds CPU in 30-second window
- 60 seconds total CPU

**Fix:**

1. Contact your ad provider - they need to optimize
2. Use lighter ad formats
3. Lazy-load ads below the fold
4. Consider ad networks that enforce resource limits

You can't directly fix third-party ad code, but you can choose better providers.

### 5. Content Security Policy Violations

Resources blocked by your own CSP.

```text
Refused to load the script 'https://analytics.example.com/track.js'
because it violates the Content-Security-Policy directive: "script-src 'self'"
```

**Fix options:**

**A. Add source to CSP:**

```http
Content-Security-Policy: script-src 'self' https://analytics.example.com
```

**B. Use nonce for inline scripts:**

```http
Content-Security-Policy: script-src 'nonce-abc123'
```

```html
<script nonce="abc123">
  // Allowed
</script>
```

**C. Review if the blocked resource is necessary:**

CSP correctly blocks unwanted scripts (injected by browser extensions, etc.).

## Framework Examples

**Nuxt** - Configure security headers in `**nuxt.config.ts**`:

```ts
export default defineNuxtConfig({
  routeRules: {
    '/**': {
      headers: {
        'Content-Security-Policy': 'default-src \'self\'; script-src \'self\' \'unsafe-inline\'',
        'X-Content-Type-Options': 'nosniff'
      }
    }
  }
})
```

For cookies, use `**useCookie**` with options:

```ts
const session = useCookie('session', {
  secure: true,
  sameSite: 'lax',
  httpOnly: true
})
```

**Next.js** - Set headers in `**next.config.js**`:

```js
export default {
  async headers() {
    return [{
      source: '/:path*',
      headers: [
        {
          key: 'Content-Security-Policy',
          value: 'default-src \'self\'; script-src \'self\' \'unsafe-inline\''
        }
      ]
    }]
  }
}
```

For cookies in API routes:

```js
res.setHeader('Set-Cookie', 'session=value; Secure; HttpOnly; SameSite=Lax; Path=/')
```

## Verify the Fix

1. **Reload and check Issues panel** - Should show no issues
2. **Re-run Lighthouse** - "No issues in the Issues panel" should pass
3. **Check Network tab** - No blocked requests

**Test mixed content specifically:**

```js
// In console on your HTTPS page
performance.getEntriesByType('resource').forEach((r) => {
  if (r.name.startsWith('http://')) {
    console.warn('Mixed content:', r.name)
  }
})
```

## Common Mistakes

- **Protocol-relative URLs with local resources** - `**//localhost:3000/api**` doesn't work, use full URLs.
- **Overly strict CSP** - Starting with `**default-src 'self'**` and wondering why everything breaks. Build CSP incrementally.
- **Forgetting Secure on SameSite=None** - Cookies with `**SameSite=None**` require `**Secure**` flag.
- **Ignoring third-party issues** - If an embedded widget causes issues, either fix its integration or remove it.

## Test Your Entire Site

Issues often appear only on specific pages - a blog post with an old HTTP image, a landing page with a misconfigured embed. [**~~Unlighthouse~~**](https://unlighthouse.dev/) audits every page and surfaces browser issues across your entire site.

### **Related **

[**All Best Practices Issues**](https://unlighthouse.dev/learn-lighthouse/best-practices#all-best-practices-issues) [**Best Practices Overview**](https://unlighthouse.dev/learn-lighthouse/best-practices)

[**Low Resolution Images** Serve images with appropriate resolution for the display size and device pixel ratio. Blurry images hurt perceived quality.](https://unlighthouse.dev/learn-lighthouse/best-practices/image-size-responsive) [**CLS** Google considers a CLS score of 0.1 or less as good. Learn what causes layout shifts and how to fix CLS with proven techniques for images, fonts, ads, and dynamic content.](https://unlighthouse.dev/learn-lighthouse/cls)

**On this page **

- [What's Happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Framework Examples](#framework-examples)
- [Verify the Fix](#verify-the-fix)
- [Common Mistakes](#common-mistakes)
- [Test Your Entire Site](#test-your-entire-site)

---

- **Page:** Fix Layout Shifts: CSS Reflow, Font-Size &amp; CLS Causes · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/cls/layout-shifts
- **Description:** Diagnose and fix layout shifts caused by CSS reflow, font-size changes, unsized media, web fonts, and injected iframes. Reduce your CLS score.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Layout Shifts: CSS Reflow, Font-Size & CLS Causes**

Diagnose and fix layout shifts caused by CSS reflow, font-size changes, unsized media, web fonts, and injected iframes. Reduce your CLS score.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)6 min read Published **Jan 18, 2025**

Lighthouse found significant layout shifts on your page. Each shift degrades user experience - content jumps, clicks miss their targets, users lose their place.

**CLS**Cumulative Layout Shift** CWV **

**25% weight **

Good ≤0.10Poor >0.25

## What's the problem?

A layout shift occurs when a visible element changes position between two rendered frames. The browser calculates a shift score based on the impact fraction (how much of the viewport shifted) multiplied by the distance fraction (how far it moved).

**The three main root causes Lighthouse detects:**

1. **Unsized Media** - Images, videos, or iframes without explicit dimensions
2. **Web Font Loading** - Text reflows when custom fonts replace fallbacks
3. **Injected Iframes** - Third-party iframes inserted dynamically

Each shift has a weighted score. Shifts during the largest "session window" (a burst of shifts within 5 seconds, with gaps under 1 second) contribute to your CLS metric. Lighthouse reports the top 15 shifts regardless of whether they're in the CLS calculation window.

**Why it matters:** Users interact with your page while it's loading. A 0.25 CLS means a quarter of your viewport unexpectedly moved. On mobile, that's enough to cause misclicks, frustration, and abandonment. Google uses CLS as a ranking factor. Pages scoring above 0.1 are penalized in search results.

Beyond SEO, layout shifts are a significant **accessibility barrier**. For users with cognitive disabilities, unpredictable movement can be disorienting. For those with motor impairments, it leads to "moving target" buttons that are impossible to click accurately, violating WCAG principles of being **Operable** and **Understandable**.

The audit shows each shift's score and the element that moved the most. Sub-items reveal the probable cause - unsized image, font load, or iframe injection.

## How to identify this issue

### Chrome DevTools

**Performance Panel Method:**

1. Open DevTools > Performance
2. Enable "Web Vitals" checkbox
3. Record a page load
4. Look for red "LS" markers in the timeline
5. Click each to see which element shifted and by how much

**Live Monitoring:**

```js
new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (entry.hadRecentInput)
      continue // Ignore user-initiated shifts

    console.group(`Layout Shift: ${entry.value.toFixed(4)}`)
    console.log('Time:', entry.startTime.toFixed(0), 'ms')

    for (const source of entry.sources || []) {
      console.log('Element:', source.node)
      console.log('Previous rect:', source.previousRect)
      console.log('Current rect:', source.currentRect)
    }
    console.groupEnd()
  }
}).observe({ type: 'layout-shift', buffered: true })
```

This logs every shift with the exact element and its before/after positions.

### Lighthouse

The "Avoid large layout shifts" audit lists:

- **Element**: The DOM node that shifted the most in each shift event
- **Layout shift score**: The weighted contribution to CLS
- **Root cause** (sub-items): Why the shift happened

A page with 5 shifts of 0.05 each has the same CLS as one shift of 0.25 - but different debugging approaches. Multiple small shifts suggest systemic issues (many unsized images). One large shift points to a specific culprit (hero image, late-loading banner).

## The fix

### 1. fix unsized media (most common)

When Lighthouse shows "Media element lacking an explicit size" as a root cause:

```html
<!-- Before: causes shift -->
<img src="/hero.jpg" alt="Hero">
<video src="/promo.mp4"></video>
<iframe src="https://youtube.com/embed/xyz"></iframe>

<!-- After: no shift -->
<img src="/hero.jpg" width="1200" height="630" alt="Hero">
<video src="/promo.mp4" width="1920" height="1080"></video>
<iframe src="https://youtube.com/embed/xyz" width="560" height="315"></iframe>
```

For responsive layouts, combine with CSS:

```css
img, video, iframe {
  max-width: 100%;
  height: auto;
}

/* Or use aspect-ratio */
.video-embed {
  aspect-ratio: 16 / 9;
  width: 100%;
}
```

The browser calculates the aspect ratio from width/height attributes and reserves space accordingly.

### 2. fix web font shifts

When Lighthouse shows "Web font loaded" as a root cause:

**Option A: Preload critical fonts**

```html
<link rel="preload" href="/fonts/main.woff2" as="font" type="font/woff2" crossorigin>
```

This fetches the font early, reducing the time text displays with a fallback.

**Option B: Use font-display: optional**

```css
@font-face {
  font-family: 'CustomFont';
  src: url('/fonts/main.woff2') format('woff2');
  font-display: optional;
}
```

The font only renders if it loads within \~100ms. Otherwise, the fallback persists - no shift.

**Option C: Match fallback metrics**

```css
@font-face {
  font-family: 'CustomFont';
  src: url('/fonts/main.woff2') format('woff2');
  font-display: swap;
  size-adjust: 105%;
  ascent-override: 95%;
  descent-override: 22%;
  line-gap-override: 0%;
}
```

Adjust these values until your fallback font has the same line height and width as your custom font. No reflow = no shift.

**Next.js with next/font:**

```jsx
import { Inter } from 'next/font/google'

const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
  adjustFontFallback: true, // Auto-generates fallback metrics
})
```

### 3. fix injected iframes

When Lighthouse shows "Injected iframe" as a root cause:

**Reserve space before injection:**

```html
<div class="embed-container" style="aspect-ratio: 16/9; min-height: 315px;">
  <!-- Third-party script will inject iframe here -->
</div>
```

```css
.embed-container {
  aspect-ratio: 16 / 9;
  width: 100%;
  background: var(--ui-bg-muted);
}

.embed-container iframe {
  width: 100%;
  height: 100%;
}
```

**Load iframes below the fold:**

Iframes that inject below the visible viewport don't cause CLS. Move non-critical embeds (comments, social feeds) further down the page.

**Use facade pattern:**

```html
<div class="youtube-facade" data-video-id="xyz">
  <img src="/thumbnails/xyz.jpg" alt="Video thumbnail">
  <button>Play</button>
</div>
```

```js
document.querySelector('.youtube-facade').onclick = function () {
  const iframe = document.createElement('iframe')
  iframe.src = `https://youtube.com/embed/${this.dataset.videoId}?autoplay=1`
  iframe.width = this.offsetWidth
  iframe.height = this.offsetHeight
  this.replaceWith(iframe) // Swap, same size, no shift
}
```

The iframe loads only on interaction, after the user has stopped scrolling.

### Why this works

Layout shifts happen when the browser doesn't know element sizes upfront. Every fix follows the same principle: tell the browser the size before the content loads.

- Explicit dimensions on media: browser reserves exact space
- Font metrics matching: fallback and final have same line boxes
- Container sizing for iframes: space reserved before injection

The browser does layout calculation once, not twice.

## Framework-specific solutions

**Next.js**

Handle all three root causes:

```jsx
// Fonts - next/font eliminates shift
import { Inter } from 'next/font/google'

// Images - next/image handles sizing
import Image from 'next/image'

const inter = Inter({ subsets: ['latin'] })

export function Demo() {
  return (
    <>
      <Image src="/hero.jpg" width={1200} height={630} alt="Hero" />
      {/* Iframes - wrap in sized container */}
      <div className="aspect-video relative">
        <iframe src="..." className="absolute inset-0 w-full h-full" />
      </div>
    </>
  )
}
```

For dynamic content that might cause shifts:

```jsx
import { Suspense } from 'react'

export function Content() {
  return (
    <Suspense fallback={<div style={{ height: 400 }} />}>
      <DynamicContent />
    </Suspense>
  )
}
```

**Nuxt**

```html
<template>
  <!-- Images with NuxtImg -->
  <NuxtImg src="/hero.jpg" width="1200" height="630" alt="Hero" />

  <!-- Iframes with container -->
  <div class="aspect-video">
    <iframe src="..." class="w-full h-full" />
  </div>

  <!-- Client-only with sized fallback -->
  <ClientOnly>
    <ThirdPartyWidget />
    <template #fallback>
      <div class="h-[400px] bg-gray-100" />
    </template>
  </ClientOnly>
</template>
```

For fonts, configure in `**nuxt.config.ts**`:

```ts
export default defineNuxtConfig({
  app: {
    head: {
      link: [
        {
          rel: 'preload',
          href: '/fonts/main.woff2',
          as: 'font',
          type: 'font/woff2',
          crossorigin: 'anonymous'
        }
      ]
    }
  }
})
```

## Verify the fix

**1. Re-run Lighthouse**

The "Avoid large layout shifts" audit should show fewer shifts with lower scores. Target: no shifts above 0.05, total CLS under 0.1.

**2. Monitor live CLS**

```js
let clsValue = 0
new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (!entry.hadRecentInput) {
      clsValue += entry.value
    }
  }
  console.log('Running CLS:', clsValue.toFixed(4))
}).observe({ type: 'layout-shift', buffered: true })
```

Reload multiple times. CLS should be consistently under 0.1.

**3. Visual inspection**

Record your screen while loading on throttled connection (DevTools > Network > Slow 3G). Play back at 0.5x speed. You shouldn't see content jumping.

**Expected improvement:** Fixing root causes typically reduces CLS by 50-90%. A page with CLS of 0.32 from unsized hero + font shift + ad iframe can reach 0.05 after fixes.

## Common mistakes

**Fixing shifts outside the measurement window**

Lighthouse shows shifts that may not be in the CLS window (due to windowing algorithm). Focus on the highest-score shifts first - they impact CLS most.

**Ignoring small shifts**

A shift of 0.02 seems minor. But 5 of them = 0.1 CLS. Fix all sources, not just the biggest.

**Using JavaScript to set dimensions after load**

```js
// Wrong - dimension set after image loads, too late
img.onload = () => {
  img.width = img.naturalWidth
  img.height = img.naturalHeight
}
```

Dimensions must be in HTML or CSS, available during initial parse.

**Assuming lazy loading prevents CLS**

```html
<!-- Still causes shift when image enters viewport -->
<img src="/photo.jpg" loading="lazy">
```

Lazy-loaded images still need dimensions. The shift happens when they load into view.

## Related issues

Layout shifts have cascading causes:

- [**~~Unsized Images~~**](https://unlighthouse.dev/learn-lighthouse/cls/unsized-images) - Deep dive on image dimensions
- [**~~Web Fonts~~**](https://unlighthouse.dev/learn-lighthouse/cls/web-fonts-causing-foit) - Font loading strategies
- [**~~Ads & Embeds~~**](https://unlighthouse.dev/learn-lighthouse/cls/ads-embeds-iframes) - Third-party content
- [**~~Dynamic Content~~**](https://unlighthouse.dev/learn-lighthouse/cls/dynamic-content-injection) - JavaScript-injected elements
- [**~~Animations~~**](https://unlighthouse.dev/learn-lighthouse/cls/animations-transitions) - Motion that causes reflow

## Test your entire site

Different pages have different shift patterns. A product page might have unsized thumbnails. A blog post might have embedded videos. A landing page might have late-loading CTAs. [**~~Unlighthouse~~**](https://unlighthouse.dev/) scans your entire site and reports CLS per page with the specific shifts causing problems.

### **Related **

[**CLS Overview**](https://unlighthouse.dev/learn-lighthouse/cls) [**All CLS Issues**](https://unlighthouse.dev/learn-lighthouse/cls#common-cls-issues) [**CLS Definition**](https://unlighthouse.dev/glossary/cls) [**CLS Debugger Tool**](https://unlighthouse.dev/tools/cls-debugger)

[**Images Without Dimensions** Images without width and height cause layout shifts. Add explicit dimensions to prevent your page from jumping around as images load.](https://unlighthouse.dev/learn-lighthouse/cls/unsized-images) [**Web Fonts (FOIT/FOUT)** How to prevent layout shifts from web font loading using font-display, preloading, and fallback metrics.](https://unlighthouse.dev/learn-lighthouse/cls/web-fonts-causing-foit)

**On this page **

- [What's the problem?](#whats-the-problem)
- [How to identify this issue](#how-to-identify-this-issue)
- [The fix](#the-fix)
- [Framework-specific solutions](#framework-specific-solutions)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** What is first contentful paint (FCP)? · Unlighthouse
- **Source:** https://unlighthouse.dev/glossary/fcp
- **Description:** FCP measures when the first content renders. Learn what it is, thresholds, and how to improve it.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Glossary**

# **What is first contentful paint (FCP)?**

[Copy for LLMs](https://unlighthouse.dev/glossary/fcp.md)

First Contentful Paint (FCP) measures when the browser renders the first piece of content - text, image, SVG, or canvas element. It answers "is anything happening?" and contributes 10% to your Lighthouse score.

## Thresholds

| **Score** | **Rating** |
| --- | --- |
| ≤ 1.8s | Good |
| 1.8s - 3.0s | Needs Improvement |
| > 3.0s | Poor |

Aim for a score of 1.8 seconds or less at the 75th percentile of page loads to pass the [**~~Google threshold~~**](https://web.dev/articles/fcp).

## FCP vs LCP

| **Metric** | **Measures** | **Question It Answers** |
| --- | --- | --- |
| FCP | First content appears | "Is anything happening?" |
| [**~~LCP~~**](https://unlighthouse.dev/glossary/lcp) | Largest content appears | "Is the main content loaded?" |

A page can have fast FCP (spinner appears) but slow LCP (actual content takes longer). Both matter for UX.

## Why it matters

FCP marks when users perceive the page is loading. Before FCP, they see only a blank screen. Fast FCP reassures users something is happening, reducing early abandonment.

## Common issues

- Slow server response ([**~~TTFB~~**](https://unlighthouse.dev/glossary/ttfb))
- Render-blocking CSS/JavaScript
- Large CSS files blocking first paint
- Web fonts with `**font-display: block**`

## Measure FCP

- Chrome DevTools Performance panel
- Lighthouse audit
- [**~~PageSpeed Insights~~**](https://pagespeed.web.dev/)

FCP is a Lighthouse metric, not a Core Web Vital. Improving FCP typically improves [**~~LCP~~**](https://unlighthouse.dev/glossary/lcp), which is a Core Web Vital and ranking factor.

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/fcp.md)

[Markdown For LLMs](https://unlighthouse.dev/glossary/fcp.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/fcp.md) on GitHub or provide anonymous feedback below.

### **Related **

[**Largest Contentful Paint (LCP)**](https://unlighthouse.dev/glossary/lcp) [**Time to First Byte (TTFB)**](https://unlighthouse.dev/glossary/ttfb)

[**CLS** CLS measures visual stability. Learn what it is, thresholds, and how to prevent layout shifts.](https://unlighthouse.dev/glossary/cls) [**INP** INP measures responsiveness. Learn what it is, thresholds, and how to improve interaction speed.](https://unlighthouse.dev/glossary/inp)

**On this page **

- [Thresholds](#thresholds)
- [FCP vs LCP](#fcp-vs-lcp)
- [Why it matters](#why-it-matters)
- [Common issues](#common-issues)
- [Measure FCP](#measure-fcp)

---

- **Page:** What is time to interactive (TTI)? · Unlighthouse
- **Source:** https://unlighthouse.dev/glossary/tti
- **Description:** TTI measured page interactivity but was deprecated in Lighthouse 10. Learn what replaced it.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Glossary**

# **What is time to interactive (TTI)?**

[Copy for LLMs](https://unlighthouse.dev/glossary/tti.md)

Time to Interactive (TTI) was **removed from Lighthouse 10** in February 2023. Use [**~~TBT~~**](https://unlighthouse.dev/glossary/tbt) for lab measurement and [**~~INP~~**](https://unlighthouse.dev/glossary/inp) for field measurement.

Time to Interactive measured when a page became fully interactive - displaying useful content, event handlers registered, and responding within 50ms. It identified a 5-second "quiet window" with no Long Tasks.

## Why TTI was deprecated

[**~~Google removed TTI~~**](https://developer.chrome.com/blog/lighthouse-10-0) because:

- **Overly sensitive to outliers** - A single late network request could inflate TTI
- **Better alternatives exist** - [**~~TBT~~**](https://unlighthouse.dev/glossary/tbt) measures blocking more robustly
- **Poor correlation with real experience** - Terrible TTI could still feel responsive

## What replaced TTI

### Lab testing

[**~~Total Blocking Time (TBT)~~**](https://unlighthouse.dev/glossary/tbt) - Measures cumulative main thread blocking. Now has 30% Lighthouse weight.

### Field measurement

[**~~Interaction to Next Paint (INP)~~**](https://unlighthouse.dev/glossary/inp) - Measures actual interaction responsiveness. Core Web Vital since March 2024.

## Historical thresholds

| **Score** | **Rating** |
| --- | --- |
| ≤ 3.8s | Good |
| 3.8s - 7.3s | Needs Improvement |
| > 7.3s | Poor |

## Migration

| **Old** | **New** |
| --- | --- |
| TTI in Lighthouse | Use [**~~TBT~~**](https://unlighthouse.dev/glossary/tbt) |
| TTI in field/RUM | Use [**~~INP~~**](https://unlighthouse.dev/glossary/inp) |
| TTI CI assertions | Switch to TBT thresholds |

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/tti.md)

[Markdown For LLMs](https://unlighthouse.dev/glossary/tti.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/tti.md) on GitHub or provide anonymous feedback below.

### **Related **

[**Total Blocking Time (TBT)**](https://unlighthouse.dev/glossary/tbt) [**Interaction to Next Paint (INP)**](https://unlighthouse.dev/glossary/inp) [**INP Guide**](https://unlighthouse.dev/learn-lighthouse/inp)

[**TTFB** TTFB measures server response time. Learn what it is, thresholds, and how to optimize it.](https://unlighthouse.dev/glossary/ttfb) 

**On this page **

- [Why TTI was deprecated](#why-tti-was-deprecated)
- [What replaced TTI](#what-replaced-tti)
- [Historical thresholds](#historical-thresholds)
- [Migration](#migration)

---

- **Page:** Fix Heavy Main Thread Work for Better INP · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/inp/heavy-dom-operations
- **Description:** Reduce main thread work from DOM manipulation, style recalculation, and layout thrashing. Keep interactions responsive.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Heavy Main Thread Work for Better INP**

Reduce main thread work from DOM manipulation, style recalculation, and layout thrashing. Keep interactions responsive.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)7 min read Published **Jan 18, 2025**

Your browser spent 4 seconds doing work on the main thread. During that time? Every user interaction waited in line. The `**mainthread-work-breakdown**` audit measures everything the browser does: parsing, compiling, layout, paint, JavaScript execution. When this total exceeds 2 seconds, interactions suffer.

**TBT**Total Blocking Time

**30% weight **

Good ≤200msPoor >600ms

## What's the problem?

Lighthouse measures total main thread work and scores it on a curve. A score of 100 requires under 2,017ms of main thread time. The median failing site clocks in at 4,000ms. That's 4 seconds where the browser can't fully respond to user input.

The audit breaks work into categories:

| **Category** | **What It Measures** |
| --- | --- |
| Script Evaluation | Running JavaScript, event handlers, timers |
| Script Parsing & Compilation | Parsing and compiling JS files |
| Style & Layout | Recalculating styles, computing layout |
| Rendering | Paint, composite, hit testing |
| Parse HTML & CSS | Parsing markup and stylesheets |
| Garbage Collection | Memory cleanup |

Each category contributes to input delay. When you click a button, the browser must finish its current task before responding. Long tasks directly hurt INP.

### Technical SEO: indexation gaps

Heavy main thread work doesn't just annoy users - it confuses search crawlers. Googlebot has a "rendering budget." If your page spends seconds recalculating layout or executing heavy scripts, the crawler may timeout before indexing your key content.

This leads to **"Indexation Gaps"**: where your content exists in HTML but isn't indexed because the renderer couldn't reach a stable state in time.

## How to identify the issue

### DevTools performance panel

1. Open DevTools (F12) and go to Performance
2. Record while interacting with your page
3. Look at the Main thread timeline
4. Tasks with red corners exceed 50ms (long tasks)

Color coding in the flame chart:

- **Yellow**: JavaScript execution
- **Purple**: Layout and style recalculation
- **Green**: Paint and composite

If you see large purple blocks during interactions, DOM operations are your bottleneck.

### Lighthouse breakdown

Run Lighthouse and expand the "Minimize main-thread work" audit. It shows time spent in each category. Focus on the largest contributors first.

## The fix

### 1. batch DOM reads and writes

Layout thrashing occurs when you read layout properties, write to the DOM, then read again. Each read forces the browser to recalculate layout.

```js
// Layout thrashing: 100 forced layouts
elements.forEach((el) => {
  const width = el.offsetWidth // Read - forces layout
  el.style.width = `${width * 2}px` // Write - invalidates layout
})

// Fixed: batch reads, then batch writes
const widths = elements.map(el => el.offsetWidth) // All reads
elements.forEach((el, i) => {
  el.style.width = `${widths[i] * 2}px` // All writes
})
```

Common properties that trigger layout: `**offsetWidth**`, `**offsetHeight**`, `**offsetTop**`, `**offsetLeft**`, `**scrollTop**`, `**scrollHeight**`, `**clientWidth**`, `**clientHeight**`, `**getComputedStyle()**`, `**getBoundingClientRect()**`.

### 2. use requestanimationframe for visual updates

Schedule DOM updates to run at the optimal time in the frame:

```js
// Scroll handler causing jank
function onScroll() {
  updateParallax()
  updateSticky()
  updateProgress()
}

// Fixed: throttle with rAF
let ticking = false
function onScrollThrottled() {
  if (!ticking) {
    requestAnimationFrame(() => {
      updateParallax()
      updateSticky()
      updateProgress()
      ticking = false
    })
    ticking = true
  }
}
```

This makes sure updates happen once per frame at most, not dozens of times per scroll event.

### 3. use CSS containment

Tell the browser what doesn't need recalculation:

```css
.card {
  contain: layout style;
}

.sidebar {
  contain: strict;
}
```

Containment values:

- `**contain: layout**` - Element's layout is independent
- `**contain: style**` - Styles don't leak out
- `**contain: paint**` - Content won't render outside bounds
- `**contain: strict**` - All of the above plus size

With containment, changing one card doesn't force recalculation of other cards.

### 4. use content-visibility for offscreen content

Skip rendering for content not in the viewport:

```css
.article-section {
  content-visibility: auto;
  contain-intrinsic-size: auto 500px;
}
```

The browser skips layout and paint for offscreen sections. The `**contain-intrinsic-size**` provides an estimated height to prevent scroll jumping.

Real-world impact: A page with 50 article sections saw rendering work drop from 230ms to 30ms with `**content-visibility: auto**`.

### 5. reduce style complexity

Complex CSS selectors are expensive to match:

```css
/* Slow: checks many ancestors */
.sidebar > .nav > ul > li > a.active span.icon {}

/* Fast: direct class match */
.nav-icon-active {}
```

Also avoid expensive properties during interactions:

- `**box-shadow**` with large blur radius
- `**filter: blur()**` on large elements
- `**transform**` on elements without `**will-change**`

### 6. virtual scrolling for long lists

Don't render 10,000 items when only 20 are visible:

```jsx
// @tanstack/react-virtual
import { useVirtualizer } from '@tanstack/react-virtual'

function VirtualList({ items }) {
  const parentRef = useRef(null)

  const virtualizer = useVirtualizer({
    count: items.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 50,
  })

  return (
    <div ref={parentRef} style={{ height: 400, overflow: 'auto' }}>
      <div style={{ height: virtualizer.getTotalSize() }}>
        {virtualizer.getVirtualItems().map(virtualRow => (
          <div
            key={virtualRow.key}
            style={{
              position: 'absolute',
              top: virtualRow.start,
              height: virtualRow.size,
            }}
          >
            {items[virtualRow.index].name}
          </div>
        ))}
      </div>
    </div>
  )
}
```

Virtual scrolling reduces DOM nodes from thousands to dozens.

## Framework-specific solutions

**React / Next.js**

Use `**React.memo**` to prevent re-renders of unchanged components:

```jsx
const ListItem = React.memo(({ item }) => (
  <div className="list-item">{item.name}</div>
))
```

Use `**useMemo**` for expensive calculations:

```jsx
const sortedItems = useMemo(() =>
  items.slice().sort((a, b) => a.name.localeCompare(b.name)), [items])
```

For lists, use `**@tanstack/react-virtual**` or `**react-window**`.

**Vue / Nuxt**

Use `**computed**` properties which Vue caches:

```html
<script setup>
const sortedItems = computed(() =>
  [...items.value].sort((a, b) => a.name.localeCompare(b.name))
)
</script>
```

Use `**v-memo**` to skip re-renders:

```html
<div v-for="item in items" :key="item.id" v-memo="[item.updated]">
  <ExpensiveComponent :item="item" />
</div>
```

For lists, use `**vue-virtual-scroller**` or `**@tanstack/vue-virtual**`.

## Verify the fix

After changes:

1. Run Lighthouse again - main thread work should decrease
2. Record Performance trace during interactions
3. Check that no single category dominates
4. Monitor TBT as a proxy for INP impact

**Target:** Keep total main thread work under 2,000ms. Each major category (script evaluation, style/layout) should be under 500ms.

## Common mistakes

**Reading layout in loops.** Every `**offsetWidth**` read forces a layout recalculation if the DOM was modified.

**Animating layout properties.** Animating `**width**`, `**height**`, `**top**`, `**left**` triggers layout. Use `**transform**` and `**opacity**` instead.

**Missing contain-intrinsic-size.** Without it, `**content-visibility: auto**` causes scroll jumps as content renders.

**Over-using will-change.** Adding `**will-change: transform**` to everything consumes memory. Use it sparingly on elements that animate.

## Related issues

Main thread work often combines with:

- [**~~DOM Size~~**](https://unlighthouse.dev/learn-lighthouse/inp/dom-size) - Larger DOMs mean more style recalculation
- [**~~Long-Running JavaScript~~**](https://unlighthouse.dev/learn-lighthouse/inp/long-running-javascript) - Script evaluation is part of main thread work
- [**~~Third-Party Scripts~~**](https://unlighthouse.dev/learn-lighthouse/inp/third-party-scripts) - External scripts add to main thread time

## Test your entire site

Different pages have different main thread profiles. A product listing page might be style-heavy while a dashboard might be script-heavy.

[**~~Unlighthouse~~**](https://unlighthouse.dev/) scans your entire site and identifies pages with the highest TBT, which correlates with main thread work and INP.

### **Related **

[**INP Overview**](https://unlighthouse.dev/learn-lighthouse/inp) [**All INP Issues**](https://unlighthouse.dev/learn-lighthouse/inp#common-inp-issues) [**INP Definition**](https://unlighthouse.dev/glossary/inp) [**INP Analyzer Tool**](https://unlighthouse.dev/tools/inp-analyzer)

[**Total Blocking Time** Reduce TBT to improve your Lighthouse performance score. TBT measures main thread blocking - the lab proxy for real-world INP.](https://unlighthouse.dev/learn-lighthouse/inp/total-blocking-time) [**DOM Size** Large DOMs slow every interaction. Reduce DOM size with virtualization, lazy rendering, and smarter component architecture.](https://unlighthouse.dev/learn-lighthouse/inp/dom-size)

**On this page **

- [What's the problem?](#whats-the-problem)
- [How to identify the issue](#how-to-identify-the-issue)
- [The fix](#the-fix)
- [Framework-specific solutions](#framework-specific-solutions)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix HTTPS Issues for Better Best Practices Score · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/best-practices/is-on-https
- **Description:** Eliminate insecure HTTP requests and mixed content warnings. Learn to enforce HTTPS across your entire site for security and modern web features.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix HTTPS Issues for Better Best Practices Score**

Eliminate insecure HTTP requests and mixed content warnings. Learn to enforce HTTPS across your entire site for security and modern web features.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)3 min read Published **Jan 18, 2025**

Your site loads resources over insecure HTTP, exposing users to man-in-the-middle attacks and blocking access to modern browser APIs.

## What's Happening

Lighthouse detects network requests using `**http://**` instead of `**https://**`. This happens when your HTML references assets with explicit HTTP URLs, protocol-relative URLs that resolve to HTTP, or when third-party resources lack HTTPS support. Mixed content, loading HTTP resources on an HTTPS page, triggers browser warnings and can be blocked entirely.

HTTPS prevents attackers from intercepting or modifying data between your server and users. Beyond security, it's a prerequisite for HTTP/2, Service Workers, geolocation, camera access, and most modern web platform APIs.

**2025 SEO Reality:** HTTPS is a confirmed lightweight ranking signal (approx 2% weight), but more importantly, it's a "gatekeeper" signal. If you don't have it, you're disqualified from many rich result types and user trust indicators.

## Diagnose

### Chrome DevTools

1. Open DevTools (F12) and go to the **Security** tab
2. Check the "Security Overview" for warnings about mixed content
3. Switch to **Network** tab and filter by `**mixed-content:displayed**` or `**mixed-content:blockable**`
4. Look for the padlock icon in the address bar - a warning triangle indicates mixed content

### Console Warnings

Mixed content appears in the Console as:

```text
Mixed Content: The page at 'https://example.com' was loaded over HTTPS,
but requested an insecure resource 'http://cdn.example.com/script.js'.
This request has been blocked; the content must be served over HTTPS.
```

## Fix

### 1. Update All Resource URLs to HTTPS

Find and replace HTTP references in your codebase.

```html
<!-- Before -->
<script src="http://cdn.example.com/lib.js"></script>
<img src="http://images.example.com/photo.jpg">
<link href="http://fonts.googleapis.com/css?family=Roboto">

<!-- After -->
<script src="https://cdn.example.com/lib.js"></script>
<img src="https://images.example.com/photo.jpg">
<link href="https://fonts.googleapis.com/css?family=Roboto">
```

For URLs in JavaScript:

```js
// Before
const API_URL = 'http://api.example.com'

// After
const API_URL_NEW = 'https://api.example.com'
```

Use protocol-relative URLs only if you still need HTTP support (rare):

```html
<!-- Works on both HTTP and HTTPS, but prefer explicit HTTPS -->
<script src="//cdn.example.com/lib.js"></script>
```

### 2. Add Content Security Policy

Enforce HTTPS at the browser level with CSP headers:

```http
Content-Security-Policy: upgrade-insecure-requests
```

This tells browsers to automatically upgrade HTTP requests to HTTPS. Configure it on your server:

```nginx
add_header Content-Security-Policy "upgrade-insecure-requests" always;
```

```js
// Vercel/Next.js - next.config.js
export default {
  headers: async () => [{
    source: '/(.*)',
    headers: [{
      key: 'Content-Security-Policy',
      value: 'upgrade-insecure-requests'
    }]
  }]
}
```

```ts
// Nuxt - nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    '/**': {
      headers: {
        'Content-Security-Policy': 'upgrade-insecure-requests'
      }
    }
  }
})
```

### 3. Handle Third-Party Resources

If a third-party service doesn't support HTTPS:

1. **Find an alternative**: Most reputable services support HTTPS
2. **Self-host**: Download the resource and serve it from your own HTTPS domain
3. **Proxy**: Route requests through your server (adds latency)

```js
// Proxying an insecure API through your backend
// /api/proxy-legacy.js
export default async function handler(req, res) {
  const data = await fetch('http://legacy-api.example.com/data')
  res.json(await data.json())
}
```

## Verify the Fix

1. Open Chrome DevTools Security tab - should show "This page is secure"
2. Check the Network tab with filter `**mixed-content:all**` - should return no results
3. Run Lighthouse - "Uses HTTPS" audit should pass
4. Test in incognito mode to make sure no cached resources skew results

## Common Mistakes

- **Forgetting database content**: URLs stored in CMS databases or user-generated content may contain HTTP links. Run a database migration or use CSP `**upgrade-insecure-requests**` as a safety net.
- **Hardcoded URLs in CSS**: Background images and font URLs in stylesheets are easy to miss:

  ```css
  /* Check your CSS files for http:// URLs */
  background: url(http://example.com/bg.png);
  ```


- **Ignoring iframes**: Embedded content like widgets, videos, or ads may load over HTTP. Contact the provider or find HTTPS alternatives.
- **Development vs production confusion**: Using HTTP localhost URLs that get deployed. Use environment variables for API endpoints.

## Related Issues

HTTPS issues often appear alongside:

- [**~~HTTP Redirects~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/redirects-http) - HTTP requests should redirect to HTTPS
- [**~~Console Errors~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/errors-in-console) - Mixed content warnings appear as errors
- [**~~DevTools Issues~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/inspector-issues) - Security warnings appear in Issues tab

## Test Your Entire Site

Mixed content issues often hide on less-visited pages - embedded videos on blog posts, legacy image galleries, or user-generated content. Scan your entire site to catch every insecure request before users encounter browser warnings.

### **Related **

[**All Best Practices Issues**](https://unlighthouse.dev/learn-lighthouse/best-practices#all-best-practices-issues) [**Best Practices Overview**](https://unlighthouse.dev/learn-lighthouse/best-practices)

[**Back/Forward Cache** Make back button navigation instant with bfcache. Learn common blockers and how to fix them.](https://unlighthouse.dev/learn-lighthouse/best-practices/bf-cache) [**Notifications** Stop requesting notification permission on page load. Users dismiss these prompts reflexively - wait for a user action that shows they want notifications.](https://unlighthouse.dev/learn-lighthouse/best-practices/notification-on-start)

**On this page **

- [What's Happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Verify the Fix](#verify-the-fix)
- [Common Mistakes](#common-mistakes)
- [Related Issues](#related-issues)
- [Test Your Entire Site](#test-your-entire-site)

---

- **Page:** Fix back&#x2F;forward cache issues · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/best-practices/bf-cache
- **Description:** Make back button navigation instant with bfcache. Learn common blockers and how to fix them.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix back/forward cache issues**

Make back button navigation instant with bfcache. Learn common blockers and how to fix them.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)3 min read Published **Jan 18, 2025**

bfcache makes back button navigation instant. Fix it first. If your page prevents bfcache, users wait for a full reload instead.

## What's happening

The back/forward cache (bfcache) stores page snapshots in memory. When users hit back or forward, the browser restores the snapshot instantly. No network requests, no JavaScript re-execution, no layout recalculation. It's the fastest navigation possible. Use it.

Unload handlers, WebSockets, and certain HTTP headers block bfcache. When blocked, the back button triggers a full page reload and adds seconds to the navigation.

Lighthouse tests bfcache by simulating a back/forward navigation. It reports specific blocking reasons if restoration fails.

## Diagnose

### Chrome DevTools Application tab

1. Open DevTools and go to Application tab.
2. Find "Back/forward cache" in the sidebar.
3. Click "Test back/forward cache."
4. Review the blocking reasons if the test fails.

The panel categorizes blockers as:

- **Actionable**: Issues in your code you must fix.
- **Pending browser support**: Browser limitations that future updates may resolve.
- **Not actionable**: Inherent limitations.

### Lighthouse audit

The "Page prevented back/forward cache restoration" audit shows:

- Each blocking reason with a description.
- The frame URL where Lighthouse detected the blocker.
- Whether the blocker is actionable.

## Fix

### 1. Remove `**unload**` event handlers

The `**unload**` event is the most common bfcache blocker. It's unreliable. Mobile browsers often don't fire it.

```js
// Bad: blocks bfcache
window.addEventListener('unload', () => {
  sendAnalytics()
})

// Good: use pagehide with persisted check
window.addEventListener('pagehide', (event) => {
  if (!event.persisted) {
    // Page is being destroyed, not cached
    sendAnalytics()
  }
})

// Better: use visibilitychange for analytics
document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'hidden') {
    navigator.sendBeacon('/analytics', data)
  }
})
```

Also check for `**beforeunload**` handlers that aren't conditionally added:

```js
// Bad: always blocks bfcache
window.addEventListener('beforeunload', handleBeforeUnload)

// Good: only add when user has unsaved changes
function enableUnsavedWarning() {
  window.addEventListener('beforeunload', handleBeforeUnload)
}

function disableUnsavedWarning() {
  window.removeEventListener('beforeunload', handleBeforeUnload)
}
```

### 2. Close open connections

Persistent connections block bfcache.

**WebSockets**:

```js
// Close WebSocket when page is hidden
document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'hidden') {
    socket.close()
  }
})

// Reconnect when page becomes visible
document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'visible' && !socket.connected) {
    socket.connect()
  }
})
```

**IndexedDB transactions**:

```js
// Check that transactions complete before page hide
window.addEventListener('pagehide', () => {
  // Let any pending transactions commit
  db.close()
})
```

### 3. Avoid blocking HTTP headers

These response headers prevent bfcache:

```http
Cache-Control: no-store
Cache-Control: no-cache, no-store, must-revalidate

Cache-Control: private, max-age=0, must-revalidate
```

The `**no-store**` directive tells browsers never to cache the response. This extends to bfcache. Use `**private**` instead to prevent CDN caching while allowing bfcache.

### 4. Handle `**pageshow**` for restored pages

Refresh stale state when a page is restored from bfcache:

```js
window.addEventListener('pageshow', (event) => {
  if (event.persisted) {
    // Page was restored from bfcache
    // Refresh stale data
    refreshUserSession()
    updateTimestamps()
    reconnectWebSocket()
  }
})
```

### 5. Address third-party blockers

Third-party scripts add `**unload**` handlers. Check for:

- Analytics scripts (older versions of Google Analytics)
- Chat widgets
- Ad scripts
- Social media embeds

```js
// Audit what's listening to unload
getEventListeners(window).unload
// Returns array of unload handlers with source info
```

Update third-party scripts or defer their loading until interaction:

```html
<!-- Defer chat widget until user interacts -->
<script>
  document.addEventListener('click', () => {
    loadChatWidget()
  }, { once: true })
</script>
```

## Verify the fix

1. Open DevTools Application tab.
2. Navigate to "Back/forward cache."
3. Click "Test back/forward cache."
4. Resolve all actionable blockers.
5. Run Lighthouse to verify the audit passes.
6. Manually test: navigate away, then hit back. The page must restore instantly without network activity.

## Common mistakes

- **Third-party analytics**: Older analytics libraries add unload handlers. Update them immediately.
- **Browser extensions**: Extensions inject blocking code. Test in incognito mode with extensions disabled.
- **Service worker fetch handlers**: Complex fetch handlers block bfcache. Keep service worker logic simple.
- **Cross-origin iframes**: A blocked iframe blocks the whole page. Check all third-party embeds.
- **Testing in DevTools with throttling**: Network throttling interferes with bfcache testing. Test without throttling.

## Pending browser support issues

Some bfcache blockers aren't actionable yet:

- **BroadcastChannel**: Open BroadcastChannels block bfcache in some browsers.
- **SharedWorker**: SharedWorker prevents bfcache.
- **Keepalive fetch**: Pending fetch requests with keepalive block restoration.

Monitor the Chrome status page for changes.

## Test your entire site

Different pages have different third-party scripts and connection patterns. Test bfcache across your entire site to catch all blockers.

### **Related **

[**All Best Practices Issues**](https://unlighthouse.dev/learn-lighthouse/best-practices) [**web.dev bfcache guide**](https://web.dev/bfcache/)

[**Best Practices** Understand Lighthouse Best Practices audits, fix common security and browser issues, and verify failures across every page template.](https://unlighthouse.dev/learn-lighthouse/best-practices) [**HTTPS** Eliminate insecure HTTP requests and mixed content warnings. Learn to enforce HTTPS across your entire site for security and modern web features.](https://unlighthouse.dev/learn-lighthouse/best-practices/is-on-https)

**On this page **

- [What's happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Pending browser support issues](#pending-browser-support-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix Inputs That Block Pasting · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/best-practices/paste-preventing-inputs
- **Description:** Stop preventing users from pasting into input fields. Blocking paste breaks password managers and frustrates users without improving security.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Inputs That Block Pasting**

Stop preventing users from pasting into input fields. Blocking paste breaks password managers and frustrates users without improving security.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)3 min read Published **Jan 18, 2025**

Preventing paste in form fields is security theater that actively harms your users. It blocks password managers, forces manual typing of complex passwords, and makes forms slower for everyone - while providing zero actual security benefit.

## What's Happening

Some input fields have JavaScript that intercepts the `**paste**` event and cancels it, or CSS that disables clipboard functionality. This typically appears on:

- Password confirmation fields ("retype your password")
- Email confirmation fields
- Credit card number inputs
- Verification code fields

The intent is usually to force users to "prove" they typed correctly. In practice, it:

1. Breaks password managers (the primary tool for using strong, unique passwords)
2. Forces users to manually type long, random passwords - leading to errors and frustration
3. Encourages simpler passwords that are easier to type
4. Fails to catch typos anyway (users mistype the same way twice)

## Diagnose

### DevTools

1. Right-click the problematic input > Inspect
2. In Elements panel, look for `**onpaste**` attribute in HTML
3. Check Event Listeners panel for `**paste**` listeners
4. Look for CSS `**user-select: none**` or `**-webkit-user-select: none**`

### Quick Console Check

```js
document.querySelectorAll('input, textarea').forEach((el) => {
  const events = getEventListeners(el)
  if (events.paste) {
    console.warn('Paste blocked on:', el, events.paste)
  }
})
```

### Lighthouse Details

The audit "Prevents users from pasting into input fields" lists each offending element with its DOM location and input type.

## Fix

### 1. Remove Paste Prevention

Find and delete the code blocking paste:

**Before (bad):**

```html
<!-- HTML attribute -->
<input type="password" onpaste="return false">

<!-- Inline handler -->
<input type="email" onpaste="event.preventDefault()">
```

**After (good):**

```html
<input type="password">
<input type="email">
```

**JavaScript event listener:**

```js
// Bad: Blocking paste
passwordInput.addEventListener('paste', e => e.preventDefault())

// Good: Remove the listener entirely, or just delete this code
```

### 2. Remove Confirmation Fields Entirely

The "retype your email" pattern doesn't catch errors anyway. Users who mistype their email will mistype it the same way twice.

**Before:**

```html
<input type="email" name="email" placeholder="Email">
<input type="email" name="email_confirm" placeholder="Confirm email" onpaste="return false">
```

**After:**

```html
<input type="email" name="email" placeholder="Email">
```

Add email verification by sending a confirmation link. That's actual validation.

### 3. If You Must Have Confirmation, Allow Paste

If product requirements demand confirmation fields, at least let users paste:

```html
<label>
  Password
  <input type="password" name="password" autocomplete="new-password">
</label>
<label>
  Confirm Password
  <input type="password" name="password_confirm" autocomplete="new-password">
</label>
```

Both fields allow paste. Password managers fill both. Users with manual passwords can paste into both. Validation happens on submit:

```js
form.addEventListener('submit', (e) => {
  const password = form.password.value
  const confirm = form.password_confirm.value

  if (password !== confirm) {
    e.preventDefault()
    showError('Passwords do not match')
  }
})
```

### 4. Fix CSS-Based Blocking

Some implementations use CSS to prevent text selection and pasting:

**Before (bad):**

```css
.secure-input {
  user-select: none;
  -webkit-user-select: none;
}
```

**After (good):**

```css
/* Just remove these properties */
.secure-input {
  /* Let users interact normally */
}
```

### 5. Handle Third-Party Form Libraries

Some form libraries or payment processors add paste prevention. Check their configuration:

```js
// Example: Some validation libraries
const form = new FormValidator({
  preventPaste: false, // Disable this
  // ...
})
```

For embedded payment forms (Stripe, etc.), check their documentation for paste-related settings.

## Verify the Fix

1. Reload the page
2. Click into the previously blocked input
3. Paste text ( `**Cmd/Ctrl+V**`)
4. Text should appear

Test with a password manager:

1. Use the password manager to fill the form
2. All fields should populate correctly

Run Lighthouse - the "Prevents users from pasting into input fields" audit should pass.

## Common Mistakes

- **Blocking paste only on confirmation field** - Both fields should allow paste. Password managers need to fill both.
- **Using readonly instead** - `**readonly**` prevents all input. That's not the same as a functional field that accepts paste.
- **Replacing with custom paste handling** - Some devs try to "sanitize" pasted content. Unless you're stripping specific characters (like spaces from phone numbers), allow normal paste.
- **Mobile keyboard considerations** - Some mobile keyboards have paste functionality that doesn't trigger the standard `**paste**` event. Blocking paste may work inconsistently anyway.

## The Security Argument

The argument for blocking paste is usually "users should verify what they're typing." Here's why that's backwards:

1. **Password managers generate unique, random passwords** - Blocking paste means users can't use them, leading to weaker passwords.
2. **Mistyped passwords get mistyped consistently** - If someone mistypes their email as `**john@gmial.com**`, they'll type it wrong both times.
3. **Actual security happens server-side** - Rate limiting, account verification, and proper authentication matter. Paste prevention doesn't.

NCSC (UK National Cyber Security Centre) explicitly recommends against blocking paste in their password guidance.

## Test Your Entire Site

Paste prevention often appears on specific pages: signup, checkout, account settings. [**~~Unlighthouse~~**](https://unlighthouse.dev/) scans your entire site and flags every input with paste prevention, across all forms.

### **Related **

[**Best Practices Overview**](https://unlighthouse.dev/learn-lighthouse/best-practices)

[**Notifications** Stop requesting notification permission on page load. Users dismiss these prompts reflexively - wait for a user action that shows they want notifications.](https://unlighthouse.dev/learn-lighthouse/best-practices/notification-on-start) [**HTTP Redirect** Configure your server to redirect all HTTP traffic to HTTPS. Protect users and enable secure web features across your entire site.](https://unlighthouse.dev/learn-lighthouse/best-practices/redirects-http)

**On this page **

- [What's Happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Verify the Fix](#verify-the-fix)
- [Common Mistakes](#common-mistakes)
- [The Security Argument](#the-security-argument)
- [Test Your Entire Site](#test-your-entire-site)

---

- **Page:** Fix HTTP to HTTPS Redirect for Better Best Practices Score · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/best-practices/redirects-http
- **Description:** Configure your server to redirect all HTTP traffic to HTTPS. Protect users and enable secure web features across your entire site.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix HTTP to HTTPS Redirect for Better Best Practices Score**

Configure your server to redirect all HTTP traffic to HTTPS. Protect users and enable secure web features across your entire site.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)3 min read Published **Jan 18, 2025**

Users accessing your site via HTTP aren't being redirected to HTTPS, leaving them on an insecure connection.

## What's Happening

Lighthouse tests what happens when a user visits your site using `**http://**`. If the connection stays on HTTP instead of redirecting to HTTPS, the audit fails. This occurs when your server accepts HTTP requests but doesn't issue a redirect response.

Without this redirect, users who type your domain without `**https://**`, click old bookmarks, or follow HTTP links are left on an insecure connection. Their traffic is unencrypted and vulnerable to interception.

## Diagnose

### Browser Check

1. Open a new incognito window
2. Type your domain with explicit `**http://**` prefix: `**http://yoursite.com**`
3. Check the address bar after the page loads
4. If it still shows `**http://**`, the redirect is missing

### Command Line

```bash
curl -I http://yoursite.com

HTTP/1.1 301 Moved Permanently
Location: https://yoursite.com/
```

If you see `**200 OK**` instead of a redirect, the server serves content over HTTP.

## Fix

### 1. Server-Level Redirect (Recommended)

Configure your web server or hosting platform to redirect HTTP to HTTPS.

**Nginx:**

```nginx
server {
    listen 80;
    server_name yoursite.com www.yoursite.com;
    return 301 https://$host$request_uri;
}
```

**Apache (.htaccess):**

```apache
RewriteEngine On
RewriteCond %{HTTPS} off
RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
```

**Caddy:** (Automatic - Caddy redirects HTTP to HTTPS by default)

```text
yoursite.com {
    # HTTPS redirect happens automatically
}
```

### 2. Hosting Platform Configuration

Most hosting platforms handle this through their dashboard.

**Cloudflare:**

1. Go to SSL/TLS > Edge Certificates
2. Enable "Always Use HTTPS"

**Vercel:** Automatic - all HTTP requests redirect to HTTPS by default.

**Netlify:**

1. Go to Domain settings
2. Enable "Force HTTPS"

**AWS CloudFront:**

1. Edit distribution behavior
2. Set "Viewer Protocol Policy" to "Redirect HTTP to HTTPS"

### 3. Add HSTS Header

HTTP Strict Transport Security tells browsers to always use HTTPS, preventing even the initial HTTP request on subsequent visits.

```http
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
```

Configure on your server:

```nginx
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
```

```js
// Vercel/Next.js - next.config.js
export default {
  headers: async () => [{
    source: '/(.*)',
    headers: [{
      key: 'Strict-Transport-Security',
      value: 'max-age=31536000; includeSubDomains; preload'
    }]
  }]
}
```

```ts
// Nuxt - nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    '/**': {
      headers: {
        'Strict-Transport-Security': 'max-age=31536000; includeSubDomains; preload'
      }
    }
  }
})
```

After you deploy and verify HSTS, submit to the [**~~HSTS Preload List~~**](https://hstspreload.org) to have browsers enforce HTTPS before the first visit.

## Verify the Fix

1. Clear browser cache or use incognito mode
2. Navigate to `**http://yoursite.com**` (explicit HTTP)
3. Confirm the address bar shows `**https://**` after redirect
4. Run `**curl -I http://yoursite.com**` and verify 301/308 response
5. Run Lighthouse - "Redirects HTTP traffic to HTTPS" should pass

Check redirect chain efficiency:

```bash
curl -ILs http://yoursite.com | grep -E "^HTTP | ^Location"
```

You should see exactly one redirect from HTTP to HTTPS, not multiple hops.

## Common Mistakes

- **Redirect loops**: Misconfigured load balancers or CDNs cause infinite redirects. If your app checks `**X-Forwarded-Proto**` but the header isn't set, it keeps redirecting. Verify your CDN/proxy forwards the protocol header correctly.
- **Missing www handling**: Redirect both `**http://yoursite.com**` AND `**http://www.yoursite.com**`. Users might access either.
- **302 instead of 301**: Use 301 (permanent) or 308 (permanent, preserves method) redirects. 302 (temporary) doesn't tell browsers to update bookmarks or caches.
- **Forgetting subdomains**: Each subdomain needs its own redirect configuration. An HTTPS redirect on `**yoursite.com**` doesn't cover `**api.yoursite.com**` or `**blog.yoursite.com**`.
- **Starting with aggressive HSTS**: Begin with a short `**max-age**` (like 300 seconds) and increase after confirming everything works. A misconfigured HSTS with a year-long max-age locks users out.

### 2025 Insight: Soft 404s & Status Codes

While not strictly a redirect issue, "Soft 404s" (pages that say "Not Found" but return a `**200 OK**` status) are a primary waste of crawl budget in 2025. Google's bots now aggressively deprioritize sites with poor status code integrity. Make sure your 404 pages return a `**404**` status header.

## Related Issues

HTTP redirect issues often appear alongside:

- [**~~HTTPS~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/is-on-https) - Both involve secure connections
- [**~~Redirects (LCP)~~**](https://unlighthouse.dev/learn-lighthouse/lcp/redirects) - HTTP→HTTPS redirects also affect LCP
- [**~~bfcache~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/bf-cache) - Redirect behavior affects back/forward cache

## Test Your Entire Site

HTTP redirect issues can affect some subdomains or paths but not others - especially with complex hosting setups or multiple servers. Scan your entire domain to check that every entry point redirects users to a secure connection.

### **Related **

[**All Best Practices Issues**](https://unlighthouse.dev/learn-lighthouse/best-practices#all-best-practices-issues) [**Best Practices Overview**](https://unlighthouse.dev/learn-lighthouse/best-practices)

[**Paste Inputs** Stop preventing users from pasting into input fields. Blocking paste breaks password managers and frustrates users without improving security.](https://unlighthouse.dev/learn-lighthouse/best-practices/paste-preventing-inputs) [**Charset Declaration** Properly declare character encoding to prevent text rendering issues and security vulnerabilities.](https://unlighthouse.dev/learn-lighthouse/best-practices/charset)

**On this page **

- [What's Happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Verify the Fix](#verify-the-fix)
- [Common Mistakes](#common-mistakes)
- [Related Issues](#related-issues)
- [Test Your Entire Site](#test-your-entire-site)

---

- **Page:** Fix Notification Request on Page Load · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/best-practices/notification-on-start
- **Description:** Stop requesting notification permission on page load. Users dismiss these prompts reflexively - wait for a user action that shows they want notifications.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Notification Request on Page Load**

Stop requesting notification permission on page load. Users dismiss these prompts reflexively - wait for a user action that shows they want notifications.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)3 min read Published **Jan 18, 2025**

Nothing says "desperate" like a notification prompt the instant someone opens your site. Users don't know you yet, don't trust you, and will click Block without thinking. Now your notification features are dead for that user forever.

## What's Happening

Your code calls `**Notification.requestPermission()**` during page load - before the user has expressed any interest in receiving notifications. The browser shows a permission prompt, the user blocks it reflexively, and that decision persists until they manually dig through browser settings to reverse it.

Chrome has started hiding these prompts for sites that abuse them. Your notification request might not even be shown anymore if your site has a poor grant rate.

## SEO Impact 2025

"Searcher Engagement" is now a top-tier ranking factor (weighted at **12%**). Intrusive interstitials, like immediate permission prompts, cause "pogo-sticking" (users immediately bouncing back to search results). Google's algorithm detects this pattern and demotes sites that frustrate users within seconds of loading.

## Diagnose

### DevTools Console

Check the Lighthouse audit details for the exact source location. To find it manually:

1. Open DevTools > Sources
2. Search all files ( `**Cmd/Ctrl+Shift+F**`) for `**Notification.requestPermission**` or `**pushManager.subscribe**`
3. Check if calls are inside event handlers (good) or running automatically (bad)

### Patterns That Trigger This

```js
// Bad: Runs immediately
Notification.requestPermission()

// Bad: Runs on page load
document.addEventListener('DOMContentLoaded', () => {
  Notification.requestPermission()
})

// Bad: In module top-level
if (Notification.permission === 'default') {
  Notification.requestPermission()
}

// Bad: Auto-runs after slight delay
setTimeout(() => Notification.requestPermission(), 3000)
```

## Fix

### 1. Request After User Action

Move the permission request inside a user-triggered event:

**Before (bad):**

```js
// Runs on page load
Notification.requestPermission().then((permission) => {
  if (permission === 'granted') {
    subscribeToNotifications()
  }
})
```

**After (good):**

```js
document.querySelector('#enable-notifications').addEventListener('click', () => {
  Notification.requestPermission().then((permission) => {
    if (permission === 'granted') {
      subscribeToNotifications()
      updateButtonState('enabled')
    }
    else {
      updateButtonState('denied')
    }
  })
})
```

The user clicks a button that says "Enable notifications," the browser prompt appears, and context is clear.

### 2. Explain Value Before Asking

Show users what they'll get before triggering the browser prompt:

```js
const notifyBtn = document.querySelector('#notify-toggle')

notifyBtn.addEventListener('click', async () => {
  const permission = Notification.permission

  if (permission === 'granted') {
    // Already enabled, maybe show settings
    showNotificationSettings()
  }
  else if (permission === 'denied') {
    // Blocked - explain how to unblock
    showUnblockInstructions()
  }
  else {
    // Show our own explainer first
    showNotificationExplainer()
  }
})

function showNotificationExplainer() {
  const modal = document.querySelector('#notification-explainer')
  modal.innerHTML = `
    <h3>Get notified when:</h3>
    <ul>
      <li>Your order ships</li>
      <li>Someone replies to your comment</li>
      <li>There's a flash sale</li>
    </ul>
    <button id="confirm-notify">Enable Notifications</button>
    <button id="skip-notify">Not Now</button>
  `
  modal.showModal()

  modal.querySelector('#confirm-notify').addEventListener('click', () => {
    modal.close()
    Notification.requestPermission().then(handlePermissionResult)
  }, { once: true })
}
```

### 3. Wait for Engagement

Request after the user has shown investment in your site:

```js
// Only show notification option after user has engaged
let userEngaged = false

function checkEngagement() {
  // User has been on site 2+ minutes, or completed an action
  const timeOnSite = Date.now() - pageLoadTime
  const hasInteracted = purchaseComplete || commentPosted || signedUp

  if (timeOnSite > 120000 || hasInteracted) {
    userEngaged = true
    showNotificationPrompt()
  }
}

function showNotificationPrompt() {
  if (Notification.permission !== 'default')
    return

  // Show soft prompt, not browser prompt
  const banner = document.querySelector('#notification-banner')
  banner.classList.remove('hidden')

  banner.querySelector('#enable-btn').addEventListener('click', () => {
    Notification.requestPermission()
    banner.classList.add('hidden')
  }, { once: true })
}
```

## Verify the Fix

1. Clear site data (DevTools > Application > Clear site data)
2. Reload the page
3. No permission prompt should appear automatically
4. Navigate around, scroll, read content - still no prompt
5. Click the notification enable button
6. Now the browser prompt appears

Run Lighthouse - the "Requests the notification permission on page load" audit should pass.

## Common Mistakes

- **Using a short delay** - `**setTimeout(() => Notification.requestPermission(), 5000)**` still runs automatically. Five seconds isn't user engagement; it's slower annoyance.
- **Checking permission then auto-requesting** - "If not denied, request" is still automatic. The user must take action.
- **Third-party chat widgets** - Some live chat and support widgets request notification permission automatically. Check their configuration for a "request on user interaction" option.
- **Service worker auto-subscribe** - Some push notification libraries subscribe automatically. Configure them to wait for explicit opt-in.

### **Related **

[**Geolocation Permission**](https://unlighthouse.dev/learn-lighthouse/best-practices/geolocation-on-start) [**Best Practices Overview**](https://unlighthouse.dev/learn-lighthouse/best-practices)

[**HTTPS** Eliminate insecure HTTP requests and mixed content warnings. Learn to enforce HTTPS across your entire site for security and modern web features.](https://unlighthouse.dev/learn-lighthouse/best-practices/is-on-https) [**Paste Inputs** Stop preventing users from pasting into input fields. Blocking paste breaks password managers and frustrates users without improving security.](https://unlighthouse.dev/learn-lighthouse/best-practices/paste-preventing-inputs)

**On this page **

- [What's Happening](#whats-happening)
- [SEO Impact 2025](#seo-impact-2025)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Verify the Fix](#verify-the-fix)
- [Common Mistakes](#common-mistakes)

---

- **Page:** Fix charset declaration · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/best-practices/charset
- **Description:** Properly declare character encoding to prevent text rendering issues and security vulnerabilities.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix charset declaration**

Properly declare character encoding to prevent text rendering issues and security vulnerabilities.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)3 min read Published **Jan 18, 2025**

A missing or late charset declaration forces browsers to guess your page's encoding. This causes garbled text, broken layouts, and security vulnerabilities.

## What's happening

Character encoding tells the browser how to interpret bytes as text. Without it, browsers guess and often fail. Special characters, emojis, and non-ASCII text render as garbage like `**’**` instead of `**'**`.

Charset sniffing is a security hole. Attackers bypass XSS filters by crafting payloads that browsers misinterpret as different encodings. Lighthouse requires the charset declaration within the first 1024 bytes of HTML.

The browser checks three places for charset:

1. HTTP `**Content-Type**` header with charset parameter.
2. `**<meta charset="UTF-8">**` in the first 1024 bytes.
3. Byte Order Mark (BOM) at the start of the file.

If none of these exist or they appear too late, you fail this audit.

## Diagnose

### Check your HTML source

View page source and look for a charset declaration in the `**<head>**`:

```html
<!-- Good: meta charset in first 1024 bytes -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
```

Place `**<meta charset>**` as the first element in `**<head>**`.

### Check HTTP headers

In DevTools Network tab:

1. Select the main document request.
2. Look at Response Headers for `**Content-Type**`.
3. It must include charset: `**Content-Type: text/html; charset=UTF-8**`.

Or via command line:

```bash
curl -I https://your-site.com | grep -i content-type
```

### Count bytes

If you have a long `**<head>**` before the charset, verify it's within 1024 bytes:

```bash
curl -s https://your-site.com | head -c 1024 | grep -i charset
```

## Fix

### 1. Add meta charset tag

Place the charset declaration first in `**<head>**`:

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Page Title</title>
  <!-- other head elements -->
</head>
```

Use UTF-8. It supports all languages and characters.

### 2. Set HTTP header (server-side)

Configure your server to send the charset in the Content-Type header. Browsers process this before parsing the HTML.

**Nginx**:

```nginx
http {
  charset utf-8;
  charset_types text/html text/css application/javascript;
}
```

**Apache** (.htaccess):

```apache
AddDefaultCharset UTF-8
```

**Express/Node.js**:

```js
app.use((req, res, next) => {
  res.setHeader('Content-Type', 'text/html; charset=UTF-8')
  next()
})
```

**Cloudflare Workers / Edge Functions**:

```js
async function handleRequest() {
  return new Response(html, {
    headers: {
      'Content-Type': 'text/html; charset=UTF-8',
    },
  })
}
```

### 3. Move charset earlier in document

Move charset first if you have too much content before it.

```html
<!-- Bad: charset buried after 1200 bytes of inline scripts -->
<head>
  <script>/* 800 bytes of tracking code */</script>
  <script>/* 600 bytes more */</script>
  <meta charset="UTF-8">
</head>

<!-- Good: charset first -->
<head>
  <meta charset="UTF-8">
  <script>/* tracking code */</script>
  <script>/* more scripts */</script>
</head>
```

## Verify the fix

1. View page source and confirm `**<meta charset="UTF-8">**` appears within the first few lines of `**<head>**`.
2. Check Network tab for `**Content-Type: text/html; charset=UTF-8**` header.
3. Run Lighthouse and confirm "Properly defines charset" audit passes.
4. Test pages with special characters (emojis, accented letters) to make sure they render correctly.

## Common mistakes

- **Using http-equiv instead of charset**: Legacy formats like `**<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">**` are verbose. Use `**<meta charset="UTF-8">**`.
- **Placing charset after title or other meta**: The charset must be early enough for the browser to read it before parsing text content. Put it first in `**<head>**`.
- **Wrong case for charset value**: Use `**UTF-8**`. It is the canonical form.
- **Mixing encodings**: Make sure your editor saves files as UTF-8. If your file is saved as ISO-8859-1 but you declare UTF-8, characters will break.
- **Large inline scripts before charset**: The 1024-byte limit is firm. Move large inline scripts to external files or after the charset declaration.

## Test your entire site

Different templates use different `**<head>**` structures. Scan your entire site to check that all pages declare charset correctly.

[Scan Your Site with Unlighthouse](https://unlighthouse.dev/)

### **Related **

[**All Best Practices Issues**](https://unlighthouse.dev/learn-lighthouse/best-practices) [**Fix HTML Doctype**](https://unlighthouse.dev/learn-lighthouse/best-practices/doctype)

[**HTTP Redirect** Configure your server to redirect all HTTP traffic to HTTPS. Protect users and enable secure web features across your entire site.](https://unlighthouse.dev/learn-lighthouse/best-practices/redirects-http) [**Deprecated APIs** Replace deprecated browser APIs before they are removed. Covers document.domain, Event.path, keyCode, and sync XHR.](https://unlighthouse.dev/learn-lighthouse/best-practices/deprecations)

**On this page **

- [What's happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix deprecated browser APIs · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/best-practices/deprecations
- **Description:** Replace deprecated browser APIs before they are removed. Covers document.domain, Event.path, keyCode, and sync XHR.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix deprecated browser APIs**

Replace deprecated browser APIs before they are removed. Covers document.domain, Event.path, keyCode, and sync XHR.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)3 min read Published **Jan 18, 2025**

Your code uses browser APIs scheduled for removal. When browsers drop support, your site breaks. Fix them now.

## What's happening

Browsers deprecate APIs when better alternatives exist or the API poses security risks. Deprecated APIs work for a grace period but eventually get removed. Lighthouse monitors Chrome's deprecation warnings to catch these early.

Chrome logs a warning when JavaScript calls a deprecated API. Lighthouse collects these warnings and fails the audit. Legacy DOM methods, outdated security APIs, and obsolete media features are common culprits.

## Diagnose

### Check DevTools Console

1. Open DevTools (F12) and go to the Console tab.
2. Look for yellow warnings mentioning "deprecated."
3. Click the warning to see the source location.

Typical deprecation warnings look like:

```text
[Deprecation] 'window.webkitStorageInfo' is deprecated. Please use 'navigator.storage' instead.
[Deprecation] Synchronous XMLHttpRequest on the main thread is deprecated.
[Deprecation] 'document.domain' setter is deprecated.
```

### Run Lighthouse

The Lighthouse "Uses deprecated APIs" audit lists each deprecation with:

- The deprecated API or feature.
- The source file and line number.
- Links to documentation about the replacement.

### Search your codebase

Search your code for flagged APIs:

```bash
grep -r "webkitStorageInfo" --include="*.js" src/
grep -r "document.domain" --include="*.js" src/
```

## Fix

### 1. Identify the modern replacement

Each deprecated API has a replacement. Use these fixes for common deprecations:

**`**document.domain**` setter**:

```js
// Deprecated: relaxing same-origin policy
document.domain = 'example.com'

// Modern: use postMessage for cross-origin communication
window.parent.postMessage(data, 'https://example.com')
```

**Synchronous XMLHttpRequest**:

```js
// Deprecated: blocks main thread
const xhr = new XMLHttpRequest()
xhr.open('GET', '/api', false) // sync = false is deprecated

// Modern: use async fetch or XHR
async function fetchData() {
  const response = await fetch('/api')
  const data = await response.json()
  return data
}
```

**`**webkitStorageInfo**`**:

```js
// Deprecated: webkit-prefixed storage API
// window.webkitStorageInfo.queryUsageAndQuota(...)

// Modern: Storage API
async function getStorage() {
  const estimate = await navigator.storage.estimate()
  console.log(`Using ${estimate.usage} of ${estimate.quota} bytes`)
}
```

**`**Event.path**`**:

```js
// Deprecated: non-standard event property
const path = event.path || (event.composedPath && event.composedPath())

// Modern: use composedPath()
const modernPath = event.composedPath()
```

**`**KeyboardEvent.keyCode**`**:

```js
// Deprecated: numeric key codes
if (event.keyCode === 13) { /* Enter */ }

// Modern: use key property
if (event.key === 'Enter') { /* Enter */ }
```

### 2. Handle third-party dependencies

If deprecation warnings come from third-party scripts:

```bash
# Check if the issue is from node_modules
# Lighthouse shows source file paths in the audit

# Option 1: Update the dependency
npm update problematic-package

# Option 2: Find an alternative package
npm uninstall old-package
npm install modern-alternative

# Option 3: If it's a CDN script, check for newer versions
```

### 3. Polyfill during transition

Polyfill the API to suppress warnings while you plan the migration if you can't replace it immediately.

```js
// Temporary polyfill for Event.path
if (!Event.prototype.composedPath) {
  Event.prototype.composedPath = function () {
    const path = []
    let el = this.target
    while (el) {
      path.push(el)
      el = el.parentElement
    }
    path.push(document, window)
    return path
  }
}
```

Polyfills mask the problem but don't solve it. Plan a proper migration. Never rely on polyfills long-term.

## Verify the fix

1. Clear browser cache and reload the page.
2. Open DevTools Console and confirm no deprecation warnings appear.
3. Run Lighthouse and verify "Avoids deprecated APIs" audit passes.
4. Test affected functionality with the new APIs.
5. If you updated dependencies, run your test suite.

## Common mistakes

- **Ignoring third-party scripts**: Deprecation warnings from analytics, widgets, or ads fail the audit. Update vendors or find alternatives.
- **Only fixing in development**: Production bundles use different code paths. Test with production builds.
- **Using deprecated APIs in feature detection**: Checking `**if (window.webkitStorageInfo)**` can trigger deprecation warnings.
- **Assuming deprecation means broken**: Deprecated APIs work until they don't. They will break in a future browser update.
- **Not checking polyfill sources**: Some polyfill libraries use deprecated APIs. Audit your dependencies.

## Test your entire site

Different pages load different scripts. A full site scan catches deprecations across all your JavaScript.

[Scan Your Site with Unlighthouse](https://unlighthouse.dev/)

### **Related **

[**All Best Practices Issues**](https://unlighthouse.dev/learn-lighthouse/best-practices) [**MDN Deprecated Features**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Deprecated_and_obsolete_features)

[**Charset Declaration** Properly declare character encoding to prevent text rendering issues and security vulnerabilities.](https://unlighthouse.dev/learn-lighthouse/best-practices/charset) [**HTML Doctype** Learn why your page needs a proper HTML doctype and how quirks mode breaks your layout and CSS.](https://unlighthouse.dev/learn-lighthouse/best-practices/doctype)

**On this page **

- [What's happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix Missing HTML Doctype for Better Best Practices Score · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/best-practices/doctype
- **Description:** Learn why your page needs a proper HTML doctype and how quirks mode breaks your layout and CSS.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Missing HTML Doctype for Better Best Practices Score**

Learn why your page needs a proper HTML doctype and how quirks mode breaks your layout and CSS.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)3 min read Published **Jan 18, 2025**

Without a proper doctype, browsers render your page in quirks mode - a legacy compatibility mode that breaks modern CSS and causes unpredictable layout behavior.

## What's Happening

The doctype declaration tells browsers which version of HTML your document uses. When it's missing or incorrect, browsers fall back to quirks mode, which emulates old browser bugs from the early 2000s. This means your carefully crafted CSS won't behave as expected - box models calculate differently, table layouts break, and modern features may not work at all.

Lighthouse flags this under "Page lacks the HTML doctype, thus triggering quirks-mode" when your document either has no doctype, uses an outdated doctype format, or includes unnecessary public/system identifiers.

## Diagnose

### Check Document Source

View your page source (Ctrl+U / Cmd+U) and look at the first line. It should be exactly:

```html
<!DOCTYPE html>
```

If you see any of these, you have a problem:

```html
<!-- Missing entirely - no doctype at the top -->

<!-- Old HTML 4.01 doctype (triggers limited-quirks) -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

<!-- XHTML doctype -->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
```

### Check Compatibility Mode in DevTools

1. Open DevTools (F12)
2. Go to Console
3. Run: `**document.compatMode**`
4. If it returns `**"BackCompat"**`, you're in quirks mode
5. `**"CSS1Compat"**` means standards mode (correct)

## Fix

### 1. Add the HTML5 Doctype

Place this as the absolute first line of your HTML document - before any whitespace, comments, or other content:

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <!-- rest of head -->
</head>
```

The doctype must be:

- Exactly `**<!DOCTYPE html>**` (case-insensitive, but lowercase is conventional)
- No public ID
- No system ID
- Nothing before it in the document

### 2. Fix Server-Side Template Issues

If your doctype is correct in your source but missing in the rendered HTML, check your server-side templates.

**PHP**: Check for no output before the doctype:

```php
<?php
// Bad: whitespace before PHP tag causes output
?>
<!DOCTYPE html>
```

```php
<?php // Good: no whitespace before doctype ?>
<!DOCTYPE html>
```

**Express/Node.js**: Watch for BOM or whitespace in template files:

```js
// If using template literals, watch for leading whitespace
const html = `<!DOCTYPE html>
<html>...</html>`
```

**Static Site Generators**: Check your base layout or template file. The doctype should be in your root layout, not repeated in partials.

### 3. Handle Dynamic Content

For single-page applications that manipulate the DOM, make sure the initial HTML shell includes the doctype:

```html
<!-- public/index.html or equivalent -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>App</title>
</head>
<body>
  <div id="app"></div>
  <script src="/app.js"></script>
</body>
</html>
```

## Verify the Fix

1. View page source and confirm `**<!DOCTYPE html>**` is on line 1
2. Open DevTools Console and run `**document.compatMode**` - should return `**"CSS1Compat"**`
3. Run Lighthouse and confirm the "Page has the HTML doctype" audit passes
4. Check your layouts still render correctly (quirks mode may have been masking CSS issues)

## Common Mistakes

- **Whitespace before doctype**: Even a single blank line or space before `**<!DOCTYPE html>**` triggers quirks mode in some browsers. Use your editor to verify there's no invisible BOM character.
- **Copying old doctypes from legacy code**: HTML 4.01 and XHTML doctypes include public/system identifiers that trigger limited-quirks mode. Replace them with the simple HTML5 doctype.
- **PHP/ASP output before doctype**: Server-side scripts that output content (including whitespace or error messages) before the doctype will break standards mode.
- **Incorrect case or typos**: While browsers are forgiving about case, typos like `**<!DOCTYP html>**` or `**<!DOCTYPE htm>**` will fail.

## Test Your Entire Site

A missing doctype on one template can affect all pages using that layout. Scan your entire site to catch doctype issues across all routes.

[Scan Your Site with Unlighthouse](https://unlighthouse.dev/)

### **Related **

[**All Best Practices Issues**](https://unlighthouse.dev/learn-lighthouse/best-practices) [**Fix Charset Declaration**](https://unlighthouse.dev/learn-lighthouse/best-practices/charset)

[**Deprecated APIs** Replace deprecated browser APIs before they are removed. Covers document.domain, Event.path, keyCode, and sync XHR.](https://unlighthouse.dev/learn-lighthouse/best-practices/deprecations) [**Console Errors** Identify and resolve browser console errors. Clean up JavaScript exceptions, failed network requests, and deprecation warnings affecting your site.](https://unlighthouse.dev/learn-lighthouse/best-practices/errors-in-console)

**On this page **

- [What's Happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Verify the Fix](#verify-the-fix)
- [Common Mistakes](#common-mistakes)
- [Test Your Entire Site](#test-your-entire-site)

---

- **Page:** Fix Console Errors for Better Best Practices Score · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/best-practices/errors-in-console
- **Description:** Identify and resolve browser console errors. Clean up JavaScript exceptions, failed network requests, and deprecation warnings affecting your site.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Console Errors for Better Best Practices Score**

Identify and resolve browser console errors. Clean up JavaScript exceptions, failed network requests, and deprecation warnings affecting your site.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)3 min read Published **Jan 18, 2025**

Your page logs errors to the browser console, indicating unresolved problems that may affect functionality or user experience.

## What's Happening

Lighthouse scans the browser console for error-level messages during page load. These errors come from JavaScript exceptions, failed network requests, CORS issues, deprecated API usage, or security policy violations. Each error represents something broken or misconfigured.

Console errors signal problems users might experience - broken features, missing content, or degraded performance. Even if the page appears to work, these errors often indicate edge cases where things fail.

**2025 Metric Watch:** "Engagement Reliability (ER)" is a new Core Web Vital metric tracking interaction consistency. Console errors often correlate with "fragile" interactions - buttons that work *most* of the time but fail under race conditions. High error rates will drag down your ER score.

## Diagnose

### Chrome DevTools

1. Open DevTools (F12) and go to the **Console** tab
2. Refresh the page and watch for red error messages
3. Filter by "Errors" using the dropdown to hide warnings and info
4. Click error messages to see stack traces and source locations

### Common Error Types

**JavaScript Runtime Errors:**

```text
Uncaught TypeError: Cannot read properties of undefined (reading 'map')
    at ProductList.js:42
```

**Failed Network Requests:**

```text
GET https://api.example.com/data 404 (Not Found)
```

**CORS Errors:**

```text
Access to fetch at 'https://api.example.com' from origin 'https://yoursite.com'
has been blocked by CORS policy
```

**Content Security Policy Violations:**

```text
Refused to execute inline script because it violates the following
Content Security Policy directive: "script-src 'self'"
```

## Fix

### 1. Fix JavaScript Runtime Errors

These are bugs in your code. The stack trace points to the source.

**Null/Undefined Access:**

```js
// Before - crashes if user.profile is undefined
const oldName = user.profile.name

// After - defensive access
const name = user?.profile?.name ?? 'Anonymous'
```

**Array on Non-Array:**

```js
// Before - crashes if data isn't an array
const oldItems = data.map(item => item.id)

// After - check that array exists
const items = Array.isArray(data) ? data.map(item => item.id) : []
```

**Missing DOM Elements:**

```js
// Before - crashes if element doesn't exist
document.getElementById('app').innerHTML = content

// After - check element exists
const app = document.getElementById('app')
if (app)
  app.innerHTML = content
```

### 2. Fix Failed Network Requests

404 and 500 errors indicate missing or broken resources.

**Missing Assets:**

- Check if the file exists at the expected path
- Verify the build process includes the asset
- Update references if files were renamed or moved

**API Failures:**

- Verify the API endpoint exists and is accessible
- Check authentication tokens haven't expired
- Handle error responses gracefully:

```js
async function fetchData() {
  const response = await fetch('/api/data')
  if (!response.ok) {
    console.warn(`API returned ${response.status}`)
    return fallbackData
  }
  return response.json()
}
```

### 3. Fix CORS Errors

Cross-origin requests fail without proper server configuration.

**Server-Side Fix (API server):**

```js
// Express.js
app.use((req, res, next) => {
  res.header('Access-Control-Allow-Origin', 'https://yoursite.com')
  res.header('Access-Control-Allow-Methods', 'GET, POST, OPTIONS')
  res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization')
  next()
})
```

```nginx
add_header Access-Control-Allow-Origin "https://yoursite.com";
add_header Access-Control-Allow-Methods "GET, POST, OPTIONS";
```

**If You Don't Control the API:**

- Use a backend proxy to make the request server-side
- Check if the API offers JSONP or a CORS-enabled endpoint

### 4. Fix Third-Party Script Errors

Errors from external scripts (analytics, widgets, ads) still count against your page.

**Ad Blocker Errors:** Lighthouse ignores `**ERR_BLOCKED_BY_CLIENT**` by default, but other blocking patterns might slip through.

**Outdated Third-Party Scripts:**

```html
<!-- Check for newer versions -->
<script src="https://cdn.example.com/widget-v2.js"></script>
```

**Missing Fallbacks:**

```js
// Handle missing third-party gracefully
if (typeof ThirdPartyWidget !== 'undefined') {
  ThirdPartyWidget.init()
}
```

### 5. Fix Deprecation and CSP Errors

**Deprecated APIs:** Update code using deprecated browser features. The console message typically suggests the replacement:

```text
[Deprecation] SharedArrayBuffer requires cross-origin isolation.
```

**CSP Violations:** Adjust your Content Security Policy or fix the code violating it:

```html
<!-- Instead of inline scripts -->
<script>doSomething()</script>

<!-- Use external files -->
<script src="/js/init.js"></script>
```

## Verify the Fix

1. Clear browser cache and refresh the page
2. Check Console tab with "Errors" filter - should be empty
3. Navigate through key user flows to trigger any interaction-based errors
4. Run Lighthouse - "No browser errors logged to the console" should pass
5. Test in incognito mode to catch issues masked by extensions

## Common Mistakes

- **Swallowing errors silently**: Wrapping everything in empty catch blocks hides problems without fixing them. Log errors to a monitoring service even if you handle them gracefully.
- **Only testing locally**: Production environments have different API URLs, CDN configurations, and CSP policies. Errors might only appear in production.
- **Ignoring intermittent errors**: Race conditions and timing issues cause errors that don't reproduce consistently. Use error monitoring tools to catch these in real user sessions.
- **Fixing symptoms not causes**: Adding null checks everywhere masks architectural problems. If data is frequently undefined, fix the data flow rather than patching every access point.

## Related Issues

Console error issues often appear alongside:

- [**~~Deprecated APIs~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/deprecations) - Deprecated APIs often log warnings before becoming errors
- [**~~DevTools Issues~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/inspector-issues) - Other browser-detected problems
- [**~~HTTPS~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/is-on-https) - Mixed content warnings appear in console

## Test Your Entire Site

Console errors often hide on specific pages - a contact form with a broken validation script, a product page referencing missing images, or an admin section with outdated dependencies. Scan every page to find errors across your entire application.

### **Related **

[**All Best Practices Issues**](https://unlighthouse.dev/learn-lighthouse/best-practices#all-best-practices-issues) [**Best Practices Overview**](https://unlighthouse.dev/learn-lighthouse/best-practices)

[**HTML Doctype** Learn why your page needs a proper HTML doctype and how quirks mode breaks your layout and CSS.](https://unlighthouse.dev/learn-lighthouse/best-practices/doctype) [**Geolocation** Stop requesting geolocation permission on page load. Users distrust sites that ask for location without context - tie requests to user actions instead.](https://unlighthouse.dev/learn-lighthouse/best-practices/geolocation-on-start)

**On this page **

- [What's Happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Verify the Fix](#verify-the-fix)
- [Common Mistakes](#common-mistakes)
- [Related Issues](#related-issues)
- [Test Your Entire Site](#test-your-entire-site)

---

- **Page:** Fix Geolocation Request on Page Load · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/best-practices/geolocation-on-start
- **Description:** Stop requesting geolocation permission on page load. Users distrust sites that ask for location without context - tie requests to user actions instead.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Geolocation Request on Page Load**

Stop requesting geolocation permission on page load. Users distrust sites that ask for location without context - tie requests to user actions instead.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)3 min read Published **Jan 18, 2025**

Requesting location permission the moment someone lands on your page is the fastest way to get denied. Users don't trust sites that ask for sensitive permissions without context.

## What's Happening

Your JavaScript calls `**navigator.geolocation.getCurrentPosition()**` or `**navigator.geolocation.watchPosition()**` during page load - before the user has done anything that suggests they want location features. The browser shows a permission prompt immediately, the user reflexively clicks "Block," and now your location features are permanently broken for that visitor.

Lighthouse flags this because it's both bad UX and counterproductive. Studies show permission grant rates drop significantly when prompts appear without context.

## Diagnose

### DevTools Console

Lighthouse reports the source location in the audit details. You can also find it manually:

1. Open DevTools > Sources
2. Search all files ( `**Cmd/Ctrl+Shift+F**`) for `**geolocation**`
3. Look for calls to `**getCurrentPosition**` or `**watchPosition**`
4. Check if they're inside event handlers (good) or top-level/immediately invoked (bad)

### Common Patterns That Trigger This

```js
// Bad: Runs on script load
navigator.geolocation.getCurrentPosition((pos) => {
  console.log(pos.coords)
})

// Bad: Runs immediately when module loads
const position = await new Promise((resolve) => {
  navigator.geolocation.getCurrentPosition(resolve)
})

// Bad: Inside DOMContentLoaded or load event
window.addEventListener('load', () => {
  navigator.geolocation.getCurrentPosition(handlePosition)
})
```

## Fix

### 1. Request After User Action

Move geolocation requests inside user-triggered event handlers:

**Before (bad):**

```js
// Runs on page load
navigator.geolocation.getCurrentPosition(
  position => showNearbyStores(position.coords),
  error => console.error(error)
)
```

**After (good):**

```js
document.querySelector('#find-stores-btn').addEventListener('click', () => {
  navigator.geolocation.getCurrentPosition(
    position => showNearbyStores(position.coords),
    error => showLocationError(error)
  )
})
```

The user clicks "Find stores near me," the prompt appears, and they understand why you're asking.

### 2. Show a Pre-Permission Prompt

For better UX, explain before the browser prompt appears:

```js
const locationBtn = document.querySelector('#use-location')

locationBtn.addEventListener('click', async () => {
  // Check current permission state
  const permission = await navigator.permissions.query({ name: 'geolocation' })

  if (permission.state === 'granted') {
    // Already have permission, proceed
    getLocation()
  }
  else if (permission.state === 'prompt') {
    // Show custom UI explaining why
    showLocationExplainer()
  }
  else {
    // Denied - show alternative
    showManualLocationInput()
  }
})

function showLocationExplainer() {
  const modal = document.querySelector('#location-explainer')
  modal.showModal()

  modal.querySelector('#confirm-location').addEventListener('click', () => {
    modal.close()
    getLocation()
  }, { once: true })
}

function getLocation() {
  navigator.geolocation.getCurrentPosition(
    position => handleSuccess(position.coords),
    error => handleError(error)
  )
}
```

### 3. Provide a Fallback

Always have a non-location path:

```js
function initStoreLocator() {
  // Default: show all stores or ask for zip code
  showAllStores()

  // Enhance with location button
  const locationBtn = document.querySelector('#use-my-location')
  locationBtn.addEventListener('click', requestLocation)
}

function requestLocation() {
  navigator.geolocation.getCurrentPosition(
    pos => filterStoresByProximity(pos.coords),
    () => showZipCodeInput() // Fallback on denial/error
  )
}
```

## Verify the Fix

1. Clear site data (DevTools > Application > Clear site data)
2. Reload the page
3. No permission prompt should appear
4. Interact with the feature that needs location
5. Now the prompt should appear

Run Lighthouse again - the "Requests the geolocation permission on page load" audit should pass.

## Common Mistakes

- **Moving to DOMContentLoaded** - Still runs automatically, still bad. The user must *do* something first.
- **Using setTimeout to delay** - `**setTimeout(() => { geolocation... }, 5000)**` is still automatic. Lighthouse may not catch it, but users will still see an unexplained prompt.
- **Checking permissions then requesting** - Even `**navigator.permissions.query()**` followed by an automatic request is wrong. The permission check is fine; the automatic request isn't.
- **Third-party scripts** - Analytics or mapping libraries request location on load. Check your dependencies and configure them to defer location requests.

## Test Your Entire Site

Location requests might be buried in a script that only loads on certain pages. [**~~Unlighthouse~~**](https://unlighthouse.dev/) scans every page on your site and flags any that trigger geolocation requests on load.

### **Related **

[**Notification Permission**](https://unlighthouse.dev/learn-lighthouse/best-practices/notification-on-start) [**Best Practices Overview**](https://unlighthouse.dev/learn-lighthouse/best-practices)

[**Console Errors** Identify and resolve browser console errors. Clean up JavaScript exceptions, failed network requests, and deprecation warnings affecting your site.](https://unlighthouse.dev/learn-lighthouse/best-practices/errors-in-console) [**Image Aspect Ratio** Display images with their natural aspect ratio to prevent distortion. Stretched or squished images look unprofessional.](https://unlighthouse.dev/learn-lighthouse/best-practices/image-aspect-ratio)

**On this page **

- [What's Happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Verify the Fix](#verify-the-fix)
- [Common Mistakes](#common-mistakes)
- [Test Your Entire Site](#test-your-entire-site)

---

- **Page:** Fix Incorrect Image Aspect Ratio for Better Best Practices Score · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/best-practices/image-aspect-ratio
- **Description:** Display images with their natural aspect ratio to prevent distortion. Stretched or squished images look unprofessional.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Incorrect Image Aspect Ratio for Better Best Practices Score**

Display images with their natural aspect ratio to prevent distortion. Stretched or squished images look unprofessional.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)3 min read Published **Jan 18, 2025**

When an image's display dimensions don't match its natural aspect ratio, it gets stretched or squished. Faces look wrong. Products look unprofessional. Users notice.

## What's Happening

You have an image with natural dimensions of 1200x800 (aspect ratio 1.5:1), but you're displaying it at 400x400 (aspect ratio 1:1). The browser has three choices: stretch it, squish it, or crop/contain it. Without explicit `**object-fit**` instructions, it stretches.

Lighthouse compares the displayed aspect ratio to the natural aspect ratio. If they differ by more than a couple pixels (accounting for rounding), the audit fails. It only checks images using `**object-fit: fill**` (the default) because other values intentionally override aspect ratio behavior.

## Diagnose

### Chrome DevTools

1. Right-click the distorted image, select **Inspect**
2. Check the element's rendered dimensions vs natural dimensions:

```js
// Select the image element first
const img = $0
console.log({
  natural: `${img.naturalWidth}x${img.naturalHeight}`,
  displayed: `${img.clientWidth}x${img.clientHeight}`,
  naturalRatio: (img.naturalWidth / img.naturalHeight).toFixed(2),
  displayedRatio: (img.clientWidth / img.clientHeight).toFixed(2)
})
```

If the ratios don't match, that's your problem.

### Find All Distorted Images

```js
document.querySelectorAll('img').forEach((img) => {
  if (!img.naturalWidth || !img.naturalHeight)
    return
  if (img.clientWidth < 5 || img.clientHeight < 5)
    return

  const naturalRatio = img.naturalWidth / img.naturalHeight
  const displayedRatio = img.clientWidth / img.clientHeight
  const diff = Math.abs(naturalRatio - displayedRatio)

  if (diff > 0.05) {
    console.warn('Aspect ratio mismatch:', img.src, {
      natural: `${img.naturalWidth}x${img.naturalHeight} (${naturalRatio.toFixed(2)})`,
      displayed: `${img.clientWidth}x${img.clientHeight} (${displayedRatio.toFixed(2)})`
    })
  }
})
```

## Fix

### 1. Match Container to Image Ratio

The cleanest fix: make the display dimensions match the natural aspect ratio.

```html
<!-- Image is 1200x800 (1.5:1 ratio) -->
<!-- Bad: forcing into a square -->
<img src="/photo.jpg" style="width: 400px; height: 400px;">

<!-- Good: maintaining ratio -->
<img src="/photo.jpg" style="width: 400px; height: 267px;">

<!-- Better: let height auto-calculate -->
<img src="/photo.jpg" width="1200" height="800" style="width: 400px; height: auto;">
```

With `**width**` and `**height**` attributes, browsers calculate the aspect ratio automatically:

```css
img {
  max-width: 100%;
  height: auto;
}
```

### 2. Use object-fit for Fixed Containers

When you need a specific container size regardless of image ratio, use `**object-fit**`:

```css
.thumbnail {
  width: 200px;
  height: 200px;
  object-fit: cover; /* Crop to fill, maintain ratio */
}

.product-image {
  width: 100%;
  height: 300px;
  object-fit: contain; /* Fit inside, maintain ratio, may letterbox */
}
```

**object-fit values:**

- `**cover**` - Fill container, crop excess (most common for thumbnails)
- `**contain**` - Fit inside container, letterbox if needed
- `**fill**` - Stretch to fill (default, causes distortion)
- `**none**` - Natural size, crop if larger
- `**scale-down**` - Like `**contain**` but never upscales

```html
<div class="avatar">
  <img src="/user.jpg" alt="User" style="width: 100%; height: 100%; object-fit: cover;">
</div>
```

```css
.avatar {
  width: 48px;
  height: 48px;
  border-radius: 50%;
  overflow: hidden;
}
```

### 3. Use aspect-ratio for Responsive Containers

Let CSS maintain the ratio while the container scales:

```css
.video-thumbnail {
  width: 100%;
  aspect-ratio: 16 / 9;
}

.video-thumbnail img {
  width: 100%;
  height: 100%;
  object-fit: cover;
}
```

The container maintains 16:9, and `**object-fit: cover**` handles any image that doesn't match exactly.

### 4. Crop Images at Source

If every image in a gallery should be square, crop them to square before uploading rather than relying on CSS:

```js
// Server-side with Sharp
import sharp from 'sharp'

sharp('input.jpg')
  .resize(400, 400, {
    fit: 'cover',
    position: 'attention' // Smart crop
  })
  .toFile('output-square.jpg')
```

This gives you control over what gets cropped rather than leaving it to CSS.

## Framework Examples

**Nuxt** - Use `**NuxtImg**` with `**fit**` prop:

```html
<template>
  <NuxtImg
    src="/photo.jpg"
    width="400"
    height="400"
    fit="cover"
    alt="Photo"
  />
</template>
```

For containers with fixed aspect ratio:

```html
<div class="aspect-square">
  <NuxtImg src="/photo.jpg" class="w-full h-full object-cover" />
</div>
```

**Next.js** - `**next/image**` with `**fill**` and `**objectFit**`:

```jsx
<div className="relative w-48 h-48">
  <Image
    src="/photo.jpg"
    fill
    style={{ objectFit: 'cover' }}
    alt="Photo"
  />
</div>
```

For responsive with maintained ratio:

```jsx
<Image
  src="/photo.jpg"
  width={1200}
  height={800}
  style={{ width: '100%', height: 'auto' }}
  alt="Photo"
/>
```

## Verify the Fix

1. **Visual check** - Images should look natural, not stretched or squished
2. **Re-run Lighthouse** - "Displays images with correct aspect ratio" should pass
3. **Console check:**

```js
document.querySelectorAll('img').forEach((img) => {
  const style = getComputedStyle(img)
  if (style.objectFit !== 'fill')
    return // Using cover/contain is fine

  const naturalRatio = img.naturalWidth / img.naturalHeight
  const displayedRatio = img.clientWidth / img.clientHeight
  if (Math.abs(naturalRatio - displayedRatio) > 0.05) {
    console.warn('Still distorted:', img.src)
  }
})
```

## Common Mistakes

- **Setting only width** - `**width: 100%**` without `**height: auto**` causes stretching if there's an inherited height.
- **Forgetting object-fit on avatars** - Circle avatars with square images need `**object-fit: cover**` or they'll oval.
- **Wrong width/height attributes** - If your HTML says 400x300 but the image is 1200x800, browsers use the attributes for ratio calculation. Make them match.
- **Background images** - This audit only checks `**<img>**` elements. Distorted background images need `**background-size: cover**` or `**contain**`.

## Test Your Entire Site

Your homepage might look perfect while product pages stretch images into a grid. [**~~Unlighthouse~~**](https://unlighthouse.dev/) checks every page and surfaces all distorted images across your entire site.

### **Related **

[**All Best Practices Issues**](https://unlighthouse.dev/learn-lighthouse/best-practices#all-best-practices-issues) [**Best Practices Overview**](https://unlighthouse.dev/learn-lighthouse/best-practices)

[**Geolocation** Stop requesting geolocation permission on page load. Users distrust sites that ask for location without context - tie requests to user actions instead.](https://unlighthouse.dev/learn-lighthouse/best-practices/geolocation-on-start) [**Low Resolution Images** Serve images with appropriate resolution for the display size and device pixel ratio. Blurry images hurt perceived quality.](https://unlighthouse.dev/learn-lighthouse/best-practices/image-size-responsive)

**On this page **

- [What's Happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Framework Examples](#framework-examples)
- [Verify the Fix](#verify-the-fix)
- [Common Mistakes](#common-mistakes)
- [Test Your Entire Site](#test-your-entire-site)

---

- **Page:** Fix Low Resolution Images for Better Best Practices Score · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/best-practices/image-size-responsive
- **Description:** Serve images with appropriate resolution for the display size and device pixel ratio. Blurry images hurt perceived quality.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Low Resolution Images for Better Best Practices Score**

Serve images with appropriate resolution for the display size and device pixel ratio. Blurry images hurt perceived quality.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)3 min read Published **Jan 18, 2025**

Serving undersized images on high-DPI screens makes your site look amateur. Users notice blurry images even if they can't articulate why something feels "off."

## What's Happening

Your image's natural dimensions are too small for how the browser displays it. On a 2x retina display, an image displayed at 400x300 CSS pixels needs to be at least 800x600 actual pixels to look sharp. When you serve a 400x300 image at that size on a retina screen, the browser upscales it and everything looks soft.

Lighthouse calculates the expected size by multiplying the displayed dimensions by the device pixel ratio (DPR). It caps the requirement at 2x because research shows humans can't perceive quality improvements beyond that at typical viewing distances. If your image falls short, it fails.

## Mobile-First Indexing & 2025 Targets

Google's 2025 mobile-first indexing standards have tightened. Images are a primary driver of mobile bandwidth usage.

- **Network Request Target:** Aim for **<50 total network requests** on mobile. Consolidating images or lazy-loading them is critical.
- **CLS Impact:** Undersized or un-dimensioned images are the #1 cause of Cumulative Layout Shift (CLS). A CLS score > 0.1 will penalize your mobile rankings.

## Diagnose

### Chrome DevTools

1. Right-click the blurry image, select **Inspect**
2. In Elements panel, look at the `**<img>**` element
3. Check the rendered size vs natural size:

```js
// In console, click the image element first
$0.getBoundingClientRect() // displayed size
$0.naturalWidth // actual image width
$0.naturalHeight // actual image height
```

Compare: if displayed width is 400px and DPR is 2, you need naturalWidth of at least 800px.

### Quick Page Audit

```js
document.querySelectorAll('img').forEach((img) => {
  const rect = img.getBoundingClientRect()
  const dpr = Math.min(window.devicePixelRatio, 2)
  const expectedWidth = Math.ceil(rect.width * dpr)
  const expectedHeight = Math.ceil(rect.height * dpr)

  if (img.naturalWidth < expectedWidth || img.naturalHeight < expectedHeight) {
    console.warn('Low res:', img.src, {
      displayed: `${rect.width}x${rect.height}`,
      actual: `${img.naturalWidth}x${img.naturalHeight}`,
      expected: `${expectedWidth}x${expectedHeight}`
    })
  }
})
```

## Fix

### 1. Serve Properly Sized Images

The direct fix: make sure your image files are large enough.

For an image displayed at 600x400 on desktop:

- **1x displays:** 600x400 minimum
- **2x displays (retina):** 1200x800 minimum

If you only serve one size, use the 2x version. It'll look great on retina and acceptable (though heavier) on 1x.

```html
<!-- Single high-res image -->
<img
  src="/hero-1200x800.jpg"
  width="600"
  height="400"
  alt="Hero"
>
```

### 2. Use srcset for Multiple Resolutions

Serve different sizes for different pixel densities:

```html
<img
  src="/photo-600.jpg"
  srcset="
    /photo-600.jpg 1x,
    /photo-1200.jpg 2x
  "
  width="600"
  height="400"
  alt="Photo"
>
```

The browser picks the right one based on DPR.

For responsive widths, use `**srcset**` with width descriptors:

```html
<img
  src="/hero-800.jpg"
  srcset="
    /hero-400.jpg 400w,
    /hero-800.jpg 800w,
    /hero-1200.jpg 1200w,
    /hero-1600.jpg 1600w
  "
  sizes="(max-width: 600px) 100vw, 800px"
  width="800"
  height="450"
  alt="Hero"
>
```

The browser considers both viewport width and DPR when selecting.

### 3. Generate Multiple Sizes at Build Time

Don't manually create every size. Use tooling:

**Sharp (Node.js):**

```js
import sharp from 'sharp'

const sizes = [400, 800, 1200, 1600]

sizes.forEach((width) => {
  sharp('original.jpg')
    .resize(width)
    .toFile(`output-${width}.jpg`)
})
```

**Image CDN approach:**

```html
<!-- Cloudinary example -->
<img
  src="https://res.cloudinary.com/demo/image/upload/w_800/sample.jpg"
  srcset="
    https://res.cloudinary.com/demo/image/upload/w_400/sample.jpg 400w,
    https://res.cloudinary.com/demo/image/upload/w_800/sample.jpg 800w,
    https://res.cloudinary.com/demo/image/upload/w_1200/sample.jpg 1200w
  "
  sizes="(max-width: 600px) 100vw, 800px"
  alt="Sample"
>
```

CDNs like Cloudinary, imgix, or Cloudflare Images resize on-the-fly.

### 4. Consider Modern Formats

While fixing resolution, also consider format. AVIF and WebP compress better, letting you serve larger dimensions without increasing file size:

```html
<picture>
  <source
    srcset="/hero-1200.avif 1200w, /hero-800.avif 800w"
    sizes="(max-width: 600px) 100vw, 800px"
    type="image/avif"
  >
  <source
    srcset="/hero-1200.webp 1200w, /hero-800.webp 800w"
    sizes="(max-width: 600px) 100vw, 800px"
    type="image/webp"
  >
  <img
    src="/hero-800.jpg"
    srcset="/hero-1200.jpg 1200w, /hero-800.jpg 800w"
    sizes="(max-width: 600px) 100vw, 800px"
    width="800"
    height="450"
    alt="Hero"
  >
</picture>
```

## Framework Examples

**Nuxt** - `**@nuxt/image**` generates multiple sizes automatically:

```html
<NuxtImg
  src="/photo.jpg"
  width="800"
  height="600"
  sizes="sm:100vw md:50vw lg:800px"
  format="webp"
/>
```

The `**sizes**` prop triggers srcset generation. Configure providers in `**nuxt.config.ts**` for CDN support.

**Next.js** - `**next/image**` handles this automatically:

```jsx
<Image
  src="/photo.jpg"
  width={800}
  height={600}
  sizes="(max-width: 600px) 100vw, 800px"
  alt="Photo"
/>
```

It generates multiple sizes and serves WebP/AVIF where supported.

## Verify the Fix

1. **Re-run Lighthouse** - "Serves images with appropriate resolution" should pass
2. **Visual check** - On a retina display, images should look crisp, not soft
3. **DevTools Network** - Verify correct srcset variant loads based on your display

**Quick console check:**

```js
document.querySelectorAll('img').forEach((img) => {
  const rect = img.getBoundingClientRect()
  const dpr = Math.min(window.devicePixelRatio, 2)
  const ratio = img.naturalWidth / (rect.width * dpr)
  if (ratio < 0.75)
    console.warn('Still undersized:', img.src, ratio.toFixed(2))
})
```

Ratio should be 1.0 or higher (0.75 is the minimum Lighthouse allows for larger images).

## Common Mistakes

- **Upscaling small originals** - You can't add detail that doesn't exist. Start with high-res source images.
- **Ignoring retina** - Testing only on 1x displays misses the problem entirely. Use Chrome DevTools device mode with 2x DPR.
- **CSS background images** - This audit only covers `**<img>**` elements. Background images need manual srcset via `**image-set()**`.
- **SVG confusion** - SVGs are vector, infinitely scalable. This audit correctly ignores them.

## Test Your Entire Site

A product page might have crisp images while your blog uses undersized thumbnails. [**~~Unlighthouse~~**](https://unlighthouse.dev/) audits every page and flags all low-resolution images across your site.

### **Related **

[**All Best Practices Issues**](https://unlighthouse.dev/learn-lighthouse/best-practices#all-best-practices-issues) [**Best Practices Overview**](https://unlighthouse.dev/learn-lighthouse/best-practices)

[**Image Aspect Ratio** Display images with their natural aspect ratio to prevent distortion. Stretched or squished images look unprofessional.](https://unlighthouse.dev/learn-lighthouse/best-practices/image-aspect-ratio) [**Inspector Issues** Resolve browser-detected problems including mixed content, cookie issues, CSP violations, and cross-origin blocks that appear in Chrome's Issues panel.](https://unlighthouse.dev/learn-lighthouse/best-practices/inspector-issues)

**On this page **

- [What's Happening](#whats-happening)
- [Mobile-First Indexing & 2025 Targets](#mobile-first-indexing-2025-targets)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Framework Examples](#framework-examples)
- [Verify the Fix](#verify-the-fix)
- [Common Mistakes](#common-mistakes)
- [Test Your Entire Site](#test-your-entire-site)

---

- **Page:** Fix heading order for better accessibility · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/accessibility/heading-order
- **Description:** Fix heading order issues in Lighthouse accessibility audits. Ordered headings convey semantic structure for easier navigation.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix heading order for better accessibility**

Fix heading order issues in Lighthouse accessibility audits. Ordered headings convey semantic structure for easier navigation.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 18, 2025**

Screen reader users rely on headings to navigate your page. Skipped levels break navigation and make content structure unclear.

## What's happening

Headings (`**<h1>**` through `**<h6>**`) must form a logical hierarchy, increasing by only one level at a time. Skipping from `**<h2>**` to `**<h4>**` breaks the user's mental model of the page. Users cannot tell if the skipped `**<h3>**` represents missing content or poor markup.

Ordered headings let users jump between sections, understand the page structure, and orient themselves.

## Diagnose

### Chrome DevTools

1. Open DevTools (F12)
2. Press Ctrl+Shift+P (Cmd+Shift+P on Mac)
3. Type "Show headings" and select the option
4. Review the heading outline - look for skipped levels

Quick console check:

```js
const headings = [...document.querySelectorAll('h1, h2, h3, h4, h5, h6')]
let lastLevel = 0

headings.forEach((h) => {
  const level = Number.parseInt(h.tagName[1])
  if (level > lastLevel + 1 && lastLevel !== 0) {
    console.warn(`Skipped heading level: ${h.tagName} after H${lastLevel}`, h)
  }
  lastLevel = level
})
```

### Accessibility tree

1. DevTools > Elements > Accessibility pane
2. Expand the tree and look at heading structure
3. Levels must descend sequentially: 1 > 2 > 3, not 1 > 3.

## Fix

### 1. Restructure heading levels

Fix the hierarchy by adjusting heading levels:

```html
<!-- Before: Skipped level -->
<h1>Product Catalog</h1>
<h3>Electronics</h3>  <!-- Wrong: skipped h2 -->
<h3>Clothing</h3>

<!-- After: Sequential levels -->
<h1>Product Catalog</h1>
<h2>Electronics</h2>  <!-- Correct: h2 follows h1 -->
<h2>Clothing</h2>
```

For nested sections, continue the hierarchy:

```html
<h1>Product Catalog</h1>
  <h2>Electronics</h2>
    <h3>Phones</h3>
    <h3>Laptops</h3>
  <h2>Clothing</h2>
    <h3>Shirts</h3>
    <h3>Pants</h3>
```

### 2. Style independently from semantics

Use CSS to achieve desired visual sizes without breaking semantics:

```html
<!-- Keep correct heading level, style differently -->
<h2 class="text-3xl font-bold">Main Section</h2>
<h3 class="text-2xl font-semibold">Subsection</h3>
<h4 class="text-xl">Nested Item</h4>
```

```css
/* Override default heading styles */
.section-title {
  font-size: 1.5rem;
  font-weight: 600;
}

h2.section-title,
h3.section-title,
h4.section-title {
  /* Same visual appearance, correct semantic level */
}
```

### 3. Fix component headings

Components often hardcode heading levels. Make them configurable:

```html
<!-- Bad: Component always uses h3 -->
<div class="card">
  <h3>Card Title</h3>
</div>

<!-- Good: Heading level is contextual -->
<div class="card">
  <h2>Card Title</h2>  <!-- or h3, h4 depending on context -->
</div>
```

Pass the heading level as a prop.

## Framework examples

**Nuxt / Vue**

Make heading levels dynamic in components:

```html
<script setup>
defineProps({
  level: {
    type: Number,
    default: 2,
    validator: v => v >= 1 && v <= 6
  }
})
</script>

<template>
  <component :is="`h${level}`" class="card-title">
    <slot />
  </component>
</template>
```

Usage:

```html
<Card>
  <CardHeading :level="2">Products</CardHeading>
  <Card>
    <CardHeading :level="3">Electronics</CardHeading>
  </Card>
</Card>
```

**React**

Dynamic heading component:

```jsx
function Heading({ level = 2, children, className }) {
  const Tag = `h${level}`
  return <Tag className={className}>{children}</Tag>
}

// Usage with context for automatic levels
function Section({ children }) {
  const parentLevel = useHeadingLevel()
  return (
    <HeadingLevelProvider value={parentLevel + 1}>
      {children}
    </HeadingLevelProvider>
  )
}
```

## SEO impact: passage ranking

Correct heading structure is critical for **Google Passage Ranking**.

Google indexes and ranks individual passages from a page independently. It relies on `**<h>**` tags to understand where one topic ends and another begins.

- **Broken hierarchy**: Confuses the crawler about the relationship between sections.
- **Logical hierarchy**: Allows Google to snip a specific section and serve it as a **Featured Snippet**.

Fixing heading order maximizes your content's surface area in search results.

## Verify the fix

1. **Re-run Lighthouse** - The "Heading elements appear in a sequentially-descending order" audit must pass.
2. **Check heading outline** - In DevTools, run:

```js
Array.from(document.querySelectorAll('h1,h2,h3,h4,h5,h6'), h => `${h.tagName}: ${h.textContent.trim().slice(0, 50)}`)
  .join('\n')
```

The output must show logical nesting without skips.

1. **Screen reader test** - Use heading navigation (H key in NVDA/JAWS) to move through headings. The structure must be logical.

## Common mistakes

- **Using headings for visual styling**: Use a `**<p>**` or `**<span>**` with CSS if you want big bold text that isn't a section heading. Reserve headings for actual document structure.
- **Multiple h1 elements**: Use only one `**<h1>**` per page. Multiple `**<h1>**` elements confuse screen readers and search engines.
- **Starting at h2 or h3**: The first heading on a page must be `**<h1>**`. Starting at a lower level breaks the hierarchy.
- **Using divs with heading roles**: `**<div role="heading" aria-level="2">**` is fragile. Use real heading elements.
- **Hiding headings for visual design**: Use visually-hidden CSS if a heading shouldn't be visible. `**display: none**` hides it from screen readers.

## Related issues

Heading order issues often appear alongside:

- [**~~Document Title~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/document-title) - The title and h1 should describe the same topic
- [**~~Bypass~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/bypass) - Proper headings enable skip navigation
- [**~~HTML Lang~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/html-has-lang) - Both affect how screen readers interpret structure

## Test your entire site

Heading structure issues often creep in through reusable components, templates, or CMS content. A card component using `**<h3>**` might be correct on one page but break hierarchy on another. Unlighthouse scans every page and flags heading order violations across your entire site.

### **Related **

[**All Accessibility Issues**](https://unlighthouse.dev/learn-lighthouse/accessibility#common-accessibility-issues) [**Accessibility Overview**](https://unlighthouse.dev/learn-lighthouse/accessibility)

[**Frame Title** Learn how to fix frame and iframe title issues in Lighthouse accessibility audits](https://unlighthouse.dev/learn-lighthouse/accessibility/frame-title) [**Best Practices** Understand Lighthouse Best Practices audits, fix common security and browser issues, and verify failures across every page template.](https://unlighthouse.dev/learn-lighthouse/best-practices)

**On this page **

- [What's happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Framework examples](#framework-examples)
- [SEO impact: passage ranking](#seo-impact-passage-ranking)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Get a PageSpeed Insights API Key · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/get-api-key
- **Description:** Step-by-step guide to getting a free PageSpeed Insights API key from Google Cloud Console. Setup takes 2 minutes.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Get a PageSpeed Insights API Key**

Step-by-step guide to getting a free PageSpeed Insights API key from Google Cloud Console. Setup takes 2 minutes.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)3 min read Published **Jan 18, 2025**

Free API key setup in 2 minutes. No billing required for the free tier.

## Steps

### 1. Open Google Cloud Console

Go to [**~~console.cloud.google.com~~**](https://console.cloud.google.com)

Sign in with any Google account. You don't need a paid Google Cloud account - the PSI API has a free tier.

### 2. Create or Select a Project

Click the project dropdown at the top of the page:

- **New users:** Click "New Project", give it a name like "PSI Testing", and create
- **Existing users:** Select an existing project or create a new one

### 3. Enable the PageSpeed Insights API

1. Go to **APIs & Services** → **Library** (or search "API Library" in the top search bar)
2. Search for **"PageSpeed Insights API"**
3. Click on it and press **Enable**

The API is now active for your project.

### 4. Create Credentials

1. Go to **APIs & Services** → **Credentials**
2. Click **Create Credentials** → **API Key**
3. Copy the key that appears

Your key is ready to use immediately.

## Secure Your Key

API keys can be stolen and abused. For example, [**~~exposed API keys can lead to significant unauthorized charges~~**](https://cloud.google.com/docs/authentication/api-keys#securing_an_api_key) if attackers use them to call other billable GCP APIs. Always add restrictions.

### For Server-Side Use

Restrict by IP address:

1. Click on your API key in the Credentials list
2. Under **Application restrictions**, select **IP addresses**
3. Add your server's IP address(es)
4. Save

**Note:** IP restrictions [**~~don't work with serverless platforms~~**](https://vercel.com/kb/guide/can-i-get-a-fixed-ip-address) (Vercel, Cloudflare Workers, AWS Lambda) since they use dynamic IPs. Use HTTP referrer restrictions or a server-side proxy instead.

### For Client-Side Use

Restrict by HTTP referrer:

1. Click on your API key in the Credentials list
2. Under **Application restrictions**, select **HTTP referrers**
3. Add your domain: `**yourdomain.com/***`
4. Save

### API Restrictions (Critical)

**Always** limit the key to only the PSI API - this prevents the billing nightmare above:

1. Under **API restrictions**, select **Restrict key**
2. Choose **PageSpeed Insights API** from the dropdown
3. Save

## Test Your Key

Verify it works with a curl request:

```bash
curl "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=https://example.com&key=YOUR_API_KEY"
```

A successful response returns JSON with Lighthouse data. An invalid key returns:

```json
{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key."
  }
}
```

## Quotas

| **Limit** | **Value** |
| --- | --- |
| Requests per day | 25,000 |
| Requests per minute | \~240 |
| Requests per 100 seconds per user | 60 |

Monitor usage at **APIs & Services** → **PageSpeed Insights API** → **Quotas**.

The daily limit resets at midnight Pacific Time. Official Google Cloud quotas specify a default of 25,000 queries per day and 400 queries per 100 seconds (approx. 4 queries per second). Monitor and manage your limits in the [**~~Google Cloud Console~~**](https://console.cloud.google.com/apis/api/pagespeedonline.googleapis.com/quotas). Your actual limits may vary based on project history and usage.

**Set up quota alerts:** Go to **IAM & Admin** → **Quotas & System Limits** → find PageSpeed Insights API → **Create usage alert** at 50%, 80%, and 95% thresholds.

**For higher limits:** Create multiple GCP projects (each gets its own 25k/day quota) or request a quota increase in the Quotas section. Google is reportedly reasonable about increases for legitimate use cases.

## Next Steps

- [**~~Node.js integration~~**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/node-example)
- [**~~Python integration~~**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/python-example)
- [**~~Handle rate limits~~**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/rate-limits)

## Skip the API Key Dance

Unlighthouse runs Lighthouse locally - no API keys, no quotas, no Google Cloud Console.

```bash
npx unlighthouse --site https://your-site.com
```

[Try Unlighthouse](https://unlighthouse.dev/)

### **Related **

[**PageSpeed Insights API Guide**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api) [**Rate Limits**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/rate-limits) [**PageSpeed Insights vs Unlighthouse**](https://unlighthouse.dev/tools/pagespeed-insights-performance)

[**API Guide** Complete guide to using the PageSpeed Insights API. Get Lighthouse performance data programmatically with 25,000 free requests per day.](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api) [**Node.js Example** Fetch Lighthouse data with Node.js using the googleapis.com/pagespeedonline/v5/runPagespeed endpoint. Working TypeScript code examples.](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/node-example)

**On this page **

- [Steps](#steps)
- [Secure Your Key](#secure-your-key)
- [Test Your Key](#test-your-key)
- [Quotas](#quotas)
- [Next Steps](#next-steps)
- [Skip the API Key Dance](#skip-the-api-key-dance)

---

- **Page:** PageSpeed Insights API Node.js Example (googleapis.com&#x2F;pagespeedonline) · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/node-example
- **Description:** Fetch Lighthouse data with Node.js using the googleapis.com/pagespeedonline/v5/runPagespeed endpoint. Working TypeScript code examples.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **PageSpeed Insights API Node.js Example (googleapis.com/pagespeedonline)**

Fetch Lighthouse data with Node.js using the googleapis.com/pagespeedonline/v5/runPagespeed endpoint. Working TypeScript code examples.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 18, 2025**

Fetch Lighthouse performance data programmatically with [**~~Node.js~~**](https://nodejs.org).

## Official Google Client

Google provides an official Node.js client: [`**@googleapis/pagespeedonline**`](https://www.npmjs.com/package/@googleapis/pagespeedonline)

```bash
npm install @googleapis/pagespeedonline
```

```js
import { pagespeedonline } from '@googleapis/pagespeedonline'

const client = pagespeedonline('v5')
const res = await client.pagespeedapi.runpagespeed({
  url: 'https://example.com',
  key: process.env.PSI_API_KEY,
})

console.log(res.data.lighthouseResult.categories.performance.score * 100)
```

For TypeScript types, install [`**@maxim_mazurok/gapi.client.pagespeedonline-v5**`](https://www.npmjs.com/package/@maxim_mazurok/gapi.client.pagespeedonline-v5).

## Basic Request (fetch)

```js
const API_KEY = process.env.PSI_API_KEY
const url = 'https://example.com'

const response = await fetch(
  `https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=${encodeURIComponent(url)}&key=${API_KEY}`
)
const data = await response.json()

console.log('Performance:', data.lighthouseResult.categories.performance.score * 100)
```

The score is 0-1, so multiply by 100 for the familiar 0-100 scale.

## Extract Core Web Vitals

```js
function getCoreWebVitals(data) {
  const audits = data.lighthouseResult.audits
  return {
    lcp: audits['largest-contentful-paint'].numericValue,
    cls: audits['cumulative-layout-shift'].numericValue,
    tbt: audits['total-blocking-time'].numericValue,
  }
}

const vitals = getCoreWebVitals(data)
console.log(`LCP: ${vitals.lcp}ms, CLS: ${vitals.cls}, TBT: ${vitals.tbt}ms`)
```

Note: The API returns TBT (Total Blocking Time) as a proxy for INP since INP requires real user interaction data.

## Get All Category Scores

Request multiple categories in one call:

```js
const categories = ['performance', 'accessibility', 'seo', 'best-practices']
const categoryParam = categories.map(c => `category=${c}`).join('&')

const response = await fetch(
  `https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=${encodeURIComponent(url)}&key=${API_KEY}&${categoryParam}`
)
const data = await response.json()

const scores = Object.entries(data.lighthouseResult.categories).reduce((acc, [key, value]) => {
  acc[key] = Math.round(value.score * 100)
  return acc
}, {})

console.log(scores)
// { performance: 87, accessibility: 92, seo: 100, 'best-practices': 95 }
```

## With TypeScript Types

```ts
interface PSIResponse {
  lighthouseResult: {
    categories: {
      'performance': CategoryResult
      'accessibility'?: CategoryResult
      'seo'?: CategoryResult
      'best-practices'?: CategoryResult
    }
    audits: Record<string, AuditResult>
  }
  loadingExperience?: LoadingExperience
}

interface CategoryResult {
  score: number
  title: string
}

interface AuditResult {
  score: number | null
  numericValue?: number
  displayValue?: string
}

interface LoadingExperience {
  metrics: {
    LARGEST_CONTENTFUL_PAINT_MS?: MetricValue
    CUMULATIVE_LAYOUT_SHIFT_SCORE?: MetricValue
    INTERACTION_TO_NEXT_PAINT?: MetricValue
  }
}

interface MetricValue {
  percentile: number
  category: 'FAST' | 'AVERAGE' | 'SLOW'
}

async function fetchPSI(url: string): Promise<PSIResponse> {
  const response = await fetch(
    `https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=${encodeURIComponent(url)}&key=${process.env.PSI_API_KEY}`
  )

  if (!response.ok) {
    throw new Error(`PSI API error: ${response.status}`)
  }

  return response.json()
}
```

## Get Field Data (Real User Metrics)

The `**loadingExperience**` object contains real Chrome user data when available:

```js
function getFieldData(data) {
  const field = data.loadingExperience?.metrics
  if (!field)
    return null

  return {
    lcp: field.LARGEST_CONTENTFUL_PAINT_MS?.percentile,
    cls: field.CUMULATIVE_LAYOUT_SHIFT_SCORE?.percentile,
    inp: field.INTERACTION_TO_NEXT_PAINT?.percentile,
    lcpCategory: field.LARGEST_CONTENTFUL_PAINT_MS?.category,
    clsCategory: field.CUMULATIVE_LAYOUT_SHIFT_SCORE?.category,
    inpCategory: field.INTERACTION_TO_NEXT_PAINT?.category,
  }
}
```

Field data is only available for URLs with enough Chrome traffic. Low-traffic pages return `**null**`.

## Timeout Handling

PSI requests [**~~typically take 10-60 seconds~~**](https://github.com/GoogleChrome/lighthouse/issues/14072). Default timeouts will fail. Use `**AbortSignal.timeout()**` (Node.js 18+):

```js
const response = await fetch(url, {
  signal: AbortSignal.timeout(60000), // 60 second timeout
})
```

## Error Handling

The API returns 500 errors for [**~~API rate limits and error responses~~**](https://developers.google.com/speed/docs/insights/v5/get-started#limits), not just 429. Treat persistent 500s as throttling:

```js
async function fetchPSI(url) {
  const response = await fetch(
    `https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=${encodeURIComponent(url)}&key=${process.env.PSI_API_KEY}`,
    { signal: AbortSignal.timeout(60000) }
  )

  if (response.status === 429) {
    const retryAfter = response.headers.get('Retry-After') || 60
    console.log(`Rate limited. Retry after ${retryAfter}s`)
    return null
  }

  if (response.status === 500) {
    // Undocumented rate limit - treat as throttling, not server error
    console.log('Possible rate limit (500). Wait 60-180s before retrying.')
    return null
  }

  if (response.status === 400) {
    const error = await response.json()
    console.error('Invalid request:', error.error.message)
    return null
  }

  if (!response.ok) {
    console.error(`PSI API error: ${response.status}`)
    return null
  }

  return response.json()
}
```

## Complete Example

```js
import 'dotenv/config'

const API_KEY = process.env.PSI_API_KEY

async function analyzeUrl(url) {
  const apiUrl = new URL('https://www.googleapis.com/pagespeedonline/v5/runPagespeed')
  apiUrl.searchParams.set('url', url)
  apiUrl.searchParams.set('key', API_KEY)
  apiUrl.searchParams.set('strategy', 'mobile')
  apiUrl.searchParams.append('category', 'performance')
  apiUrl.searchParams.append('category', 'accessibility')

  const response = await fetch(apiUrl)

  if (!response.ok) {
    console.error(`Failed to analyze ${url}: ${response.status}`)
    return null
  }

  const data = await response.json()
  const { lighthouseResult } = data

  return {
    url,
    performance: Math.round(lighthouseResult.categories.performance.score * 100),
    accessibility: Math.round(lighthouseResult.categories.accessibility.score * 100),
    lcp: lighthouseResult.audits['largest-contentful-paint'].numericValue,
    cls: lighthouseResult.audits['cumulative-layout-shift'].numericValue,
    tbt: lighthouseResult.audits['total-blocking-time'].numericValue,
  }
}

const result = await analyzeUrl('https://example.com')
console.log(result)
```

## Next Steps

- [**~~Test multiple URLs~~**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/bulk-testing)
- [**~~Handle rate limits~~**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/rate-limits)

## Skip the Boilerplate

Building API clients, handling rate limits, and parsing responses is time you're not spending on actual performance improvements.

Unlighthouse handles the complexity and crawls your entire site:

```bash
npx unlighthouse --site https://your-site.com
```

[Try Unlighthouse](https://unlighthouse.dev/)

### **Related **

[**PageSpeed Insights API Guide**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api) [**Python Example**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/python-example) [**Bulk Testing**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/bulk-testing) [**PageSpeed Insights vs Unlighthouse**](https://unlighthouse.dev/tools/pagespeed-insights-performance)

[**Get API Key** Step-by-step guide to getting a free PageSpeed Insights API key from Google Cloud Console. Setup takes 2 minutes.](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/get-api-key) [**Python Example** Fetch Lighthouse data with Python using the googleapis.com/pagespeedonline/v5/runPagespeed endpoint. Working code examples with type hints.](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/python-example)

**On this page **

- [Official Google Client](#official-google-client)
- [Basic Request (fetch)](#basic-request-fetch)
- [Extract Core Web Vitals](#extract-core-web-vitals)
- [Get All Category Scores](#get-all-category-scores)
- [With TypeScript Types](#with-typescript-types)
- [Get Field Data (Real User Metrics)](#get-field-data-real-user-metrics)
- [Timeout Handling](#timeout-handling)
- [Error Handling](#error-handling)
- [Complete Example](#complete-example)
- [Next Steps](#next-steps)
- [Skip the Boilerplate](#skip-the-boilerplate)

---

- **Page:** Fix Focusable Elements Inside aria-hidden · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/accessibility/aria-hidden-focus
- **Description:** Learn how to fix aria-hidden-focus issues in Lighthouse accessibility audits

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Focusable Elements Inside aria-hidden**

Learn how to fix aria-hidden-focus issues in Lighthouse accessibility audits

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 18, 2025**

Keyboard users can focus elements that screen reader users can't perceive, creating a confusing mismatch in experience.

## What's Happening

When you apply `**aria-hidden="true"**` to an element, you're telling assistive technologies to ignore it completely. But if that element contains focusable items like links, buttons, or form fields, keyboard users can still tab into them. The screen reader goes silent while focus lands on an invisible element - users hear nothing and have no idea where they are on the page.

## Diagnose

1. Open Chrome DevTools (F12)
2. Go to **Elements** panel and find elements with `**aria-hidden="true"**`
3. Expand the element and look for:
   - Links ( `**<a href>**`)
   - Buttons ( `**<button>**`)
   - Form inputs ( `**<input>**`, `**<select>**`, `**<textarea>**`)
   - Elements with `**tabindex="0"**` or positive tabindex
4. Alternatively, tab through your page and listen with a screen reader - silence during focus indicates this issue

## Fix

### 1. Add tabindex="-1" to Focusable Descendants

Remove elements from the tab order while keeping aria-hidden:

```html
<!-- Before: Focusable link inside aria-hidden -->
<div aria-hidden="true">
  <a href="/terms">Terms of Service</a>
</div>

<!-- After: Link removed from tab order -->
<div aria-hidden="true">
  <a href="/terms" tabindex="-1">Terms of Service</a>
</div>
```

### 2. Use the inert Attribute

The `**inert**` attribute removes both focus AND aria-hidden in one step:

```html
<!-- Modern approach: inert handles everything -->
<div inert>
  <button>This button cannot be focused or seen by AT</button>
  <a href="/link">This link is also inert</a>
</div>
```

All modern browsers support `**inert**`, making it the preferred solution for modal backgrounds, hidden menus, and off-screen content.

### 3. Restructure to Avoid the Conflict

Rethink your HTML structure to avoid the conflict:

```html
<!-- Before: Icon with focusable link hidden -->
<div aria-hidden="true">
  <svg>...</svg>
  <a href="/download">Download</a>
</div>

<!-- After: Only hide the decorative icon -->
<div>
  <svg aria-hidden="true">...</svg>
  <a href="/download">Download</a>
</div>
```

### 4. Manage Focus When Showing/Hiding Content

For dynamic content like modals:

```javascript
function openModal(modal) {
  modal.removeAttribute('aria-hidden')
  modal.removeAttribute('inert')
  modal.querySelector('button, [href], input').focus()
}

function closeModal(modal) {
  modal.setAttribute('inert', '')
  // or: modal.setAttribute('aria-hidden', 'true')
  // and add tabindex="-1" to all focusable children
}
```

## Framework Examples

In Vue/Nuxt, use a composable to manage inert state:

```html
<script setup>
const isMenuOpen = ref(false)
</script>

<template>
  <div :inert="!isMenuOpen || undefined">
    <nav>
      <a href="/about">About</a>
      <a href="/contact">Contact</a>
    </nav>
  </div>
</template>
```

Note: Bind to `**undefined**` (not `**false**`) to remove the attribute when not needed.

## Verify the Fix

1. Re-run Lighthouse accessibility audit
2. Tab through the page with keyboard only - hidden elements must not be focusable
3. Test with a screen reader:
   - Tab navigation should skip all inert/hidden regions
   - No silent focus gaps should occur
4. Check DevTools Accessibility tree - hidden elements should not appear

## Common Mistakes

- **Only adding aria-hidden without managing focus**: Screen readers are fixed, but keyboard users still get stuck.
- **Using CSS display:none but also aria-hidden**: `**display:none**` already hides from both, making aria-hidden redundant.
- **Forgetting dynamically added content**: New buttons added via JavaScript inside aria-hidden regions are still focusable.
- **Not using inert for modals**: When a modal opens, the background content should use `**inert**` to prevent focus escape.

## When to use each approach

| **Scenario** | **Solution** |
| --- | --- |
| Modal backdrop/background | `**inert**` on background |
| Off-screen mobile menu | `**inert**` when closed |
| Decorative icons with nearby text | `**aria-hidden**` on icon only |
| Collapsed accordion content | `**inert**` when collapsed |
| Permanently hidden content | `**display: none**` (no ARIA needed) |

## Related issues

ARIA focus issues often appear alongside:

- [**~~Required ARIA attributes~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/aria-required-attr) - Missing state attributes on interactive elements
- [**~~Valid ARIA attributes~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/aria-valid-attr) - Typos in attribute names cause silent failures
- [**~~Tabindex~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/tabindex) - Both affect keyboard navigation order

## Test your entire site

This issue commonly appears in modals, mobile navigation, and dynamically shown/hidden content across your site. Unlighthouse audits every page automatically, catching aria-hidden focus traps wherever they occur so keyboard and screen reader experiences stay in sync.

### **Related **

[**All Accessibility Issues**](https://unlighthouse.dev/learn-lighthouse/accessibility#common-accessibility-issues) [**Accessibility Overview**](https://unlighthouse.dev/learn-lighthouse/accessibility)

[**Accessibility** Master web accessibility with Lighthouse. Learn how accessibility audits work, why they matter for users and SEO, and how to fix common issues.](https://unlighthouse.dev/learn-lighthouse/accessibility) [**HTML Lang Attribute** Learn how to fix missing lang attribute in Lighthouse accessibility audits. The lang attribute helps screen readers pronounce content correctly.](https://unlighthouse.dev/learn-lighthouse/accessibility/html-has-lang)

**On this page **

- [What's Happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Framework Examples](#framework-examples)
- [Verify the Fix](#verify-the-fix)
- [Common Mistakes](#common-mistakes)
- [When to use each approach](#when-to-use-each-approach)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Bulk Testing with PageSpeed Insights API · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/bulk-testing
- **Description:** Test multiple URLs with the PageSpeed Insights API. Queue implementation, rate limit handling, and practical limits of bulk PSI testing.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Bulk Testing with PageSpeed Insights API**

Test multiple URLs with the PageSpeed Insights API. Queue implementation, rate limit handling, and practical limits of bulk PSI testing.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)5 min read Published **Jan 18, 2025**

Test multiple URLs while respecting rate limits. Here's what works and where it breaks down.

## The Challenge

PSI API limits make bulk testing complex:

| **Constraint** | **Value** |
| --- | --- |
| URLs per request | 1 |
| Requests per minute | \~240 |
| Requests per day | 25,000 |
| Time per request | 10-30 seconds |

Testing 1,000 URLs? That's at least 250 seconds of API calls, assuming no errors or rate limits. Real-world: expect 30+ minutes.

**Optimal concurrency:** 5-10 parallel requests is the sweet spot. Higher concurrency triggers [**~~API rate limits~~**](https://developers.google.com/speed/docs/insights/v5/get-started#limits) with 500 errors after \~450 requests.

## Queue Implementation (Node.js)

Use `**p-queue**` to throttle requests:

```js
import PQueue from 'p-queue'

const API_KEY = process.env.PSI_API_KEY

// 4 concurrent, max 4 per second (stays under ~240/min limit)
const queue = new PQueue({
  concurrency: 4,
  interval: 1000,
  intervalCap: 4,
})

async function fetchPSI(url) {
  const response = await fetch(
    `https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=${encodeURIComponent(url)}&key=${API_KEY}`
  )

  if (!response.ok) {
    console.error(`Failed: ${url} (${response.status})`)
    return null
  }

  const data = await response.json()
  return {
    url,
    score: Math.round(data.lighthouseResult.categories.performance.score * 100),
  }
}

const urls = [
  'https://example.com',
  'https://example.com/about',
  'https://example.com/contact',
  // ... more URLs
]

const results = await Promise.all(
  urls.map(url => queue.add(() => fetchPSI(url)))
)

console.log(results.filter(Boolean))
```

## Queue Implementation (Python)

```python
import asyncio
import aiohttp
import os
from asyncio import Semaphore

API_KEY = os.environ['PSI_API_KEY']
MAX_CONCURRENT = 4
RATE_LIMIT_DELAY = 1.0  # 4 concurrent × 1 req/s each (under ~240/min limit)

semaphore = Semaphore(MAX_CONCURRENT)

async def fetch_psi(session: aiohttp.ClientSession, url: str) -> dict | None:
    async with semaphore:
        await asyncio.sleep(RATE_LIMIT_DELAY)

        params = {'url': url, 'key': API_KEY}
        async with session.get(
            'https://www.googleapis.com/pagespeedonline/v5/runPagespeed',
            params=params
        ) as response:
            if not response.ok:
                print(f'Failed: {url} ({response.status})')
                return None

            data = await response.json()
            return {
                'url': url,
                'score': round(data['lighthouseResult']['categories']['performance']['score'] * 100),
            }

async def bulk_test(urls: list[str]) -> list[dict]:
    async with aiohttp.ClientSession() as session:
        tasks = [fetch_psi(session, url) for url in urls]
        results = await asyncio.gather(*tasks)
        return [r for r in results if r]

urls = [
    'https://example.com',
    'https://example.com/about',
    'https://example.com/contact',
]

results = asyncio.run(bulk_test(urls))
print(results)
```

## Handling Failures

Add retry logic with exponential backoff:

```js
async function fetchWithRetry(url, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(
      `https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=${encodeURIComponent(url)}&key=${API_KEY}`
    )

    if (response.ok) {
      return response.json()
    }

    if (response.status === 429) {
      const delay = 2 ** attempt * 1000
      console.log(`Rate limited, waiting ${delay}ms`)
      await new Promise(r => setTimeout(r, delay))
      continue
    }

    if (response.status >= 500) {
      const delay = 2 ** attempt * 1000
      console.log(`Server error, retrying in ${delay}ms`)
      await new Promise(r => setTimeout(r, delay))
      continue
    }

    // 4xx errors (except 429) - don't retry
    console.error(`Failed: ${url} (${response.status})`)
    return null
  }

  console.error(`Max retries exceeded: ${url}`)
  return null
}
```

## Storing Results

Save to JSON for later analysis:

```js
import { writeFile } from 'node:fs/promises'

const results = await Promise.all(
  urls.map(url => queue.add(() => fetchPSI(url)))
)

const report = {
  timestamp: new Date().toISOString(),
  totalUrls: urls.length,
  successful: results.filter(Boolean).length,
  results: results.filter(Boolean),
}

await writeFile('psi-report.json', JSON.stringify(report, null, 2))
```

Or export to CSV:

```js
const csv = [
  'url,score,lcp,cls,tbt',
  ...results
    .filter(Boolean)
    .map(r => `${r.url},${r.score},${r.lcp},${r.cls},${r.tbt}`)
].join('\n')

await writeFile('psi-report.csv', csv)
```

## Progress Tracking

Show progress for long-running jobs:

```js
let completed = 0
const total = urls.length

queue.on('completed', () => {
  completed++
  process.stdout.write(`\r${completed}/${total} URLs processed`)
})

queue.on('error', (error) => {
  console.error('\nQueue error:', error.message)
})
```

## Score Variance

Scores can [**~~vary ±5 points~~**](https://developers.google.com/web/tools/lighthouse/variability) between runs due to network conditions and server load. For accurate monitoring:

- Run each URL 3 times and take the **median** score ([**~~recommended practice~~**](https://developers.google.com/web/tools/lighthouse/variability))
- Test from a consistent location (PSI uses servers in Oregon, S. Carolina, Netherlands, or Taiwan)
- Sites without CDNs see more variance based on test server location

## When This Breaks Down

At scale, PSI API bulk testing has basic problems:

| **Problem** | **Impact** |
| --- | --- |
| No URL discovery | You provide every URL manually |
| Rate limit dance | Complex queue management |
| No historical comparison | Build your own storage |
| Slow feedback | 10-30s per URL |
| Quota exhaustion | 25k/day sounds like a lot until it isn't |
| Score variance | Need multiple runs per URL for accuracy |

### The Math

| **Site Size** | **Time (optimistic)** | **Time (realistic)** |
| --- | --- | --- |
| 100 URLs | 4 minutes | 15 minutes |
| 500 URLs | 20 minutes | 1 hour |
| 1,000 URLs | 40 minutes | 2+ hours |
| 5,000 URLs | 3+ hours | 10+ hours |

And that's assuming no retries, no 429s, and no server errors.

## Alternative: CrUX API

If you only need field data (Core Web Vitals from real users), the [**~~CrUX API~~**](https://developer.chrome.com/docs/crux/guides/crux-api) has **no daily limit**: 150 requests/minute. It's faster since there's no Lighthouse analysis overhead.

```bash
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=YOUR_KEY" \
 -d '{"url": "https://example.com"}'
```

**Note:** Google is [**~~discontinuing CrUX data in PSI API~~**](https://developers.google.com/speed/docs/insights/release_notes), recommending the CrUX API instead.

## Skip the Queue Management

Unlighthouse crawls your sitemap, discovers all URLs automatically, manages concurrency, and stores results. One command:

```bash
npx unlighthouse --site https://your-site.com
```

| **Feature** | **PSI API Bulk** | **Unlighthouse** |
| --- | --- | --- |
| URL discovery | Manual | Automatic crawl |
| Rate limits | Your problem | None |
| Queue management | Build it yourself | Built-in |
| Historical data | Build it yourself | Built-in |
| Time for 500 URLs | 1+ hour | \~10 minutes |

For scheduled bulk testing with historical tracking, [**~~Unlighthouse Cloud~~**](https://unlighthouse.dev/cloud) handles everything.

[Try Unlighthouse Cloud](https://unlighthouse.dev/)

### **Related **

[**PageSpeed Insights API Guide**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api) [**Rate Limits**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/rate-limits) [**Node.js Example**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/node-example) [**Python Example**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/python-example) [**Bulk Lighthouse Testing Guide**](https://unlighthouse.dev/learn-lighthouse/bulk-lighthouse-testing) [**PageSpeed Insights vs Unlighthouse**](https://unlighthouse.dev/tools/pagespeed-insights-performance)

[**Python Example** Fetch Lighthouse data with Python using the googleapis.com/pagespeedonline/v5/runPagespeed endpoint. Working code examples with type hints.](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/python-example) [**Rate Limits** Handle PSI API quotas without breaking your integration. Rate limit detection, retry strategies, and quota monitoring.](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/rate-limits)

**On this page **

- [The Challenge](#the-challenge)
- [Queue Implementation (Node.js)](#queue-implementation-nodejs)
- [Queue Implementation (Python)](#queue-implementation-python)
- [Handling Failures](#handling-failures)
- [Storing Results](#storing-results)
- [Progress Tracking](#progress-tracking)
- [Score Variance](#score-variance)
- [When This Breaks Down](#when-this-breaks-down)
- [Alternative: CrUX API](#alternative-crux-api)
- [Skip the Queue Management](#skip-the-queue-management)

---

- **Page:** PageSpeed Insights API Python Example (googleapis.com&#x2F;pagespeedonline) · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/python-example
- **Description:** Fetch Lighthouse data with Python using the googleapis.com/pagespeedonline/v5/runPagespeed endpoint. Working code examples with type hints.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **PageSpeed Insights API Python Example (googleapis.com/pagespeedonline)**

Fetch Lighthouse data with Python using the googleapis.com/pagespeedonline/v5/runPagespeed endpoint. Working code examples with type hints.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 18, 2025**

Fetch Lighthouse performance data programmatically with Python.

## HTTP Client Choice

For PSI API requests:

| **Library** | **Best For** |
| --- | --- |
| `**requests**` | Simple scripts, familiar API |
| `**httpx**` | Sync/async flexibility, HTTP/2 support |
| `**aiohttp**` | High concurrency (100+ URLs), best connection pooling |

For bulk testing, [**~~aiohttp is often preferred for high-concurrency workloads~~**](https://docs.aiohttp.org/en/stable/client_quickstart.html) at high concurrency.

## Basic Request

```python
import os
import requests

API_KEY = os.environ['PSI_API_KEY']
url = 'https://example.com'

response = requests.get(
    'https://www.googleapis.com/pagespeedonline/v5/runPagespeed',
    params={
        'url': url,
        'key': API_KEY
    },
    timeout=60  # PSI requests take 10-60s (https://github.com/GoogleChrome/lighthouse/issues/14072)
)
data = response.json()

score = data['lighthouseResult']['categories']['performance']['score'] * 100
print(f'Performance: {score}')
```

The score is 0-1, so multiply by 100 for the familiar 0-100 scale.

## Extract Core Web Vitals

```python
def get_core_web_vitals(data: dict) -> dict:
    audits = data['lighthouseResult']['audits']
    return {
        'lcp': audits['largest-contentful-paint']['numericValue'],
        'cls': audits['cumulative-layout-shift']['numericValue'],
        'tbt': audits['total-blocking-time']['numericValue'],
    }

vitals = get_core_web_vitals(data)
print(f"LCP: {vitals['lcp']}ms, CLS: {vitals['cls']}, TBT: {vitals['tbt']}ms")
```

Note: The API returns TBT (Total Blocking Time) as a proxy for INP since INP requires real user interaction data.

## Get All Category Scores

Request multiple categories in one call:

```python
import requests

def fetch_all_categories(url: str, api_key: str) -> dict:
    response = requests.get(
        'https://www.googleapis.com/pagespeedonline/v5/runPagespeed',
        params={
            'url': url,
            'key': api_key,
            'category': ['performance', 'accessibility', 'seo', 'best-practices']
        }
    )
    data = response.json()

    categories = data['lighthouseResult']['categories']
    return {
        key: round(value['score'] * 100)
        for key, value in categories.items()
    }

scores = fetch_all_categories('https://example.com', API_KEY)
print(scores)
# {'performance': 87, 'accessibility': 92, 'seo': 100, 'best-practices': 95}
```

## With Type Hints

```python
from typing import TypedDict, Optional
import requests

class CategoryResult(TypedDict):
    score: float
    title: str

class AuditResult(TypedDict):
    score: Optional[float]
    numericValue: Optional[float]
    displayValue: Optional[str]

class MetricValue(TypedDict):
    percentile: int
    category: str  # 'FAST', 'AVERAGE', 'SLOW'

class LoadingExperience(TypedDict, total=False):
    metrics: dict[str, MetricValue]

class LighthouseResult(TypedDict):
    categories: dict[str, CategoryResult]
    audits: dict[str, AuditResult]

class PSIResponse(TypedDict):
    lighthouseResult: LighthouseResult
    loadingExperience: Optional[LoadingExperience]

def fetch_psi(url: str, api_key: str) -> PSIResponse:
    response = requests.get(
        'https://www.googleapis.com/pagespeedonline/v5/runPagespeed',
        params={'url': url, 'key': api_key}
    )
    response.raise_for_status()
    return response.json()
```

## Get Field Data (Real User Metrics)

The `**loadingExperience**` object contains real Chrome user data when available:

```python
def get_field_data(data: dict) -> Optional[dict]:
    field = data.get('loadingExperience', {}).get('metrics')
    if not field:
        return None

    return {
        'lcp': field.get('LARGEST_CONTENTFUL_PAINT_MS', {}).get('percentile'),
        'cls': field.get('CUMULATIVE_LAYOUT_SHIFT_SCORE', {}).get('percentile'),
        'inp': field.get('INTERACTION_TO_NEXT_PAINT', {}).get('percentile'),
        'lcp_category': field.get('LARGEST_CONTENTFUL_PAINT_MS', {}).get('category'),
        'cls_category': field.get('CUMULATIVE_LAYOUT_SHIFT_SCORE', {}).get('category'),
        'inp_category': field.get('INTERACTION_TO_NEXT_PAINT', {}).get('category'),
    }
```

Field data is only available for URLs with enough Chrome traffic. Low-traffic pages return `**None**`.

## Error Handling

The API returns 500 errors for [**~~API rate limits and error responses~~**](https://developers.google.com/speed/docs/insights/v5/get-started#limits), not just 429. Treat persistent 500s as throttling:

```python
import requests

def fetch_psi(url: str, api_key: str) -> Optional[dict]:
    response = requests.get(
        'https://www.googleapis.com/pagespeedonline/v5/runPagespeed',
        params={'url': url, 'key': api_key},
        timeout=60
    )

    if response.status_code == 429:
        retry_after = response.headers.get('Retry-After', 60)
        print(f'Rate limited. Retry after {retry_after}s')
        return None

    if response.status_code == 500:
        # Undocumented rate limit - wait 60-180s before retrying
        print('Possible rate limit (500). Wait before retrying.')
        return None

    if response.status_code == 400:
        error = response.json()
        print(f"Invalid request: {error['error']['message']}")
        return None

    if not response.ok:
        print(f'PSI API error: {response.status_code}')
        return None

    return response.json()
```

## Async with aiohttp

For better performance when testing multiple URLs. Use [`**aiolimiter**`](https://aiolimiter.readthedocs.io/) for rate limiting:

```bash
pip install aiohttp aiolimiter
```

```python
import asyncio
import aiohttp
import os
from aiolimiter import AsyncLimiter

API_KEY = os.environ['PSI_API_KEY']

# 240 requests per minute (stay under limit)
limiter = AsyncLimiter(240, 60)

async def fetch_psi_async(session: aiohttp.ClientSession, url: str) -> Optional[dict]:
    async with limiter:
        params = {
            'url': url,
            'key': API_KEY,
            'strategy': 'mobile'
        }

        async with session.get(
            'https://www.googleapis.com/pagespeedonline/v5/runPagespeed',
            params=params
        ) as response:
            if response.status == 429:
                print(f'Rate limited for {url}')
                return None
            if response.status == 500:
                print(f'Possible rate limit for {url}')
                return None
            if not response.ok:
                print(f'Error for {url}: {response.status}')
                return None
            return await response.json()

async def analyze_urls(urls: list[str]) -> list[dict]:
    timeout = aiohttp.ClientTimeout(total=60)
    async with aiohttp.ClientSession(timeout=timeout) as session:
        tasks = [fetch_psi_async(session, url) for url in urls]
        return await asyncio.gather(*tasks)

urls = ['https://example.com', 'https://example.com/about']
results = asyncio.run(analyze_urls(urls))
```

`**aiohttp.ClientSession**` automatically handles connection pooling for better performance.

## Complete Example

```python
import os
import requests
from typing import Optional

API_KEY = os.environ['PSI_API_KEY']

def analyze_url(url: str) -> Optional[dict]:
    response = requests.get(
        'https://www.googleapis.com/pagespeedonline/v5/runPagespeed',
        params={
            'url': url,
            'key': API_KEY,
            'strategy': 'mobile',
            'category': ['performance', 'accessibility']
        }
    )

    if not response.ok:
        print(f'Failed to analyze {url}: {response.status_code}')
        return None

    data = response.json()
    lighthouse = data['lighthouseResult']
    audits = lighthouse['audits']

    return {
        'url': url,
        'performance': round(lighthouse['categories']['performance']['score'] * 100),
        'accessibility': round(lighthouse['categories']['accessibility']['score'] * 100),
        'lcp': audits['largest-contentful-paint']['numericValue'],
        'cls': audits['cumulative-layout-shift']['numericValue'],
        'tbt': audits['total-blocking-time']['numericValue'],
    }

if __name__ == '__main__':
    result = analyze_url('https://example.com')
    print(result)
```

## Next Steps

- [**~~Test multiple URLs~~**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/bulk-testing)
- [**~~Handle rate limits~~**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/rate-limits)

## Skip the Boilerplate

Building API clients, handling rate limits, and parsing responses is time you're not spending on actual performance improvements.

Unlighthouse handles the complexity and crawls your entire site:

```bash
npx unlighthouse --site https://your-site.com
```

[Try Unlighthouse](https://unlighthouse.dev/)

### **Related **

[**PageSpeed Insights API Guide**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api) [**Node.js Example**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/node-example) [**Bulk Testing**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/bulk-testing) [**PageSpeed Insights vs Unlighthouse**](https://unlighthouse.dev/tools/pagespeed-insights-performance)

[**Node.js Example** Fetch Lighthouse data with Node.js using the googleapis.com/pagespeedonline/v5/runPagespeed endpoint. Working TypeScript code examples.](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/node-example) [**Bulk Testing** Test multiple URLs with the PageSpeed Insights API. Queue implementation, rate limit handling, and practical limits of bulk PSI testing.](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/bulk-testing)

**On this page **

- [HTTP Client Choice](#http-client-choice)
- [Basic Request](#basic-request)
- [Extract Core Web Vitals](#extract-core-web-vitals)
- [Get All Category Scores](#get-all-category-scores)
- [With Type Hints](#with-type-hints)
- [Get Field Data (Real User Metrics)](#get-field-data-real-user-metrics)
- [Error Handling](#error-handling)
- [Async with aiohttp](#async-with-aiohttp)
- [Complete Example](#complete-example)
- [Next Steps](#next-steps)
- [Skip the Boilerplate](#skip-the-boilerplate)

---

- **Page:** PageSpeed Insights API Rate Limits · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/rate-limits
- **Description:** Handle PSI API quotas without breaking your integration. Rate limit detection, retry strategies, and quota monitoring.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **PageSpeed Insights API Rate Limits**

Handle PSI API quotas without breaking your integration. Rate limit detection, retry strategies, and quota monitoring.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 18, 2025**

Handle quotas without breaking your integration.

## Limits

| **Limit** | **Value** | **Scope** |
| --- | --- | --- |
| Per day | 25,000 | Per project |
| Per minute | \~240 | Per project |
| Per 100 seconds per user | 60 | Per API key |

The daily limit resets at midnight Pacific Time. Official Google Cloud quotas specify a default of 25,000 queries per day and 400 queries per 100 seconds (approx. 4 queries per second). Monitor and manage your limits in the [**~~Google Cloud Console~~**](https://console.cloud.google.com/apis/api/pagespeedonline.googleapis.com/quotas). Your actual limits may vary based on project history and usage. Some developers report [**~~undocumented throttling~~**](https://github.com/GoogleChrome/lighthouse/issues/13605) with 500 errors after sustained heavy usage.

## Detecting Rate Limits

The API returns HTTP 429 when you hit the documented limit, but also returns **500 errors** for undocumented throttling:

```js
const response = await fetch(url)

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After')
  console.log(`Rate limited. Retry after ${retryAfter} seconds`)
}

if (response.status === 500) {
  // Undocumented per-origin rate limit
  // Wait 60-180 seconds before retrying
  console.log('Possible throttling (500). Wait before retrying.')
}
```

The `**Retry-After**` header tells you how long to wait. If it's missing, default to 60 seconds.

**Important:** The API doesn't return rate limit headers (`**X-RateLimit-***`). You must track usage client-side.

## Strategy 1: Respect Retry-After

The simplest approach - wait as long as the API tells you:

```js
async function fetchWithRetryAfter(url, apiKey) {
  const response = await fetch(
    `https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=${encodeURIComponent(url)}&key=${apiKey}`
  )

  if (response.status === 429) {
    const retryAfter = Number.parseInt(response.headers.get('Retry-After') || '60', 10)
    console.log(`Rate limited. Waiting ${retryAfter}s`)
    await new Promise(r => setTimeout(r, retryAfter * 1000))
    return fetchWithRetryAfter(url, apiKey)
  }

  return response.json()
}
```

## Strategy 2: Exponential Backoff

For transient errors and rate limits, increase wait time on each retry:

```js
async function fetchWithBackoff(url, apiKey, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(
      `https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=${encodeURIComponent(url)}&key=${apiKey}`
    )

    if (response.ok) {
      return response.json()
    }

    if (response.status === 429 || response.status >= 500) {
      const baseDelay = 1000
      const delay = baseDelay * 2 ** attempt + Math.random() * 1000
      console.log(`Attempt ${attempt + 1} failed. Waiting ${Math.round(delay)}ms`)
      await new Promise(r => setTimeout(r, delay))
      continue
    }

    // Non-retryable error
    throw new Error(`PSI API error: ${response.status}`)
  }

  throw new Error('Max retries exceeded')
}
```

The random jitter prevents thundering herd when multiple clients retry simultaneously.

## Strategy 3: Queue with Throttling

Prevent rate limits by controlling request rate upfront:

```js
import PQueue from 'p-queue'

// Stay under ~240/min limit: 4 per second is conservative
const queue = new PQueue({
  concurrency: 4,
  interval: 1000,
  intervalCap: 4,
})

async function fetchPSI(url, apiKey) {
  return queue.add(async () => {
    const response = await fetch(
      `https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=${encodeURIComponent(url)}&key=${apiKey}`
    )

    if (!response.ok) {
      throw new Error(`PSI error: ${response.status}`)
    }

    return response.json()
  })
}

// Queue handles rate limiting automatically
const urls = ['https://example.com/page1', 'https://example.com/page2']
const results = await Promise.all(urls.map(url => fetchPSI(url, API_KEY)))
```

## Strategy 4: Circuit Breaker

Stop making requests when the API is consistently failing:

```js
class CircuitBreaker {
  constructor(threshold = 5, resetTime = 60000) {
    this.failures = 0
    this.threshold = threshold
    this.resetTime = resetTime
    this.isOpen = false
    this.lastFailure = 0
  }

  async call(fn) {
    if (this.isOpen) {
      if (Date.now() - this.lastFailure < this.resetTime) {
        throw new Error('Circuit breaker open')
      }
      this.isOpen = false
      this.failures = 0
    }

    const result = await fn().catch((error) => {
      this.failures++
      this.lastFailure = Date.now()

      if (this.failures >= this.threshold) {
        this.isOpen = true
        console.log('Circuit breaker opened')
      }

      throw error
    })

    this.failures = 0
    return result
  }
}

const breaker = new CircuitBreaker()

async function fetchPSI(url) {
  return breaker.call(() =>
    fetch(`https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=${encodeURIComponent(url)}&key=${API_KEY}`)
      .then((r) => {
        if (!r.ok)
          throw new Error(`Status ${r.status}`)
        return r.json()
      })
  )
}
```

## Monitoring Usage

Check your quota in Google Cloud Console:

1. Go to **APIs & Services** → **Enabled APIs**
2. Click **PageSpeed Insights API**
3. View **Quotas** tab

You can also check programmatically:

```js
// Track requests locally
let requestsToday = 0
const resetTime = getNextMidnightPT()

function trackRequest() {
  if (Date.now() > resetTime) {
    requestsToday = 0
  }
  requestsToday++

  if (requestsToday > 24000) {
    console.warn(`Approaching daily limit: ${requestsToday}/25000`)
  }
}
```

## Quota Increase

Need more than 25,000 requests/day? You have options:

### Multiple GCP Projects

Each project gets its own 25k/day quota. Rotating API keys across projects is a common strategy to scale beyond single-project limits.

### Request a Quota Increase

1. Go to **APIs & Services** → **Quotas**
2. Find **Queries per day**
3. Click **Edit Quotas**
4. Submit request with justification

Google reviews requests manually. They're [**~~reportedly reasonable~~**](https://groups.google.com/g/pagespeed-insights-discuss/c/dB7hWmGAGsw) about increases for legitimate use cases, but approval isn't guaranteed. There's no paid tier - the API is [**~~100% free~~**](https://support.google.com/webmasters/thread/57358176/).

### Use CrUX API Instead

If you only need field data (real user Core Web Vitals), the [**~~CrUX API~~**](https://developer.chrome.com/docs/crux/guides/crux-api) has **no daily limit**: 150/minute. It's also faster since there's no Lighthouse analysis.

## When Limits Aren't Enough

The math doesn't work for site-wide testing:

| **Site Size** | **Daily Quota** | **Days to Test** |
| --- | --- | --- |
| 25,000 pages | 25,000 | 1+ |
| 50,000 pages | 25,000 | 2+ |
| 100,000 pages | 25,000 | 4+ |

And that's assuming you test each page once. Weekly monitoring? Monthly monitoring? The quota depletes fast.

## Skip the Rate Limit Dance

Unlighthouse runs Lighthouse locally. No API keys, no quotas, no rate limits.

```bash
npx unlighthouse --site https://your-site.com
```

Test your entire site as often as you want.

[Try Unlighthouse](https://unlighthouse.dev/)

### **Related **

[**PageSpeed Insights API Guide**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api) [**Get API Key**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/get-api-key) [**Bulk Testing**](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/bulk-testing) [**PageSpeed Insights vs Unlighthouse**](https://unlighthouse.dev/tools/pagespeed-insights-performance)

[**Bulk Testing** Test multiple URLs with the PageSpeed Insights API. Queue implementation, rate limit handling, and practical limits of bulk PSI testing.](https://unlighthouse.dev/learn-lighthouse/pagespeed-insights-api/bulk-testing) [**Playwright** Run Google Lighthouse audits with Playwright for automated performance, accessibility, and SEO testing. Complete setup guide with code examples.](https://unlighthouse.dev/learn-lighthouse/playwright)

**On this page **

- [Limits](#limits)
- [Detecting Rate Limits](#detecting-rate-limits)
- [Strategy 1: Respect Retry-After](#strategy-1-respect-retry-after)
- [Strategy 2: Exponential Backoff](#strategy-2-exponential-backoff)
- [Strategy 3: Queue with Throttling](#strategy-3-queue-with-throttling)
- [Strategy 4: Circuit Breaker](#strategy-4-circuit-breaker)
- [Monitoring Usage](#monitoring-usage)
- [Quota Increase](#quota-increase)
- [When Limits Aren't Enough](#when-limits-arent-enough)
- [Skip the Rate Limit Dance](#skip-the-rate-limit-dance)

---

- **Page:** Fix Missing Image Alt Text for Better Accessibility · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/accessibility/image-alt
- **Description:** Learn how to fix missing image alt attributes in Lighthouse accessibility audits

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Missing Image Alt Text for Better Accessibility**

Learn how to fix missing image alt attributes in Lighthouse accessibility audits

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 18, 2025**

Screen readers announce images without alt text as "image" or read the filename, leaving millions of visually impaired users guessing what content they're missing.

## What's happening

Lighthouse flags `**<img>**` elements that lack an `**alt**` attribute. Every image needs one of three things: descriptive alt text for informative images, an empty `**alt=""**` for decorative images, or `**role="presentation"**` to explicitly mark the image as non-essential. Without these, assistive technology cannot communicate the image's purpose.

Screen readers announce images without alt text as "image" or read the filename, leaving millions of visually impaired users guessing what content they're missing.

## Diagnose

1. Open DevTools and run Lighthouse accessibility audit.
2. Expand "Image elements do not have `**[alt]**` attributes."
3. Click flagged images to locate them in the DOM.
4. Check the Elements panel for the presence and value of the `**alt**` attribute.
5. Right-click the image and select "Open image in new tab" to understand its content.

## Fix

### 1. Add descriptive alt text

Write concise text that conveys the image's meaning in context.

```html
<!-- Before: no alt attribute -->
<img src="/team/sarah.jpg">

<!-- After: descriptive alt -->
<img src="/team/sarah.jpg" alt="Sarah Chen, Lead Developer">
```

```html
<!-- Before: missing alt on functional image -->
<a href="/search">
  <img src="/icons/search.svg">
</a>

<!-- After: alt describes the action -->
<a href="/search">
  <img src="/icons/search.svg" alt="Search">
</a>
```

### 2. Use empty alt for decorative images

Images that add visual interest but no information should have empty alt text.

```html
<!-- Decorative divider -->
<img src="/divider-ornament.svg" alt="">

<!-- Background pattern in content -->
<img src="/hero-pattern.png" alt="">
```

### 3. Use role="presentation" for layout images

For images used purely for layout or spacing, remove them from the accessibility tree.

```html
<!-- Spacer image (replace with CSS) -->
<img src="/spacer.gif" role="presentation">

<!-- Or equivalently -->
<img src="/spacer.gif" alt="" role="none">
```

## Framework examples

Nuxt Image (`**<NuxtImg>**`) still requires alt attributes like native images. Create a composable to enforce alt text in your components:

```html
<script setup lang="ts">
const props = defineProps<{
  src: string
  alt: string // Required prop enforces alt at build time
}>()
</script>

<template>
  <NuxtImg
    :src="props.src"
    :alt="props.alt"
  />
</template>
```

Use [**~~ESLint~~**](https://eslint.org) with `**eslint-plugin-vuejs-accessibility**` to catch missing alt attributes during development.

## SEO & visual search

Alt text provides the primary metadata for **Visual Search** and is a critical accessibility requirement.

- **Google Images**: Alt text acts as the "keyword" for image search results.
- **Google Lens**: As visual search grows, algorithms use alt text combined with computer vision to understand the context of an object.
- **Topic relevance**: Search engines use image alt text to better understand the surrounding content, boosting the relevance of the entire page for related queries.

> **Pro Tip***: Avoid "keyword stuffing" in alt text. Describe the image naturally. If the image is "Red leather armchair with wooden legs", use exactly that. It captures long-tail search intent better than just "chair".*

## Verify the fix

1. Re-run Lighthouse and confirm the audit passes.
2. Use a screen reader (VoiceOver, NVDA) to navigate your images.
3. Check that decorative images are skipped by the screen reader.
4. Verify functional images (links, buttons) announce their purpose.

## Common mistakes

- **Using filenames as alt text**: "IMG\_2847.jpg" or "hero-banner-final-v2.png" tells users nothing.
- **Don't start with "Image of" or "Picture of"**: Screen readers already announce it's an image.
- **Writing alt text that's too long**: Keep it under 125 characters; use `**longdesc**` or surrounding text for complex images.
- **Using the same alt text for different images**: Each image's alt should reflect its specific content and context.
- **Leaving alt empty on functional images**: Images inside links or buttons must describe the action, not be empty.

## Related issues

Image alt issues often appear alongside:

- [**~~Link name~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/link-name) - Images inside links need alt text describing the destination
- [**~~Button name~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/button-name) - Icon buttons with images need accessible names
- [**~~Frame title~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/frame-title) - Both involve describing embedded content

## Test your entire site

Missing alt text often accumulates in blog posts, product pages, and user-generated content areas that grow over time. Unlighthouse crawls your entire site to surface every image lacking proper alt text, generating a complete report you can work through systematically.

### **Related **

[**All Accessibility Issues**](https://unlighthouse.dev/learn-lighthouse/accessibility#common-accessibility-issues) [**Accessibility Overview**](https://unlighthouse.dev/learn-lighthouse/accessibility)

[**HTML Lang Attribute** Learn how to fix missing lang attribute in Lighthouse accessibility audits. The lang attribute helps screen readers pronounce content correctly.](https://unlighthouse.dev/learn-lighthouse/accessibility/html-has-lang) [**Form Labels** Learn how to fix missing form labels in Lighthouse accessibility audits. Labels ensure form controls are announced properly by assistive technologies.](https://unlighthouse.dev/learn-lighthouse/accessibility/label)

**On this page **

- [What's happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Framework examples](#framework-examples)
- [SEO & visual search](#seo-visual-search)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix Missing HTML Lang Attribute for Better Accessibility · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/accessibility/html-has-lang
- **Description:** Learn how to fix missing lang attribute in Lighthouse accessibility audits. The lang attribute helps screen readers pronounce content correctly.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Missing HTML Lang Attribute for Better Accessibility**

Learn how to fix missing lang attribute in Lighthouse accessibility audits. The lang attribute helps screen readers pronounce content correctly.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 18, 2025**

Without a language declaration, screen readers guess the page language based on user settings. If they guess wrong, content becomes incomprehensible.

## What's happening

The `**lang**` attribute on the `**<html>**` element tells browsers and assistive technologies what language the page content is in. Screen readers use this to load the correct pronunciation rules, speech patterns, and voice.

Without a language declaration, screen readers have to guess the page language based on user settings. If they guess wrong, content becomes incomprehensible. A French page read with English pronunciation rules produces nonsensical audio. Even for English pages, missing the lang attribute affects hyphenation, quotes, and other language-specific features.

## Diagnose

### DevTools

1. Open DevTools (F12).
2. Elements panel > select the `**<html>**` element.
3. Check if `**lang**` attribute exists with a valid value.

Quick console check:

```js
const lang = document.documentElement.lang
if (!lang) {
  console.error('HTML element is missing lang attribute')
}
else {
  console.log('Page language:', lang)
}
```

### View page source

1. Right-click > View Page Source.
2. First line after `**<!DOCTYPE html>**` should be `**<html lang="...">**`.

## Fix

### 1. Add lang attribute to HTML element

Add the `**lang**` attribute to your `**<html>**` element:

```html
<!DOCTYPE html>
<html lang="en">
<head>
  ...
</head>
<body>
  ...
</body>
</html>
```

### 2. Use correct language codes

Use [**~~BCP 47 language tags~~**](https://www.w3.org/International/articles/language-tags/):

```html
<!-- Basic language codes -->
<html lang="en">      <!-- English -->
<html lang="es">      <!-- Spanish -->
<html lang="fr">      <!-- French -->
<html lang="de">      <!-- German -->
<html lang="ja">      <!-- Japanese -->
<html lang="zh">      <!-- Chinese -->

<!-- With regional variants -->
<html lang="en-US">   <!-- American English -->
<html lang="en-GB">   <!-- British English -->
<html lang="pt-BR">   <!-- Brazilian Portuguese -->
<html lang="zh-Hans"> <!-- Simplified Chinese -->
<html lang="zh-Hant"> <!-- Traditional Chinese -->
```

### 3. Handle mixed-language content

When content switches language within the page, use `**lang**` on specific elements:

```html
<html lang="en">
<body>
  <p>The French phrase <span lang="fr">c'est la vie</span> means "that's life".</p>

  <blockquote lang="de">
    Die Grenzen meiner Sprache bedeuten die Grenzen meiner Welt.
  </blockquote>
  <p>— Ludwig Wittgenstein</p>
</body>
</html>
```

Screen readers will switch pronunciation rules for the marked sections.

## Framework examples

**Nuxt**

Set the default language in `**nuxt.config.ts**`:

```ts
export default defineNuxtConfig({
  app: {
    head: {
      htmlAttrs: {
        lang: 'en'
      }
    }
  }
})
```

For dynamic language:

```html
<script setup>
// In your layout or page
const { locale } = useI18n()

useHead({
  htmlAttrs: {
    lang: locale.value
  }
})
</script>
```

The `**@nuxtjs/i18n**` module handles this automatically based on the current locale.

**React / Next.js**

In Next.js App Router, set in layout:

```tsx
// app/layout.tsx
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}
```

For dynamic language:

```tsx
// app/[locale]/layout.tsx
export default function LocaleLayout({ children, params }) {
  return (
    <html lang={params.locale}>
      <body>{children}</body>
    </html>
  )
}
```

With Pages Router, customize `**_document.js**`:

```jsx
// pages/_document.js
export default function Document() {
  return (
    <HTML lang="en">
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </HTML>
  )
}
```

## User experience & bounce rate

While `**lang**` attributes are a lightweight signal for SEO geo-targeting, their biggest impact is on **User Friction**.

If you omit the `**lang**` attribute (or set it wrong), browsers like Chrome incorrectly detect the page language. This triggers the "Translate this page?" popup for every user.

- **The friction**: Users have to dismiss a popup before interacting with your site.
- **The result**: Increased bounce rate and lower time-on-page, which are negative signals for search engines.
- **Geo-targeting**: For international SEO, the `**html lang**` attribute works in tandem with `**hreflang**` tags to make sure the right regional version of your site is served to the right user.

## Verify the fix

1. **Re-run Lighthouse** - The " `**<html>**` element has a `**[lang]**` attribute" audit should pass.
2. **Console verification**:

```js
const lang = document.documentElement.lang
console.log('Lang attribute:', lang || 'MISSING')
console.log('Valid:', /^[a-z]{2,3}(?:-[A-Za-z]{2,4})?$/.test(lang))
```

1. **Screen reader test** - The page should be read with correct pronunciation for the declared language.

## Common mistakes

- **Lang on body instead of HTML**: Must be on `**<html>**`, not `**<body>**`. The lang attribute on body is ignored by most tools.
- **Invalid language code**: `**<html lang="english">**` is invalid. Use proper BCP 47 codes like `**en**`.
- **Empty lang attribute**: `**<html lang="">**` fails the audit. Must contain a valid code.
- **Wrong language**: Setting `**lang="en"**` on a French page is worse than no lang at all. Screen readers will mispronounce everything.
- **Regional variants**: For content with regional spelling or vocabulary differences, use `**en-US**` vs `**en-GB**`, `**pt-PT**` vs `**pt-BR**`.

## Related issues

HTML lang issues often appear alongside:

- [**~~Document title~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/document-title) - Both are document-level requirements set in the head
- [**~~Heading order~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/heading-order) - Proper lang makes sure headings are pronounced correctly
- [**~~Hreflang~~**](https://unlighthouse.dev/learn-lighthouse/seo/hreflang) - Multi-language sites need both HTML lang and hreflang

## Test your entire site

Missing lang attributes often occur in error pages, legacy templates, or dynamically generated pages that bypass your main layout. Unlighthouse scans every page on your site and flags any missing lang attributes, so you have consistent accessibility across all routes.

### **Related **

[**All Accessibility Issues**](https://unlighthouse.dev/learn-lighthouse/accessibility#common-accessibility-issues) [**Accessibility Overview**](https://unlighthouse.dev/learn-lighthouse/accessibility)

[**aria-hidden-focus** Learn how to fix aria-hidden-focus issues in Lighthouse accessibility audits](https://unlighthouse.dev/learn-lighthouse/accessibility/aria-hidden-focus) [**Image Alt** Learn how to fix missing image alt attributes in Lighthouse accessibility audits](https://unlighthouse.dev/learn-lighthouse/accessibility/image-alt)

**On this page **

- [What's happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Framework examples](#framework-examples)
- [User experience & bounce rate](#user-experience-bounce-rate)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix links without discernible names for better accessibility · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/accessibility/link-name
- **Description:** Fix links without discernible names in Lighthouse accessibility audits

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix links without discernible names for better accessibility**

Fix links without discernible names in Lighthouse accessibility audits

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 18, 2025**

Screen reader users navigate sites by tabbing through links. A link without a name is useless. It is announced as "link" and users must guess where it goes.

## What's happening

Lighthouse flags anchor elements (`**<a>**`) that have no accessible name. This happens when links contain only images without alt text, CSS background images, or empty content. The audit checks for text content, `**aria-label**`, `**aria-labelledby**`, or alt text on child images. Without these, users must guess the destination.

## Diagnose

1. Open DevTools and run Lighthouse accessibility audit.
2. Expand "Links do not have a discernible name."
3. Click each flagged link to locate it in the DOM.
4. Check the Elements panel for: inner text, `**aria-label**`, or images with alt text.
5. Use the Accessibility tab in DevTools to see the computed accessible name.

## Fix

### 1. Use descriptive link text

Use descriptive text content inside the link.

```html
<!-- Before: empty link -->
<a href="/pricing"></a>

<!-- After: visible text -->
<a href="/pricing">View pricing plans</a>
```

```html
<!-- Before: generic text -->
<a href="/report.pdf">Click here</a>

<!-- After: descriptive text -->
<a href="/report.pdf">Download annual report (PDF)</a>
```

### 2. Add aria-label for icon-only links

Use `**aria-label**` for icon-only links.

```html
<!-- Before: icon link with no name -->
<a href="https://twitter.com/mycompany">
  <svg class="icon-twitter">...</svg>
</a>

<!-- After: aria-label provides the name -->
<a href="https://twitter.com/mycompany" aria-label="Follow us on Twitter">
  <svg class="icon-twitter" aria-hidden="true">...</svg>
</a>
```

### 3. Add alt text to image links

The image's alt text becomes the link name when a link wraps an image.

```html
<!-- Before: image link without alt -->
<a href="/">
  <img src="/logo.svg">
</a>

<!-- After: alt text names the link -->
<a href="/">
  <img src="/logo.svg" alt="Acme Corp homepage">
</a>
```

### 4. Use visually hidden text

Use visually hidden text for icons that need a name.

```html
<a href="/cart">
  <svg aria-hidden="true">...</svg>
  <span class="sr-only">Shopping cart (3 items)</span>
</a>
```

```css
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  border: 0;
}
```

## Framework examples

Nuxt UI's `**UButton**` component with `**to**` prop handles accessibility when you provide a label. For icon-only buttons that act as links:

```html
<UButton
  to="/settings"
  icon="i-heroicons-cog-6-tooth"
  aria-label="Settings"
  variant="ghost"
/>
```

For navigation links, always provide visible text or an explicit `**aria-label**`.

## SEO impact: link equity

Descriptive link names are essential for **Internal SEO**.

When you link to a page, the "anchor text" tells Google what the destination page is about. This passes a "Relevance Signal."

- **"Click here"**: Tells Google the target page is about "Click here". This is useless.
- **"Read our accessibility guide"**: Tells Google the target page ranks for "Accessibility guide". This is high value.

Fixing "Link name" errors optimizes your site's internal linking structure and helps important pages rank for their target keywords.

## Verify the fix

1. Re-run Lighthouse and confirm the audit passes.
2. Tab through your page and listen with a screen reader.
3. Check the Accessibility tab in DevTools shows a computed name.
4. Verify each link name describes its destination. Never use "click here" or "read more."

## Common mistakes

- **Using "click here" or "read more"**: These phrases mean nothing out of context. Screen reader users navigate by listing all links on a page.
- **Duplicating the URL as the link name**: " [**~~https://example.com/products~~**](https://example.com/products)" is a poor link name. Describe the destination.
- **Hiding text with `**display: none**`**: This removes content from the accessibility tree. Use the `**.sr-only**` pattern instead.
- **Adding aria-label to links that already have text**: The `**aria-label**` overrides visible text and confuses sighted screen reader users.

## Related issues

Link name issues often appear alongside:

- [**~~Button name~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/button-name) - Same pattern for button elements
- [**~~Image alt~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/image-alt) - Image links get their name from the image's alt text
- [**~~Crawlable anchors~~**](https://unlighthouse.dev/learn-lighthouse/seo/crawlable-anchors) - Links need both accessible names and valid hrefs

## Test your entire site

Icon links appear in headers, footers, and social media sections. Unlighthouse audits every page of your site in one scan to identify all links lacking discernible names.

### **Related **

[**All Accessibility Issues**](https://unlighthouse.dev/learn-lighthouse/accessibility#common-accessibility-issues) [**Accessibility Overview**](https://unlighthouse.dev/learn-lighthouse/accessibility)

[**Form Labels** Learn how to fix missing form labels in Lighthouse accessibility audits. Labels ensure form controls are announced properly by assistive technologies.](https://unlighthouse.dev/learn-lighthouse/accessibility/label) [**Meta viewport** Fix 'zooming and scaling must not be disabled' Lighthouse audit. Remove user-scalable=no and maximum-scale=1 from your viewport meta tag.](https://unlighthouse.dev/learn-lighthouse/accessibility/meta-viewport)

**On this page **

- [What's happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Framework examples](#framework-examples)
- [SEO impact: link equity](#seo-impact-link-equity)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix Form Labels for Better Accessibility · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/accessibility/label
- **Description:** Learn how to fix missing form labels in Lighthouse accessibility audits. Labels ensure form controls are announced properly by assistive technologies.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Form Labels for Better Accessibility**

Learn how to fix missing form labels in Lighthouse accessibility audits. Labels ensure form controls are announced properly by assistive technologies.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 18, 2025**

Unlabeled form fields are invisible to screen reader users. Without a label, users cannot understand what information to enter.

## What's happening

Form elements like `**<input>**`, `**<select>**`, and `**<textarea>**` need associated labels to be accessible. When a label is missing, screen readers announce the field as just "edit text" or "combo box" without context. Users cannot determine whether they should enter their name, email, or credit card number.

Unlabeled form fields are invisible to screen reader users. Without a label, users cannot understand what information to enter.

## Diagnose

### Chrome DevTools

1. Open DevTools (F12).
2. Go to Elements panel.
3. Find form elements and check for:
   - Missing `**<label>**` element nearby.
   - Missing `**for**` attribute matching input `**id**`.
   - Missing `**aria-label**` or `**aria-labelledby**` attribute.

Quick console check:

```js
document.querySelectorAll('input, select, textarea').forEach((el) => {
  const hasLabel = el.labels?.length > 0
  const hasAriaLabel = el.hasAttribute('aria-label')
  const hasAriaLabelledby = el.hasAttribute('aria-labelledby')

  if (!hasLabel && !hasAriaLabel && !hasAriaLabelledby) {
    console.warn('Unlabeled form element:', el)
  }
})
```

### Accessibility inspector

1. Open DevTools > Accessibility tab.
2. Select the form element.
3. Check "Computed Properties"; the Name should not be empty.

## Fix

### 1. Use `**<label>**` with for attribute

The explicit label association using matching `**for**` and `**id**` attributes:

```html
<!-- Before: No label -->
<input type="email" id="email">

<!-- After: Properly labeled -->
<label for="email">Email address</label>
<input type="email" id="email">
```

This is the strongest method. Clicking the label focuses the input, improving usability for everyone.

### 2. Wrap input in `**<label>**`

Implicit association by wrapping the input inside the label:

```html
<!-- Implicit label - works without for/id -->
<label>
  Email address
  <input type="email">
</label>
```

This approach is simpler but less flexible for styling. Both methods are equally accessible.

### 3. Use aria-label for visual labels

When a visible label exists but isn't associated, or when the design requires no visible label:

```html
<!-- Icon-only search button -->
<button aria-label="Search">
  <svg>...</svg>
</button>

<!-- Input with visible placeholder but no label -->
<input type="search" aria-label="Search products" placeholder="Search...">
```

Limit `**aria-label**` use; visible labels are better for all users.

### 4. Use aria-labelledby for complex cases

When the label text exists elsewhere on the page:

```html
<h2 id="contact-heading">Contact Information</h2>
<div id="phone-hint">Include country code</div>

<input
  type="tel"
  aria-labelledby="contact-heading phone-hint"
>
```

Multiple IDs can be space-separated to combine text from several elements.

## Framework examples

**Nuxt / Vue**

With Nuxt UI, form components handle labels automatically:

```html
<template>
  <UFormField label="Email address" name="email">
    <UInput v-model="email" type="email" />
  </UFormField>
</template>
```

For custom inputs, always bind labels:

```html
<script setup>
const inputId = useId()
</script>

<template>
  <div>
    <label :for="inputId">{{ label }}</label>
    <input :id="inputId" v-model="value">
  </div>
</template>
```

**React**

Use `**htmlFor**` instead of `**for**`:

```jsx
function EmailField() {
  const id = useId()
  return (
    <div>
      <label htmlFor={id}>Email address</label>
      <input id={id} type="email" />
    </div>
  )
}
```

## Verify the fix

1. **Re-run Lighthouse** - The "Form elements have associated labels" audit should pass.
2. **Test with screen reader** - Tab to each form field and verify the label is announced.
3. **Click test** - Clicking a label should focus its associated input.

Console verification:

```js
// Should return empty array
[...document.querySelectorAll('input, select, textarea')].filter((el) => {
  const hasLabel = el.labels?.length > 0
  const hasAria = el.hasAttribute('aria-label') || el.hasAttribute('aria-labelledby')
  return !hasLabel && !hasAria
})
```

## Common mistakes

- **Placeholder as label**: Placeholders disappear when users type. They are hints, not labels. Always provide a real label.
- **Label not associated**: A `**<label>**` element near the input is not enough. Use `**for**` attribute or wrap the input inside the label.
- **Empty aria-label**: `**aria-label=""**` is worse than no label at all. Always provide meaningful text.
- **Labeling hidden inputs**: Inputs with `**type="hidden"**` should not have labels. Screen readers ignore hidden inputs.
- **Duplicate IDs**: If two inputs share the same `**id**`, only one gets the label. IDs must be unique per page.

## Related issues

Form label issues often appear alongside:

- [**~~Button name~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/button-name) - Submit buttons and form controls both need names
- [**~~Link name~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/link-name) - Form action links need descriptive text
- [**~~Color contrast~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/color-contrast) - Low-contrast labels are hard to read

## Test your entire site

Form labels are easy to miss across a large site, especially in footers, search bars, and newsletter signups that appear on every page. Unlighthouse scans your entire site and identifies every page with unlabeled form elements, helping you fix them systematically. Greenland

### **Related **

[**All Accessibility Issues**](https://unlighthouse.dev/learn-lighthouse/accessibility#common-accessibility-issues) [**Accessibility Overview**](https://unlighthouse.dev/learn-lighthouse/accessibility)

[**Image Alt** Learn how to fix missing image alt attributes in Lighthouse accessibility audits](https://unlighthouse.dev/learn-lighthouse/accessibility/image-alt) [**Link Name** Fix links without discernible names in Lighthouse accessibility audits](https://unlighthouse.dev/learn-lighthouse/accessibility/link-name)

**On this page **

- [What's happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Framework examples](#framework-examples)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix zooming and scaling disabled · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/accessibility/meta-viewport
- **Description:** Fix 'zooming and scaling must not be disabled' Lighthouse audit. Remove user-scalable=no and maximum-scale=1 from your viewport meta tag.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix zooming and scaling disabled**

Fix 'zooming and scaling must not be disabled' Lighthouse audit. Remove user-scalable=no and maximum-scale=1 from your viewport meta tag.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 18, 2025**

Disabling zoom blocks 2.2 billion people with vision impairments from reading your content. They rely on screen magnification to see what you've built.

## What's happening

Your page uses `**user-scalable="no"**` in the viewport meta tag or sets `**maximum-scale**` to a value less than 5. This locks out users with low vision who need to zoom to read text.

## Diagnose

1. Open DevTools (F12 or Cmd+Shift+I).
2. Go to the Elements panel.
3. Find `**<meta name="viewport">**` in the `**<head>**`.
4. Check for `**user-scalable=no**` or `**maximum-scale**` below 5.

Run this in the Console to check quickly:

```javascript
document.querySelector('meta[name="viewport"]')?.content
```

## Fix

### 1. Remove zoom restrictions entirely

Remove all scaling restrictions. This is the best approach.

```html
<!-- Before -->
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no, maximum-scale=1">

<!-- After -->
<meta name="viewport" content="width=device-width, initial-scale=1">
```

### 2. Set maximum scale to 5 or higher

Allow at least 5x magnification if you must constrain zooming:

```html
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=5">
```

## Framework examples

In Nuxt, configure the viewport in `**nuxt.config.ts**`:

```typescript
export default defineNuxtConfig({
  app: {
    head: {
      meta: [
        { name: 'viewport', content: 'width=device-width, initial-scale=1' }
      ]
    }
  }
})
```

For [**~~React~~**](https://react.dev) with [**~~Next.js~~**](https://nextjs.org), update `**pages/_document.js**` or use the `**Head**` component:

```jsx
import Head from 'next/head'

export default function Page() {
  return (
    <Head>
      <meta name="viewport" content="width=device-width, initial-scale=1" />
    </Head>
  )
}
```

## SEO impact: mobile friendliness

The viewport meta tag is the gatekeeper for **Mobile-First Indexing**.

- **Mobile-friendly label**: Without a proper viewport tag, mobile browsers render the page as a desktop site. Google's "Mobile-Friendly Test" will fail these pages, and they will be excluded from mobile search rankings.
- **CLS (Cumulative Layout Shift)**: Improper viewports cause layout shifts as the browser reflows text. This breaks your Core Web Vitals score.

## Verify the fix

1. Run Lighthouse again and check the accessibility section.
2. On mobile, pinch to zoom and verify it works.
3. Try zooming to at least 500% using browser zoom (Cmd/Ctrl + Plus).

## Common mistakes

- **Keeping user-scalable=no for "mobile UX"**: Users with vision impairments need zoom. The browser handles accidental zooming automatically.
- **Setting maximum-scale=1 to prevent layout shifts**: Fix your responsive design. Never disable zoom to hide layout bugs. Use CSS `**touch-action**` if you need to prevent unintended zoom on specific elements.
- **Using JavaScript to disable zoom**: Using JavaScript to disable zoom is even worse than the meta tag. Check your third-party libraries for hidden zoom prevention.

## Related issues

Meta viewport issues often appear alongside:

- [**~~Color contrast~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/color-contrast) - Both affect users with vision impairments
- [**~~Target size~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/target-size) - Small targets plus no zoom is doubly problematic
- [**~~Image size responsive~~**](https://unlighthouse.dev/learn-lighthouse/best-practices/image-size-responsive) - Both involve proper responsive design

## Test your entire site

Viewport issues often hide in templates affecting hundreds of pages. Unlighthouse scans your entire site with Google Lighthouse to find every page with accessibility issues so you can fix the root cause once.

### **Related **

[**All Accessibility Issues**](https://unlighthouse.dev/learn-lighthouse/accessibility#common-accessibility-issues) [**Accessibility Overview**](https://unlighthouse.dev/learn-lighthouse/accessibility)

[**Link Name** Fix links without discernible names in Lighthouse accessibility audits](https://unlighthouse.dev/learn-lighthouse/accessibility/link-name) [**Tabindex** Fix tabindex values greater than zero in Lighthouse accessibility audits](https://unlighthouse.dev/learn-lighthouse/accessibility/tabindex)

**On this page **

- [What's happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Framework examples](#framework-examples)
- [SEO impact: mobile friendliness](#seo-impact-mobile-friendliness)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix tabindex values greater than zero for better accessibility · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/accessibility/tabindex
- **Description:** Fix tabindex values greater than zero in Lighthouse accessibility audits

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix tabindex values greater than zero for better accessibility**

Fix tabindex values greater than zero in Lighthouse accessibility audits

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 18, 2025**

Positive tabindex values break keyboard navigation. They frustrate screen reader users and destroy the natural page flow.

## What's happening

Elements have `**tabindex**` values greater than 0, which forces them into an explicit navigation order. This overrides the natural DOM order and confuses users. Users tab to high-tabindex elements first, then jump back to `**tabindex="0"**` elements. This makes navigation feel random and broken.

## Diagnose

1. Open DevTools (F12 or Cmd+Shift+I).
2. Run this in the Console to find offending elements:

```javascript
document.querySelectorAll('[tabindex]').forEach((el) => {
  if (Number.parseInt(el.getAttribute('tabindex')) > 0) {
    console.log(el, 'tabindex:', el.getAttribute('tabindex'))
  }
})
```

1. Use Tab to navigate the page and check for unexpected focus jumps.

## Fix

### 1. Remove positive tabindex values

Never use positive tabindex. Replace them with `**0**` or remove the attribute entirely.

```html
<!-- Before -->
<button tabindex="5">Submit</button>
<input tabindex="1" type="text">
<a tabindex="3" href="/about">About</a>

<!-- After -->
<button>Submit</button>
<input type="text">
<a href="/about">About</a>
```

### 2. Reorder your DOM instead

Change their position in the HTML if elements need a different tab order.

```html
<!-- Before: Using tabindex to force order -->
<div>
  <button tabindex="2">Second</button>
  <button tabindex="1">First</button>
</div>

<!-- After: Correct DOM order, no tabindex needed -->
<div>
  <button>First</button>
  <button>Second</button>
</div>
```

Use CSS (flexbox `**order**` or grid placement) to achieve visual order while keeping logical DOM order.

## Framework examples

In Vue/Nuxt, audit your components for hardcoded tabindex values:

```html
<template>
  <!-- Avoid this -->
  <button :tabindex="priority">
    Click me
  </button>

  <!-- Prefer this -->
  <button>Click me</button>
</template>
```

Stick to `**0**`, `**-1**`, or remove the attribute for focus management.

For [**~~React~~**](https://react.dev), search your codebase for tabIndex props:

```jsx
export function TabIndexExample() {
  return (
    <>
      {/* Avoid */}
      <input tabIndex={2} />

      {/* Prefer */}
      <input />
      {/* or for programmatic focus management */}
      <input tabIndex={0} />
    </>
  )
}
```

## Verify the fix

1. Run Lighthouse again and confirm the tabindex audit passes.
2. Tab through your page from start to finish.
3. Verify focus moves in a logical, predictable order matching the visual layout.

## Common mistakes

- **Using tabindex to "prioritize" important elements**: This breaks navigation for everyone. Fix the DOM order instead. Important elements must appear early in the DOM.
- **Setting tabindex="1" to make an element focusable**: Use `**tabindex="0"**` to add an element to the natural tab order. `**tabindex="1"**` forces it to receive focus before everything else.
- **Third-party libraries injecting positive tabindex**: Check modal dialogs and date pickers. Override or configure them to use `**tabindex="0"**` or `**-1**`.
- **Confusing tabindex="-1" with positive values**: Use `**tabindex="-1"**` to remove elements from the tab order while allowing programmatic focus. Modals and skip links require this.

## Related issues

Tabindex issues often appear alongside:

- [**~~Bypass~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/bypass) - Both affect keyboard navigation patterns
- [**~~ARIA Hidden Focus~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/aria-hidden-focus) - Both can trap keyboard users
- [**~~Target Size~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/target-size) - Tab-focusable elements need adequate touch targets

## Test your entire site

Tabindex issues often hide in shared components. Unlighthouse runs Lighthouse on every page of your site to catch accessibility problems wherever they appear.

### **Related **

[**All Accessibility Issues**](https://unlighthouse.dev/learn-lighthouse/accessibility#common-accessibility-issues) [**Accessibility Overview**](https://unlighthouse.dev/learn-lighthouse/accessibility)

[**Meta viewport** Fix 'zooming and scaling must not be disabled' Lighthouse audit. Remove user-scalable=no and maximum-scale=1 from your viewport meta tag.](https://unlighthouse.dev/learn-lighthouse/accessibility/meta-viewport) [**Target Size** Fix touch target size issues in Lighthouse accessibility audits](https://unlighthouse.dev/learn-lighthouse/accessibility/target-size)

**On this page **

- [What's happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Framework examples](#framework-examples)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix Missing Required ARIA Attributes · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/accessibility/aria-required-attr
- **Description:** Learn how to fix aria-required-attr issues in Lighthouse accessibility audits

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Missing Required ARIA Attributes**

Learn how to fix aria-required-attr issues in Lighthouse accessibility audits

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 18, 2025**

ARIA roles without their required attributes leave screen reader users guessing about element state.

## What's happening

When you assign an ARIA role to an element, certain attributes become mandatory. These required attributes tell assistive technologies the current state of the element. Without them, a screen reader announces "checkbox" but has no way to convey whether it's checked or unchecked.

## Diagnose

1. Open Chrome DevTools (F12)
2. Go to **Elements** panel
3. Find the flagged element using the selector from Lighthouse
4. Check which `**role**` attribute is present
5. Compare against the required attributes for that role

Common roles and their required attributes:

- `**role="checkbox"**` requires `**aria-checked**`
- `**role="combobox"**` requires `**aria-expanded**` and `**aria-controls**`
- `**role="slider"**` requires `**aria-valuenow**`, `**aria-valuemin**`, `**aria-valuemax**`
- `**role="scrollbar"**` requires `**aria-controls**`, `**aria-valuenow**`, `**aria-valuemin**`, `**aria-valuemax**`
- `**role="heading"**` requires `**aria-level**`

## Fix

### 1. Add missing attributes

For a custom checkbox missing `**aria-checked**`:

```html
<!-- Before: Missing required attribute -->
<div role="checkbox" tabindex="0">
  Accept terms
</div>

<!-- After: Complete with required attribute -->
<div role="checkbox" aria-checked="false" tabindex="0">
  Accept terms
</div>
```

Update the attribute dynamically when state changes:

```javascript
checkbox.addEventListener('click', () => {
  const isChecked = checkbox.getAttribute('aria-checked') === 'true'
  checkbox.setAttribute('aria-checked', !isChecked)
})
```

### 2. Use native HTML elements

Native elements handle required states automatically:

```html
<!-- Native checkbox - no ARIA needed -->
<label>
  <input type="checkbox" name="terms">
  Accept terms
</label>

<!-- Native slider - no ARIA needed -->
<input type="range" min="0" max="100" value="50">
```

### 3. Fix slider/range controls

Custom sliders need multiple attributes:

```html
<!-- Complete slider implementation -->
<div
  role="slider"
  aria-valuenow="50"
  aria-valuemin="0"
  aria-valuemax="100"
  aria-label="Volume"
  tabindex="0"
>
  <div class="slider-thumb"></div>
</div>
```

## Framework examples

In Vue/Nuxt, bind required attributes reactively:

```html
<script setup>
const props = defineProps(['label'])
const isChecked = ref(false)
</script>

<template>
  <div
    role="checkbox"
    :aria-checked="isChecked"
    tabindex="0"
    @click="isChecked = !isChecked"
    @keydown.space.prevent="isChecked = !isChecked"
  >
    {{ label }}
  </div>
</template>
```

## Verify the fix

1. Re-run Lighthouse accessibility audit
2. Test with a screen reader:
   - Navigate to the element
   - Confirm the role AND state are announced
3. Interact with the element and verify state changes are announced

## Common mistakes

- **Adding attributes with empty values**: `**aria-checked=""**` is invalid. Use `**"true"**` or `**"false"**`.
- **Forgetting to update dynamic state**: Initial value is set but never updated on interaction.
- **Using ARIA when native HTML works**: Native `**<input type="checkbox">**` handles all states automatically.
- **Wrong attribute for the role**: Each role has specific required attributes. Check the WAI-ARIA spec.

## Related issues

Required attribute issues often appear alongside:

- [**~~Valid ARIA attributes~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/aria-valid-attr) - Check spelling before checking completeness
- [**~~ARIA hidden focus~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/aria-hidden-focus) - Both involve proper ARIA usage on interactive elements
- [**~~Button name~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/button-name) - Custom buttons need both names and proper ARIA states

## Test your entire site

Missing required ARIA attributes often appear in reusable components across your site. Unlighthouse scans every page automatically, finding all instances where roles lack their required attributes, so you can fix components once and improve accessibility everywhere.

### **Related **

[**All Accessibility Issues**](https://unlighthouse.dev/learn-lighthouse/accessibility#common-accessibility-issues) [**Accessibility Overview**](https://unlighthouse.dev/learn-lighthouse/accessibility)

[**Target Size** Fix touch target size issues in Lighthouse accessibility audits](https://unlighthouse.dev/learn-lighthouse/accessibility/target-size) [**aria-valid-attr** Learn how to fix aria-valid-attr issues in Lighthouse accessibility audits](https://unlighthouse.dev/learn-lighthouse/accessibility/aria-valid-attr)

**On this page **

- [What's happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Framework examples](#framework-examples)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix touch target size for better accessibility · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/accessibility/target-size
- **Description:** Fix touch target size issues in Lighthouse accessibility audits

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix touch target size for better accessibility**

Fix touch target size issues in Lighthouse accessibility audits

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 18, 2025**

Small touch targets are a failure. They frustrate users with motor impairments, large fingers, and anyone using a mobile device.

## What's happening

Interactive elements like buttons, links, or form controls are too small or too close together. WCAG 2.2 requires touch targets to be at least 24x24 CSS pixels. Aim for 44x44 pixels for better usability. Small or overlapping targets make it difficult to activate the right element.

## Diagnose

1. Open DevTools and toggle device emulation (mobile view).
2. Use the Elements panel to inspect small interactive elements.
3. Check computed dimensions in the Styles panel under "Computed."
4. Look for buttons, links, and inputs under 24px in either dimension.

Run this in Console to find undersized targets:

```javascript
document.querySelectorAll('a, button, input, select, textarea, [role="button"]').forEach((el) => {
  const rect = el.getBoundingClientRect()
  if (rect.width < 24 || rect.height < 24) {
    console.log(`${el.tagName}: ${rect.width.toFixed(0)}x${rect.height.toFixed(0)}px`, el)
  }
})
```

## Fix

### 1. Increase padding on interactive elements

Add padding to reach the minimum size:

```css
/* Before: Small tap target */
.icon-button {
  padding: 4px;
}

/* After: Accessible tap target */
.icon-button {
  padding: 12px;
  min-width: 44px;
  min-height: 44px;
}
```

### 2. Use min-height and min-width

Enforce minimum dimensions for buttons and links:

```css
button,
a,
[role="button"] {
  min-height: 44px;
  min-width: 44px;
}

/* For inline links, ensure adequate line-height */
a {
  padding: 8px 0;
  display: inline-block;
}
```

### 3. Add spacing between targets

Add margin when targets are close together:

```css
.button-group button {
  margin: 4px;
  min-height: 44px;
  min-width: 44px;
}

/* Or use gap with flexbox */
.button-group {
  display: flex;
  gap: 8px;
}
```

## Framework examples

In Nuxt with [**~~Tailwind CSS~~**](https://tailwindcss.com), use utility classes for consistent sizing:

```html
<template>
  <!-- Use min-h and min-w utilities -->
  <UButton class="min-h-11 min-w-11">
    <UIcon name="i-heroicons-heart" />
  </UButton>

  <!-- For icon-only buttons, ensure adequate size -->
  <button class="p-3 min-h-[44px] min-w-[44px]">
    <span class="sr-only">Like</span>
    <UIcon name="i-heroicons-heart" />
  </button>
</template>
```

For [**~~React~~**](https://react.dev) with styled-components or CSS Modules:

```jsx
const IconButton = styled.button`
  min-height: 44px;
  min-width: 44px;
  padding: 12px;
  display: inline-flex;
  align-items: center;
  justify-content: center;
`
```

## SEO impact: Core Web Vitals

Target size directly correlates with **Interaction to Next Paint (INP)** and Mobile Usability.

1. **Mobile usability errors**: Google Search Console has a specific error for "Clickable elements too close together." Pages with this error fail the "Mobile Friendly" test and lose mobile search rankings.
2. **INP (Interaction to Next Paint)**: Users tap repeatedly or mistakenly tap adjacent elements when buttons are too small. Rage clicking and mis-clicking signal poor responsiveness and break your Core Web Vitals metrics.

## Verify the fix

1. Run Lighthouse again and check the target-size audit.
2. Test on an actual mobile device with your thumb.
3. Verify you can tap each target without hitting adjacent elements.
4. Check that focus rings are visible and sized appropriately.

## Common mistakes

- **Only sizing the icon, not the button**: A 16px icon needs a 44px clickable area. Don't just size the icon.
- **Using pixel-perfect designs that ignore accessibility**: Touch targets must meet minimums. Don't sacrifice usability for "clean" design.
- **Forgetting about links in body text**: Inline links need adequate line-height or padding. Use `**padding: 8px 0**` with `**display: inline-block**`.
- **Dense navigation menus on mobile**: Footer links and nav menus often cram items together. Use adequate padding to expand touch areas.

## Related issues

Target size issues often appear alongside:

- [**~~Meta Viewport~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/meta-viewport) - Users who can't zoom need larger targets even more
- [**~~Tabindex~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/tabindex) - Interactive elements need both proper focus order and adequate size
- [**~~Color Contrast~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/color-contrast) - Small, low-contrast targets are nearly unusable

## Test your entire site

Touch target issues multiply across sites with repeated UI patterns. Unlighthouse audits every page on your site to identify which templates and components need attention.

### **Related **

[**All Accessibility Issues**](https://unlighthouse.dev/learn-lighthouse/accessibility#common-accessibility-issues) [**Accessibility Overview**](https://unlighthouse.dev/learn-lighthouse/accessibility)

[**Tabindex** Fix tabindex values greater than zero in Lighthouse accessibility audits](https://unlighthouse.dev/learn-lighthouse/accessibility/tabindex) [**aria-required-attr** Learn how to fix aria-required-attr issues in Lighthouse accessibility audits](https://unlighthouse.dev/learn-lighthouse/accessibility/aria-required-attr)

**On this page **

- [What's happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Framework examples](#framework-examples)
- [SEO impact: Core Web Vitals](#seo-impact-core-web-vitals)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix Invalid or Misspelled ARIA Attributes · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/accessibility/aria-valid-attr
- **Description:** Learn how to fix aria-valid-attr issues in Lighthouse accessibility audits

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Invalid or Misspelled ARIA Attributes**

Learn how to fix aria-valid-attr issues in Lighthouse accessibility audits

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 18, 2025**

Misspelled ARIA attributes are ignored by assistive technologies, making your accessibility efforts invisible.

## What's happening

ARIA attributes must match the exact specification. A typo like `**aria-lable**` instead of `**aria-label**` means screen readers see nothing at all. Browsers ignore invalid attributes without warning. Your element appears accessible in your code but provides zero information to users.

## Diagnose

1. Open Chrome DevTools (F12)
2. Go to **Elements** panel
3. Find the flagged element
4. Look for attributes starting with `**aria-**`
5. Check for typos or non-existent attribute names

Common misspellings:

- `**aria-lable**` → `**aria-label**`
- `**aria-labelled-by**` → `**aria-labelledby**`
- `**aria-role**` → `**role**` (aria-role doesn't exist)
- `**aria-description**` → `**aria-describedby**`
- `**aria-pressed**` on wrong elements

## Fix

### 1. Correct typos

```html
<!-- Before: Misspelled attribute -->
<button aria-lable="Close dialog">×</button>

<!-- After: Correct spelling -->
<button aria-label="Close dialog">×</button>
```

### 2. Use correct attribute names

```html
<!-- Before: Non-existent attribute -->
<div aria-role="navigation">...</div>

<!-- After: Correct attribute -->
<div role="navigation">...</div>
```

### 3. Fix aria-labelledby

```html
<!-- Before: Hyphenated incorrectly -->
<input aria-labelled-by="name-label">
<label id="name-label">Name</label>

<!-- After: No hyphen between "labelled" and "by" -->
<input aria-labelledby="name-label">
<label id="name-label">Name</label>
```

### 4. Replace made-up attributes

These attributes do not exist:

```html
<!-- Before: aria-description doesn't exist -->
<button aria-description="This saves your work">Save</button>

<!-- After: Use aria-describedby with a referenced element -->
<button aria-describedby="save-desc">Save</button>
<span id="save-desc" class="sr-only">This saves your work</span>
```

## Framework examples

Use TypeScript or IDE extensions to catch ARIA typos at build time:

```html
<script setup lang="ts">
// Define labels as typed constants
const buttonLabel = 'Close dialog'
</script>

<template>
  <!-- TypeScript won't catch ARIA typos in templates -->
  <!-- Use eslint-plugin-vuejs-accessibility instead -->
  <button :aria-label="buttonLabel">
    <Icon name="close" />
  </button>
</template>
```

Add `**eslint-plugin-vuejs-accessibility**` to catch these issues during development.

## Verify the fix

1. Re-run Lighthouse accessibility audit
2. In DevTools Elements panel, confirm attribute names are valid
3. Test with screen reader:
   - Navigate to the element
   - Confirm the accessible name/description is announced
4. Use browser accessibility inspector (F12 → Accessibility tab)

## Common mistakes

- **Assuming aria-role exists**: The attribute is `**role**`, not `**aria-role**`.
- **Hyphenating labelledby**: It's `**aria-labelledby**` (one word), not `**aria-labelled-by**`.
- **Inventing attributes**: Only use attributes defined in the WAI-ARIA specification.
- **Copying code without checking**: Stack Overflow answers often contain typos. Verify against MDN or W3C.

## Valid ARIA attributes reference

The most commonly used valid attributes:

- `**aria-label**` - Accessible name as a string
- `**aria-labelledby**` - Accessible name from another element's ID
- `**aria-describedby**` - Additional description from another element
- `**aria-hidden**` - Hide from assistive technology
- `**aria-expanded**` - Expandable element state
- `**aria-pressed**` - Toggle button state
- `**aria-checked**` - Checkbox/switch state
- `**aria-disabled**` - Disabled state
- `**aria-live**` - Announce dynamic content changes

## Related issues

Invalid attribute issues often appear alongside:

- [**~~Required ARIA attributes~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/aria-required-attr) - Fix spelling first, then check completeness
- [**~~ARIA hidden focus~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/aria-hidden-focus) - Incorrect attributes can create focus traps
- [**~~Link name~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/link-name) - Misspelled aria-label leaves links unnamed

## Test your entire site

ARIA typos hide in component libraries or get copy-pasted across pages. Unlighthouse scans your entire site to find every invalid ARIA attribute, so you can fix typos in one place and make sure accessibility is consistent across all pages.

### **Related **

[**All Accessibility Issues**](https://unlighthouse.dev/learn-lighthouse/accessibility#common-accessibility-issues) [**Accessibility Overview**](https://unlighthouse.dev/learn-lighthouse/accessibility)

[**aria-required-attr** Learn how to fix aria-required-attr issues in Lighthouse accessibility audits](https://unlighthouse.dev/learn-lighthouse/accessibility/aria-required-attr) [**Button name** Learn how to fix buttons without accessible names in Lighthouse accessibility audits.](https://unlighthouse.dev/learn-lighthouse/accessibility/button-name)

**On this page **

- [What's happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Framework examples](#framework-examples)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Valid ARIA attributes reference](#valid-aria-attributes-reference)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix Buttons Without Accessible Names · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/accessibility/button-name
- **Description:** Learn how to fix buttons without accessible names in Lighthouse accessibility audits.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Buttons Without Accessible Names**

Learn how to fix buttons without accessible names in Lighthouse accessibility audits.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 18, 2025**

When a button lacks an accessible name, screen readers announce it as "button" with no indication of what it does. Users have to guess if it submits a form, opens a menu, or deletes data.

## What's happening

Lighthouse flags `**<button>**` elements and elements with `**role="button"**` that have no discernible text. The audit checks for visible text content, `**aria-label**`, `**aria-labelledby**`, or `**title**` attributes. Buttons containing only icons, images without alt text, or empty content will fail this audit.

## Diagnose

1. Open DevTools and run Lighthouse accessibility audit.
2. Expand "Buttons do not have an accessible name."
3. Click each flagged button to locate it in the DOM.
4. Check the Elements panel for inner text, `**aria-label**`, or child elements with text.
5. Open the Accessibility tab to view the computed accessible name (it must not be empty).

## Fix

### 1. Add visible button text

Use visible text. It's the most straightforward fix.

```html
<!-- Before: empty button -->
<button onclick="submitForm()"></button>

<!-- After: descriptive text -->
<button onclick="submitForm()">Submit application</button>
```

```html
<!-- Before: button with only whitespace -->
<button type="submit">   </button>

<!-- After: meaningful text -->
<button type="submit">Save changes</button>
```

### 2. Add aria-label for icon buttons

When design requires icon-only buttons, provide an accessible name.

```html
<!-- Before: icon button with no name -->
<button class="close-btn">
  <svg class="icon-x">...</svg>
</button>

<!-- After: aria-label names the action -->
<button class="close-btn" aria-label="Close dialog">
  <svg class="icon-x" aria-hidden="true">...</svg>
</button>
```

```html
<!-- Menu toggle button -->
<button aria-label="Open navigation menu" aria-expanded="false">
  <svg aria-hidden="true"><!-- hamburger icon --></svg>
</button>
```

### 3. Use visually hidden text

Include full text for screen readers while showing only an icon visually.

```html
<button type="button">
  <svg aria-hidden="true"><!-- trash icon --></svg>
  <span class="sr-only">Delete item</span>
</button>
```

```css
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  border: 0;
}
```

### 4. Add alt text to image buttons

When a button contains an image, the alt text provides the name.

```html
<!-- Before: image button without alt -->
<button type="submit">
  <img src="/icons/search.png">
</button>

<!-- After: alt describes the action -->
<button type="submit">
  <img src="/icons/search.png" alt="Search">
</button>
```

## Framework examples

Nuxt UI's `**UButton**` handles accessibility automatically when you provide a label. For icon-only buttons, always add `**aria-label**`:

```html
<!-- Icon-only button with accessible name -->
<UButton
  icon="i-heroicons-trash"
  color="red"
  variant="ghost"
  aria-label="Delete item"
  @click="deleteItem"
/>

<!-- Button with visible label (automatically accessible) -->
<UButton
  label="Save changes"
  @click="save"
/>
```

Use the `**label**` prop for visible text or `**aria-label**` for icon-only buttons.

## Verify the fix

1. Re-run Lighthouse and confirm the audit passes.
2. Tab to each button and verify your screen reader announces a meaningful name.
3. Check the Accessibility tab in DevTools shows a computed name.
4. Test that dynamic buttons (loaded via JavaScript) also have accessible names.

## Common mistakes

- **Using only `**title**` attribute**: While `**title**` can provide an accessible name, it's not reliably announced by all screen readers and only shows on hover.
- **Adding aria-label that doesn't match visible text**: For buttons with visible text, the aria-label overrides it, potentially confusing sighted screen reader users.
- **Describing the icon instead of the action**: "X icon" or "hamburger icon" doesn't tell users what happens; use "Close" or "Open menu."
- **Forgetting dynamically rendered buttons**: Modal close buttons, carousel controls, and other JavaScript-inserted buttons need accessible names too.
- **Using generic names**: "Button" or "Submit" aren't helpful; be specific like "Submit contact form" or "Add to cart."

## Related issues

Button name issues often appear alongside:

- [**~~Link name~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/link-name) - Same pattern for anchor elements
- [**~~Image alt~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/image-alt) - Icon images inside buttons need alt or aria-label
- [**~~Form labels~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/label) - Submit buttons and form controls both need names

## Test your entire site

Icon buttons often repeat in headers, toolbars, cards, and interactive components throughout your site. Unlighthouse scans every page automatically, finding all buttons lacking accessible names so you can address them comprehensively rather than discovering them one complaint at a time.

### **Related **

[**All Accessibility Issues**](https://unlighthouse.dev/learn-lighthouse/accessibility#common-accessibility-issues) [**Accessibility Overview**](https://unlighthouse.dev/learn-lighthouse/accessibility)

[**aria-valid-attr** Learn how to fix aria-valid-attr issues in Lighthouse accessibility audits](https://unlighthouse.dev/learn-lighthouse/accessibility/aria-valid-attr) [**bypass** Fix bypass issues in Lighthouse accessibility audits](https://unlighthouse.dev/learn-lighthouse/accessibility/bypass)

**On this page **

- [What's happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Framework examples](#framework-examples)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix missing bypass blocks for keyboard navigation · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/accessibility/bypass
- **Description:** Fix bypass issues in Lighthouse accessibility audits

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix missing bypass blocks for keyboard navigation**

Fix bypass issues in Lighthouse accessibility audits

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 18, 2025**

Keyboard users tab through every navigation link on every page visit without a way to skip to main content.

## What's happening

Websites have navigation menus with 10, 20, or more links. Keyboard users press Tab for each link before reaching the main content. On a site with 30 nav links, that's 30 key presses per page. Skip links, headings, and landmark regions let users jump directly to what they need. WCAG requires a bypass method for pages with repeated blocks of content.

## Diagnose

1. Open your page in a browser
2. Press Tab once - does a "Skip to main content" link appear?
3. Check if you have a proper heading structure (at least one `**<h1>**`)
4. Inspect the HTML for landmark regions: `**<main>**`, `**<nav>**`, `**<header>**`, `**<footer>**`
5. If none of these exist, you fail this audit.

Use a screen reader's landmarks navigation (NVDA: D key, VoiceOver: rotor) to verify landmarks are recognized.

## Fix

### 1. Add a skip link (primary solution)

Place a skip link as the first focusable element on the page:

```html
<body>
  <a href="#main-content" class="skip-link">
    Skip to main content
  </a>

  <header>
    <nav><!-- 20+ navigation links --></nav>
  </header>

  <main id="main-content">
    <!-- Page content -->
  </main>
</body>
```

Style the skip link to be visible only on focus:

```css
.skip-link {
  position: absolute;
  top: -40px;
  left: 0;
  padding: 8px 16px;
  background: #000;
  color: #fff;
  z-index: 100;
  transition: top 0.2s;
}

.skip-link:focus {
  top: 0;
}
```

### 2. Use semantic landmark regions

Screen readers navigate by landmarks directly:

```html
<body>
  <header role="banner">
    <nav role="navigation" aria-label="Main">
      <!-- Navigation links -->
    </nav>
  </header>

  <main role="main">
    <h1>Page Title</h1>
    <!-- Main content -->
  </main>

  <aside role="complementary">
    <!-- Sidebar content -->
  </aside>

  <footer role="contentinfo">
    <!-- Footer content -->
  </footer>
</body>
```

Modern browsers don't require explicit roles on semantic elements.

### 3. Include a proper heading structure

Every page needs at least one heading:

```html
<main id="main-content">
  <h1>Welcome to Our Site</h1>

  <section>
    <h2>Featured Products</h2>
    <!-- Content -->
  </section>

  <section>
    <h2>Latest News</h2>
    <!-- Content -->
  </section>
</main>
```

Screen reader users press H to jump between headings, providing another bypass method.

### 4. Multiple navigation landmarks

When you have multiple `**<nav>**` elements, label them:

```html
<nav aria-label="Main navigation">
  <!-- Primary nav links -->
</nav>

<nav aria-label="Breadcrumb">
  <!-- Breadcrumb links -->
</nav>

<nav aria-label="Footer navigation">
  <!-- Footer links -->
</nav>
```

## Framework examples

In Nuxt, add the skip link to your default layout:

```html
<!-- layouts/default.vue -->
<template>
  <div>
    <a href="#main-content" class="skip-link">
      Skip to main content
    </a>

    <AppHeader />

    <main id="main-content">
      <slot />
    </main>

    <AppFooter />
  </div>
</template>

<style>
.skip-link {
  @apply absolute -top-10 left-0 bg-primary text-white px-4 py-2 z-50 focus:top-0 transition-[top];
}
</style>
```

This ensures every page in your Nuxt app has a skip link without duplicating code.

## Verify the fix

1. Re-run Lighthouse accessibility audit
2. Load the page and press Tab once - the skip link should appear
3. Press Enter on the skip link - focus should move to main content
4. Test with a screen reader:
   - Use landmark navigation to verify regions are recognized
   - Use heading navigation (H key) to jump between sections
5. Check multiple pages - bypass mechanisms should be consistent

## Common mistakes

- **Skip link goes nowhere**: The `**href="#main-content"**` must match an element's `**id**`.
- **Skip link hidden with display:none**: This removes it from tab order. Use positioning instead.
- **Missing id on main content**: The skip link target must exist: `**<main id="main-content">**`.
- **Only having headings, no landmarks**: Landmarks provide better navigation for screen reader users.
- **Using div instead of semantic elements**: `**<div class="main">**` isn't a landmark. Use `**<main>**` or add `**role="main"**`.

## What satisfies this audit

Lighthouse looks for at least one of:

- A heading element ( `**<h1>**` through `**<h6>**`)
- A skip link ( `**<a>**` with an anchor reference early in the DOM)
- A landmark region ( `**<main>**`, `**<nav>**`, `**<header>**`, `**<footer>**`, or elements with landmark roles)

Implement all three: skip link, proper headings, and semantic landmarks.

## Related issues

Bypass issues often appear alongside:

- [**~~Heading Order~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/heading-order) - Proper headings enable keyboard navigation by section
- [**~~Tabindex~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/tabindex) - Both affect how keyboard users navigate the page
- [**~~Link Name~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/link-name) - Skip links need accessible names too

## Test your entire site

Navigation structure and bypass blocks should be consistent across your site. Unlighthouse audits every page to ensure your skip links work everywhere, your heading structure is consistent, and all pages have proper landmark regions for screen reader navigation.

### **Related **

[**All Accessibility Issues**](https://unlighthouse.dev/learn-lighthouse/accessibility#common-accessibility-issues) [**Accessibility Overview**](https://unlighthouse.dev/learn-lighthouse/accessibility)

[**Button name** Learn how to fix buttons without accessible names in Lighthouse accessibility audits.](https://unlighthouse.dev/learn-lighthouse/accessibility/button-name) [**Color Contrast** Learn how to fix color contrast issues in Lighthouse accessibility audits](https://unlighthouse.dev/learn-lighthouse/accessibility/color-contrast)

**On this page **

- [What's happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Framework examples](#framework-examples)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [What satisfies this audit](#what-satisfies-this-audit)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix Color Contrast for Better Accessibility · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/accessibility/color-contrast
- **Description:** Learn how to fix color contrast issues in Lighthouse accessibility audits

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Color Contrast for Better Accessibility**

Learn how to fix color contrast issues in Lighthouse accessibility audits

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 18, 2025**

Low-contrast text affects approximately 300 million people with color vision deficiencies and countless others reading in bright sunlight or on older displays.

## What's happening

Lighthouse flags text where the contrast ratio between foreground and background colors doesn't meet WCAG 2 AA thresholds. Normal text requires a ratio of 4.5:1, while large text (18pt or 14pt bold) needs 3:1. This audit uses axe-core to calculate the luminance difference between your text and its background.

## Diagnose

1. Open DevTools and run Lighthouse accessibility audit.
2. Expand "Background and foreground colors do not have a sufficient contrast ratio."
3. Click any flagged element to highlight it in the DOM.
4. Use the Elements panel to inspect the computed `**color**` and `**background-color**`.
5. In DevTools, click the color swatch next to any color value to open the color picker, which shows the current contrast ratio.

## Fix

### 1. Adjust text color

Darken light text or lighten dark text until you reach the required ratio.

```css
/* Before: 2.5:1 ratio - fails */
.subtitle {
  color: #999999;
  background: #ffffff;
}

/* After: 4.6:1 ratio - passes */
.subtitle {
  color: #767676;
  background: #ffffff;
}
```

### 2. Adjust background color

Change the background if changing text isn't practical.

```css
/* Before: fails on white background */
.highlight {
  color: #ffc107;
  background: #ffffff;
}

/* After: passes with darker background */
.highlight {
  color: #ffc107;
  background: #1a1a1a;
}
```

### 3. Use CSS custom properties

Create accessible color scales that guarantee contrast.

```css
:root {
  --text-primary: #1f2937;    /* 12.6:1 on white */
  --text-secondary: #4b5563;  /* 7.5:1 on white */
  --text-muted: #6b7280;      /* 5.0:1 on white */
}

.card {
  color: var(--text-secondary);
  background: #ffffff;
}
```

## Framework examples

Use Nuxt UI's built-in color system which maintains accessible contrast by default. When customizing, use `**app.config.ts**` to define color tokens that meet WCAG standards:

```ts
export default defineAppConfig({
  ui: {
    colors: {
      primary: 'blue',
      neutral: 'slate'
    }
  }
})
```

Nuxt UI's neutral gray scale prioritizes accessibility.

## Verify the fix

1. Re-run Lighthouse and confirm the audit passes.
2. Test with the DevTools color picker; it shows a checkmark when contrast is sufficient.
3. Use browser extensions like axe DevTools for real-time contrast checking.
4. Test in different lighting conditions on various devices.

## Common mistakes

- **Using placeholder text colors for real content**: Placeholder styling ( `**#aaa**`) is intentionally low contrast; don't apply it to actual content.
- **Ignoring text over images**: Text on image backgrounds often fails; add a semi-transparent overlay or text shadow.
- **Fixing only the hover state**: Both default and hover states must pass contrast requirements.
- **Relying solely on color to convey meaning**: Users with color blindness need additional indicators like icons or underlines.

## Related issues

Color contrast issues often appear alongside:

- [**~~Meta viewport~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/meta-viewport) - Both affect users with vision impairments
- [**~~Target size~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/target-size) - Small, low-contrast buttons are doubly hard to use
- [**~~Link name~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/link-name) - Low-contrast links are even harder to identify as clickable

## Test your entire site

Color contrast issues often hide in footers, captions, and secondary content that gets overlooked during manual review. Unlighthouse scans every page of your site automatically, catching contrast failures across your entire domain so nothing slips through to production.

### **Related **

[**All Accessibility Issues**](https://unlighthouse.dev/learn-lighthouse/accessibility#common-accessibility-issues) [**Accessibility Overview**](https://unlighthouse.dev/learn-lighthouse/accessibility)

[**bypass** Fix bypass issues in Lighthouse accessibility audits](https://unlighthouse.dev/learn-lighthouse/accessibility/bypass) [**Document title** Learn how to fix missing document title in Lighthouse accessibility audits. The title gives screen reader users an overview of the page.](https://unlighthouse.dev/learn-lighthouse/accessibility/document-title)

**On this page **

- [What's happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Framework examples](#framework-examples)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix Frame Title for Better Accessibility · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/accessibility/frame-title
- **Description:** Learn how to fix frame and iframe title issues in Lighthouse accessibility audits

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Frame Title for Better Accessibility**

Learn how to fix frame and iframe title issues in Lighthouse accessibility audits

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 18, 2025**

Screen reader users rely on frame titles to understand embedded content. Without titles, iframes become mysterious black boxes that users must enter to understand.

## What's happening

Your page has `**<iframe>**` or `**<frame>**` elements without a `**title**` attribute. Screen readers announce frames as navigation landmarks, but without titles, users hear only "frame" with no indication of what's inside. They must enter the frame, explore it, and exit to continue, which wastes time and causes confusion.

## Diagnose

1. Open DevTools (F12 or Cmd+Shift+I).
2. Run this in the Console to find frames without titles:

```javascript
document.querySelectorAll('iframe, frame').forEach((el) => {
  if (!el.title || el.title.trim() === '') {
    console.log('Missing title:', el)
  }
})
```

1. Use a screen reader (VoiceOver, NVDA) to navigate to the frame and hear how it's announced.

## Fix

### 1. Add descriptive title attributes

Give each frame a title describing its purpose:

```html
<!-- Before -->
<iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ"></iframe>

<!-- After -->
<iframe
  src="https://www.youtube.com/embed/dQw4w9WgXcQ"
  title="Product demonstration video">
</iframe>
```

### 2. Examples for common embed types

```html
<!-- Google Maps -->
<iframe
  src="https://www.google.com/maps/embed?..."
  title="Map showing our office location in San Francisco">
</iframe>

<!-- Social media embeds -->
<iframe
  src="https://platform.twitter.com/embed/..."
  title="Twitter post from @company about product launch">
</iframe>

<!-- Third-party widgets -->
<iframe
  src="https://calendly.com/embed/..."
  title="Schedule a meeting with our sales team">
</iframe>

<!-- Advertising (if unavoidable) -->
<iframe
  src="https://ads.example.com/..."
  title="Advertisement">
</iframe>
```

### 3. Hide decorative or technical iframes

For iframes that provide no user content (tracking pixels, technical embeds):

```html
<iframe
  src="https://tracking.example.com/pixel"
  title=""
  aria-hidden="true"
  style="display: none">
</iframe>
```

Note: Empty title with `**aria-hidden="true"**` hides the frame from assistive technology entirely.

## Framework examples

In Nuxt, when embedding videos or maps, always pass the title:

```html
<template>
  <iframe
    :src="videoUrl"
    title="Customer testimonial video from John Smith"
    loading="lazy"
    allow="accelerometer; autoplay; clipboard-write; encrypted-media"
  />
</template>
```

For YouTube embeds with `**@nuxt/youtube**`, check that the component passes through title attributes.

For [**~~React~~**](https://react.dev), make title a required prop or add [**~~ESLint~~**](https://eslint.org) rules:

```jsx
// Good pattern: require title prop
function VideoEmbed({ src, title }) {
  if (!title) {
    console.warn('VideoEmbed requires a title for accessibility')
  }

  return (
    <iframe
      src={src}
      title={title}
      loading="lazy"
    />
  )
}
```

## Verify the fix

1. Run Lighthouse again and check the frame-title audit passes.
2. Use VoiceOver (Mac) or NVDA (Windows) to navigate to the iframe.
3. Confirm the screen reader announces the title before entering the frame.
4. Verify the title accurately describes the content.

## Common mistakes

- **Using generic titles like "iframe" or "embedded content"**: Be specific. "YouTube video" is better, but "Product demo showing checkout flow" is best.
- **Copying the URL as the title**: `**title="https://youtube.com/..."**` tells users nothing. Describe what they'll find.
- **Forgetting dynamically inserted iframes**: Social embed scripts and video players often inject iframes without titles. Check your rendered HTML, not just source code.
- **Third-party embeds without title support**: Some embed codes don't include titles. Manually add the title attribute after the script injects the iframe, or wrap in a labeled container.

## Related issues

Frame title issues often appear alongside:

- [**~~Image alt~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/image-alt) - Both require descriptive alternative text for embedded content
- [**~~Link name~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/link-name) - Iframes containing links need proper link names too
- [**~~Button name~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/button-name) - Interactive elements inside iframes need accessible names

## Test your entire site

Iframes often appear on specific page types like blog posts with videos or contact pages with maps. Unlighthouse crawls your entire site running Lighthouse on each page, catching frame title issues wherever they appear so you can fix embed patterns at the source.

### **Related **

[**All Accessibility Issues**](https://unlighthouse.dev/learn-lighthouse/accessibility#common-accessibility-issues) [**Accessibility Overview**](https://unlighthouse.dev/learn-lighthouse/accessibility)

[**Document title** Learn how to fix missing document title in Lighthouse accessibility audits. The title gives screen reader users an overview of the page.](https://unlighthouse.dev/learn-lighthouse/accessibility/document-title) [**Heading Order** Fix heading order issues in Lighthouse accessibility audits. Ordered headings convey semantic structure for easier navigation.](https://unlighthouse.dev/learn-lighthouse/accessibility/heading-order)

**On this page **

- [What's happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Framework examples](#framework-examples)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix Missing Document Title · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/accessibility/document-title
- **Description:** Learn how to fix missing document title in Lighthouse accessibility audits. The title gives screen reader users an overview of the page.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Missing Document Title**

Learn how to fix missing document title in Lighthouse accessibility audits. The title gives screen reader users an overview of the page.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 18, 2025**

Pages without titles leave users guessing. Screen reader users hear "untitled document" and cannot identify what page they landed on.

## What's happening

The `**<title>**` element provides the page's name that appears in browser tabs, bookmarks, and search results. Screen readers announce the title when users arrive at a page, giving immediate context.

Without a title, users cannot distinguish between browser tabs, search results are meaningless, and screen reader users have no indication of the page content until they start exploring.

## Diagnose

### Browser check

1. Look at the browser tab; if it shows the URL or "Untitled" instead of a descriptive name, the title is missing.
2. Try bookmarking the page; the suggested name should be descriptive.

### DevTools

1. Open DevTools (F12).
2. Elements panel > search for `**<title>**`.
3. Or run in Console:

```js
console.log('Title:', document.title || 'MISSING')
```

### View page source

1. Right-click > View Page Source.
2. Look for `**<title>**` within `**<head>**`.
3. Check if it exists and contains meaningful text.

## Fix

### 1. Add a title element

Add `**<title>**` inside `**<head>**` on every page:

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Product Catalog - Acme Store</title>
</head>
<body>
  ...
</body>
</html>
```

### 2. Make titles descriptive and unique

Each page needs a unique, descriptive title:

```html
<!-- Bad: Generic title on all pages -->
<title>Acme Store</title>

<!-- Good: Specific to each page -->
<title>Running Shoes - Acme Store</title>
<title>Checkout - Acme Store</title>
<title>Order Confirmation #12345 - Acme Store</title>
```

Pattern: **Page-specific content - Site name**

### 3. Include key information first

Screen readers may truncate long titles. Put the most important information first:

```html
<!-- Bad: Site name first -->
<title>Acme Store | Running Shoes | Men's Athletic Footwear</title>

<!-- Good: Specific content first -->
<title>Men's Running Shoes - Athletic Footwear - Acme Store</title>
```

## Framework examples

**Nuxt**

Use `**useHead**` composable or `**useSeoMeta**`:

```html
<script setup>
useHead({
  title: 'Product Catalog'
})

// Or with template
useSeoMeta({
  title: 'Product Catalog - Acme Store',
  ogTitle: 'Product Catalog - Acme Store'
})
</script>
```

For dynamic titles:

```html
<script setup>
const product = await useAsyncData('product', () => fetchProduct())

useHead({
  title: () => `${product.value?.name} - Acme Store`
})
</script>
```

Configure a title template in `**nuxt.config.ts**`:

```ts
export default defineNuxtConfig({
  app: {
    head: {
      titleTemplate: '%s - Acme Store'
    }
  }
})
```

**React / Next.js**

With Next.js App Router:

```tsx
// app/products/page.tsx
export const metadata = {
  title: 'Product Catalog - Acme Store'
}

// Dynamic
export async function generateMetadata({ params }) {
  const product = await getProduct(params.id)
  return { title: `${product.name} - Acme Store` }
}
```

Or with React Helmet:

```jsx
import { Helmet } from 'react-helmet'

function ProductPage({ product }) {
  return (
    <>
      <Helmet>
        <title>
          {product.name}
          {' '}
          - Acme Store
        </title>
      </Helmet>
      <main>...</main>
    </>
  )
}
```

## SEO impact: CTR & rankings

The document title is the single most important on-page SEO element.

- **Primary SERP hook**: It is the first thing users read in search results.
- **Pogo-sticking**: If a title is vague or misleading (e.g., just "Home"), users may click, realize it's not what they wanted, and immediately bounce back to Google. This "pogo-sticking" sends a strong negative signal to Google's algorithm.
- **Keyword relevance**: Placing the primary keyword near the front of the title carries more weight for ranking.

Aligning your titles for accessibility (descriptive, unique, front-loaded) is 100% identical to optimizing them for SEO.

## Verify the fix

1. **Re-run Lighthouse** - The "Document has a `**<title>**` element" audit should pass.
2. **Check browser tab** - Should show descriptive page name.
3. **Console verification**:

```js
const title = document.title
if (!title || title.trim() === '') {
  console.error('Page title is missing or empty')
}
else {
  console.log('Title:', title)
}
```

1. **Screen reader test** - Navigate to the page; the title should be announced.

## Common mistakes

- **Empty title tag**: `**<title></title>**` passes the "exists" check but fails accessibility. The title must contain text.
- **Same title on all pages**: `**<title>Home</title>**` on every page makes navigation impossible. Each page needs a unique title.
- **Title only in JavaScript**: If your title is set via JavaScript and rendering fails, the page has no title. Use server-side rendering or a fallback.
- **Special characters not encoded**: Encode ampersands and other special characters: `**<title>Tom &amp; Jerry</title>**`
- **Excessively long titles**: Keep titles under 60-70 characters. Longer titles get truncated in search results and browser tabs.

## Related issues

Document title issues often appear alongside:

- [**~~HTML lang~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/html-has-lang) - Both are document-level metadata requirements
- [**~~Heading order~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/heading-order) - Title and h1 should align for consistent structure
- [**~~Meta description~~**](https://unlighthouse.dev/learn-lighthouse/seo/meta-description) - Both affect how the page appears in search and assistive tech

## Test your entire site

Missing titles often hide in error pages, dynamically generated pages, or legacy sections. Unlighthouse scans your entire site and identifies every page without a proper title, catching issues that manual testing misses.

### **Related **

[**All Accessibility Issues**](https://unlighthouse.dev/learn-lighthouse/accessibility#common-accessibility-issues) [**Accessibility Overview**](https://unlighthouse.dev/learn-lighthouse/accessibility)

[**Color Contrast** Learn how to fix color contrast issues in Lighthouse accessibility audits](https://unlighthouse.dev/learn-lighthouse/accessibility/color-contrast) [**Frame Title** Learn how to fix frame and iframe title issues in Lighthouse accessibility audits](https://unlighthouse.dev/learn-lighthouse/accessibility/frame-title)

**On this page **

- [What's happening](#whats-happening)
- [Diagnose](#diagnose)
- [Fix](#fix)
- [Framework examples](#framework-examples)
- [SEO impact: CTR & rankings](#seo-impact-ctr-rankings)
- [Verify the fix](#verify-the-fix)
- [Common mistakes](#common-mistakes)
- [Related issues](#related-issues)
- [Test your entire site](#test-your-entire-site)

---

- **Page:** Fix Invalid Canonical URL for Better SEO · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/seo/canonical
- **Description:** Resolve canonical tag errors that cause duplicate content issues and diluted page authority. Learn to implement rel=canonical correctly.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Invalid Canonical URL for Better SEO**

Resolve canonical tag errors that cause duplicate content issues and diluted page authority. Learn to implement rel=canonical correctly.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)5 min read Published **Jan 18, 2025**

46% of websites have canonical tag issues. An invalid canonical tells search engines to index the wrong URL - or worse, no URL at all - fragmenting your page authority across duplicates.

## What's the Problem?

Canonical tags tell search engines which version of a page is the "official" one when multiple URLs serve similar or identical content. When the canonical URL is invalid, search engines can't follow your instructions.

**Critical insight:** [**~~Canonicals are hints, not directives~~**](https://developers.google.com/search/docs/crawling-indexing/canonicalization-troubleshooting). Google may choose a different canonical if signals conflict (internal links, sitemaps, hreflang all factor in). Don't assume your canonical will be respected - verify in Search Console's URL Inspection tool.

This creates several problems:

**Duplicate content dilution.** Without a valid canonical, Google might index `**/products/widget**`, `**/products/widget?ref=email**`, and `**/products/widget?utm_source=twitter**` as separate pages. Your page authority splits three ways instead of consolidating.

**Crawl budget waste.** Search engines spend time crawling URLs that should point to a single canonical, leaving less budget for your actual unique content.

**Ranking instability.** Google picks whichever URL it prefers, which might change week to week. Your rankings fluctuate as the indexed URL shifts.

**The technical causes vary.** Lighthouse fails this audit when your canonical tag:

- Contains an invalid URL (malformed syntax)
- Uses a relative URL instead of absolute
- Points to a different hreflang location (cross-language canonical)
- Points to the homepage when it should point to the current page
- Conflicts with another canonical declaration (multiple different canonicals)

Each of these confuses search engines about which URL to index.

## How to Identify This Issue

### Chrome DevTools

Check your canonical in the Elements panel:

1. Press `**Ctrl/Cmd + F**` in Elements panel
2. Search for `**rel="canonical"**` or `**rel=canonical**`
3. Examine the `**href**` value

Common problems to look for:

```html
<!-- Invalid URL -->
<link rel="canonical" href="not-a-valid-url">

<!-- Relative URL (should be absolute) -->
<link rel="canonical" href="/products/widget">

<!-- Points to homepage when it shouldn't -->
<link rel="canonical" href="https://example.com/">

<!-- Multiple conflicting canonicals -->
<link rel="canonical" href="https://example.com/page-a">
<link rel="canonical" href="https://example.com/page-b">
```

Quick console check:

```js
const canonicals = document.querySelectorAll('link[rel="canonical"]')
canonicals.forEach(link => console.log(link.href))
// Should output exactly one absolute URL matching the current page
```

### Lighthouse

Run a Lighthouse SEO audit. Look for "Document does not have a valid `**rel=canonical**`" in the results.

The explanation will indicate the specific problem:

- "Invalid URL" - malformed href value
- "Is not an absolute URL" - relative path used
- "Points to another hreflang location" - cross-language canonical mismatch
- "Points to the domain's root URL" - homepage canonical on non-homepage
- "Multiple conflicting URLs" - more than one canonical declared

## The Fix

### 1. Add a Valid Absolute Canonical

Every page should have exactly one canonical pointing to itself (or to the preferred version if duplicates exist):

```html
<head>
  <link rel="canonical" href="https://example.com/products/widget">
</head>
```

**Requirements:**

- Must be an absolute URL with protocol ( `**https://**`)
- Must be in the `**<head>**`, not `**<body>**`
- Should match the URL you want indexed
- Only one canonical per page

For self-referencing canonicals (the most common case):

```html
<!-- On https://example.com/blog/my-post -->
<link rel="canonical" href="https://example.com/blog/my-post">
```

### 2. Handle URL Variations

When the same content exists at multiple URLs, canonicalize to one:

```html
<!-- All these pages should have the same canonical -->
<!-- https://example.com/products/widget -->
<!-- https://example.com/products/widget?ref=email -->
<!-- https://example.com/products/widget?utm_source=twitter -->
<!-- https://www.example.com/products/widget -->

<link rel="canonical" href="https://example.com/products/widget">
```

Choose your canonical URL wisely:

- Pick HTTPS over HTTP
- Choose with or without www (match your site standard)
- Exclude tracking parameters
- Use lowercase paths if your server treats URLs case-insensitively

### 3. Fix Common Canonical Errors

**Relative URLs:**

```html
<!-- Wrong -->
<link rel="canonical" href="/products/widget">

<!-- Right -->
<link rel="canonical" href="https://example.com/products/widget">
```

**Homepage canonical on all pages:**

```html
<!-- Wrong - every page points to homepage -->
<link rel="canonical" href="https://example.com/">

<!-- Right - each page points to itself -->
<link rel="canonical" href="https://example.com/about">
```

**Multiple conflicting canonicals:**

```html
<!-- Wrong - two different canonicals -->
<link rel="canonical" href="https://example.com/page-a">
<link rel="canonical" href="https://example.com/page-b">

<!-- Right - single canonical -->
<link rel="canonical" href="https://example.com/page-a">
```

**HTTP canonical header conflict:**

Check if your server sends an `**X-Canonical**` or `**Link**` header that conflicts with your HTML canonical:

```bash
curl -I https://example.com/page | grep -i canonical
```

If both exist with different values, they conflict. Choose one method and be consistent.

### 4. Dynamic Canonical Generation

For dynamic sites, generate canonicals programmatically:

```js
// Build canonical from current URL, stripping query params
function getCanonicalUrl() {
  const url = new URL(window.location.href)
  url.search = '' // Remove query parameters
  url.hash = '' // Remove hash
  return url.href
}
```

```php
// PHP example
$canonical = 'https://' . $_SERVER['HTTP_HOST'] . parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
echo '<link rel="canonical" href="' . htmlspecialchars($canonical) . '">';
```

## Framework-Specific Solutions

**Next.js** - Use the Metadata API for automatic canonical handling:

```tsx
export const metadata = {
  alternates: {
    canonical: 'https://example.com/page'
  }
}

// Or dynamically
export async function generateMetadata({ params }) {
  return {
    alternates: {
      canonical: `https://example.com/products/${params.slug}`
    }
  }
}
```

**Nuxt** - Use `**useSeoMeta**` or `**useHead**`:

```html
<script setup>
const route = useRoute()
const config = useRuntimeConfig()

useHead({
  link: [
    { rel: 'canonical', href: `${config.public.siteUrl}${route.path}` }
  ]
})
</script>
```

Or with Nuxt SEO module, it handles canonicals automatically based on your site URL configuration.

## Verify the Fix

After implementing canonical tags:

**1. View page source**

Check that exactly one `**<link rel="canonical">**` appears in `**<head>**` with a valid absolute URL.

**2. Re-run Lighthouse**

The "Document does not have a valid rel=canonical" audit should pass.

**3. Test URL variations**

Visit different versions of your URLs (`**?ref=test**`, `**?utm_source=email**`) and confirm they all have the same canonical pointing to the clean URL.

**4. Check Google Search Console**

Use URL Inspection to see which canonical Google detected. If it differs from yours, Google is overriding your choice - usually because something else signals a different preferred URL.

**5. Validate with curl**

```bash
curl -s https://example.com/page | grep -i canonical
```

Confirm the output shows your expected canonical URL.

## Common Mistakes

- **Canonicalizing to redirected URLs**: If your canonical points to a URL that 301 redirects elsewhere, you're creating a chain. Canonical should point to the final destination.
- **Using relative URLs**: Browsers resolve relative URLs, but search engines may not. Always use absolute URLs with protocol.
- **Canonical in body**: Canonicals in `**<body>**` are ignored by search engines. Must be in `**<head>**`.
- **Dynamic pages forgetting canonical**: SPAs often generate content but forget to update the canonical on route changes. Test each route.
- **Conflicting signals**: Canonicals that disagree with hreflang, sitemap URLs, or internal links confuse search engines. All signals should align.
- **Self-referential with query strings**: If your canonical includes query parameters, you're telling search engines those parameters matter. Usually they don't.
- **Relative URLs without protocol**: Writing `**href="example.com/page"**` (missing `**https://**`) gets interpreted as a subdirectory path and ignored entirely.
- **Pointing to noindex or 404**: Canonicalizing to a page that returns noindex or 404 creates indexing conflicts; Google ignores the canonical.

**Note:** [**~~Duplicate content isn't a penalty~~**](https://developers.google.com/search/blog/2008/09/demystifying-duplicate-content-penalty) - Google simply chooses a canonical version. The risk isn't punishment; it's that Google might choose the wrong version.

## Related Issues

Canonical issues often appear alongside:

- [**~~Hreflang~~**](https://unlighthouse.dev/learn-lighthouse/seo/hreflang) - Canonical and hreflang must agree on the preferred URL
- [**~~Crawlable Anchors~~**](https://unlighthouse.dev/learn-lighthouse/seo/crawlable-anchors) - Internal links should point to canonical URLs
- [**~~Is Crawlable~~**](https://unlighthouse.dev/learn-lighthouse/seo/is-crawlable) - Canonicals to noindexed pages create conflicts

## Test Your Entire Site

A single template bug can add invalid canonicals to thousands of pages. A CMS plugin might inject conflicting canonicals. Pagination might point all pages to page 1. Unlighthouse scans your entire site and flags every page with canonical issues, helping you catch systemic problems before they tank your rankings.

### **Related **

[**SEO Audits Overview**](https://unlighthouse.dev/learn-lighthouse/seo) [**All SEO Issues**](https://unlighthouse.dev/learn-lighthouse/seo#all-seo-audits)

[**SEO** Pass every Lighthouse SEO audit. Crawlability, canonical, meta description, robots.txt, hreflang, status codes — each check explained with fixes and examples.](https://unlighthouse.dev/learn-lighthouse/seo) [**Crawlable Anchors** Learn how to fix anchor elements that search engines can't follow due to missing or invalid href attributes.](https://unlighthouse.dev/learn-lighthouse/seo/crawlable-anchors)

**On this page **

- [What's the Problem?](#whats-the-problem)
- [How to Identify This Issue](#how-to-identify-this-issue)
- [The Fix](#the-fix)
- [Framework-Specific Solutions](#framework-specific-solutions)
- [Verify the Fix](#verify-the-fix)
- [Common Mistakes](#common-mistakes)
- [Related Issues](#related-issues)
- [Test Your Entire Site](#test-your-entire-site)

---

- **Page:** Fix Uncrawlable Links for Better SEO · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/seo/crawlable-anchors
- **Description:** Learn how to fix anchor elements that search engines can't follow due to missing or invalid href attributes.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Uncrawlable Links for Better SEO**

Learn how to fix anchor elements that search engines can't follow due to missing or invalid href attributes.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 18, 2025**

Search engines discover your pages by following links. When your anchor elements don't have proper `**href**` attributes, Googlebot can't crawl them - and those pages won't get indexed.

## What's the Problem?

Modern JavaScript frameworks make it easy to handle clicks without real links. But if there's no valid `**href**`, search engines see a dead end.

Lighthouse flags these patterns as uncrawlable:

**Empty or missing href:**

```html
<a onclick="navigate('/about')">About</a>
<a href="">About</a>
<a href="#">About</a>
```

**JavaScript pseudo-URLs:**

```html
<a href="javascript:void(0)">About</a>
<a href="javascript:">About</a>
```

**Invalid URLs:**

```html
<a href="file:///path/to/file">Download</a>
```

**Click handlers without href:**

```html
<a @click="goToAbout">About</a>
```

Googlebot does execute JavaScript, but it doesn't click on elements. It follows `**href**` attributes. No href, no crawl.

## How to Identify This Issue

### Chrome DevTools

1. Open DevTools (F12) → Elements tab
2. Search for `**<a**` and manually inspect href attributes
3. Or run this in the Console:

```javascript
document.querySelectorAll('a').forEach((a) => {
  const href = a.getAttribute('href')
  if (!href || href === '#' || href === '' || href.startsWith('javascript:')) {
    console.log('Uncrawlable:', a.outerHTML)
  }
})
```

### Lighthouse

Run a Lighthouse SEO audit. Look for "Links are not crawlable" which lists each failing anchor element with its HTML.

## The Fix

### 1. Always Include a Valid href

Every navigation link needs a real URL in the `**href**` attribute.

```html
<!-- Before -->
<a onclick="navigate('/about')">About</a>

<!-- After -->
<a href="/about">About</a>
```

If you need JavaScript behavior, use the href as the fallback:

```html
<a href="/about" onclick="handleClick(event)">About</a>
```

### 2. Replace JavaScript:void(0)

This pattern was common before we had better alternatives. Replace it with a real URL.

```html
<!-- Before -->
<a href="javascript:void(0)" onclick="showModal()">Open Modal</a>

<!-- After: if it's a true navigation -->
<a href="/modal-content">Open Modal</a>

<!-- Or: if it's an action, use a button -->
<button type="button" onclick="showModal()">Open Modal</button>
```

**Rule of thumb:** If clicking takes you to a new page, use `**<a>**` with an href. If it triggers an action on the current page, use `**<button>**`.

### 3. Fix Framework Router Links

Framework routers should handle this automatically, but verify your implementation:

```html
<!-- Vue Router -->
<router-link to="/about">About</router-link>
<!-- Renders: <a href="/about">About</a> ✓ -->

<!-- React Router -->
<Link to="/about">About</Link>
<!-- Renders: <a href="/about">About</a> ✓ -->
```

If you're using custom click handlers instead of router components, switch to the proper router link component.

### 4. Handle Dynamic Navigation

When you generate URLs dynamically, make sure the href is populated at render time - not just on click.

```html
<!-- Before: href is empty until clicked -->
<a href="" @click="href = getProductUrl()">View Product</a>

<!-- After: href is set during render -->
<a :href="productUrl">View Product</a>
```

```javascript
// Compute the URL upfront
const productUrl = computed(() => `/products/${product.id}`)
```

### 5. Fix Anchor Placeholders

If you're using `**<a>**` without href as a placeholder or for styling, reconsider.

```html
<!-- Before: anchor as placeholder -->
<a class="nav-item disabled">Coming Soon</a>

<!-- After: use span for non-links -->
<span class="nav-item disabled">Coming Soon</span>
```

The only valid case for `**<a>**` without href is as a named anchor: `**<a id="section-1"></a>**`. Even then, prefer `**id**` on any element.

### 6. Escape Hatch: ARIA Role

If you must use an anchor without href for technical reasons, add `**role**` to exclude it from the audit:

```html
<a role="button" onclick="showMenu()">Menu</a>
```

But this is a band-aid. Prefer a real `**<button>**` element.

## Framework-Specific Solutions

**Next.js**: Always use the `**Link**` component from `**next/link**`, never raw anchors with click handlers. The Link component renders a proper `**<a>**` with href for crawlers.

**Nuxt**: Use `**NuxtLink**` for all internal navigation. It handles both client-side routing and proper href rendering. Avoid `**@click**` navigation on raw anchors.

## Verify the Fix

1. Run Lighthouse SEO audit again
2. Confirm "Links are crawlable" shows as passing
3. Use "View Page Source" (not DevTools) to see what Googlebot sees before JavaScript runs
4. Check Google Search Console for crawl errors on pages that were previously unreachable

## Common Mistakes

- **Using anchors for buttons**: If it doesn't navigate to a URL, it shouldn't be an `**<a>**`. Use `**<button>**` for actions like modals, dropdowns, and form submissions.
- **Empty href with hash routing**: `**<a href="" @click="$router.push('/about')">**` still fails the audit. Use `**<router-link>**` or include the href.
- **Forgetting SSR rendering**: In SSR apps, check that hrefs are populated during server render, not just after hydration.
- **File protocol links**: `**file:///**` URLs are flagged as uncrawlable because they're not accessible to search engines. Upload files to your server and use http/https URLs.

## Related Issues

Crawlable anchor issues often appear alongside:

- [**~~Link Text~~**](https://unlighthouse.dev/learn-lighthouse/seo/link-text) - Links need both valid hrefs and descriptive text
- [**~~Link Name~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/link-name) - Accessibility also requires links to have names
- [**~~Canonical~~**](https://unlighthouse.dev/learn-lighthouse/seo/canonical) - Links should point to canonical URLs

## Test Your Entire Site

Uncrawlable links often hide in navigation components, footers, or dynamically loaded sections. Unlighthouse scans your entire site and identifies every page with uncrawlable anchors, so you can fix them all at once.

### **Related **

[**SEO Audits Overview**](https://unlighthouse.dev/learn-lighthouse/seo) [**All SEO Issues**](https://unlighthouse.dev/learn-lighthouse/seo#all-seo-audits)

[**Canonical URL** Resolve canonical tag errors that cause duplicate content issues and diluted page authority. Learn to implement rel=canonical correctly.](https://unlighthouse.dev/learn-lighthouse/seo/canonical) [**hreflang** Learn how to fix hreflang validation errors including unexpected language codes and relative URLs in your multi-language site.](https://unlighthouse.dev/learn-lighthouse/seo/hreflang)

**On this page **

- [What's the Problem?](#whats-the-problem)
- [How to Identify This Issue](#how-to-identify-this-issue)
- [The Fix](#the-fix)
- [Framework-Specific Solutions](#framework-specific-solutions)
- [Verify the Fix](#verify-the-fix)
- [Common Mistakes](#common-mistakes)
- [Related Issues](#related-issues)
- [Test Your Entire Site](#test-your-entire-site)

---

- **Page:** Fix Invalid hreflang Tags for Better International SEO · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/seo/hreflang
- **Description:** Learn how to fix hreflang validation errors including unexpected language codes and relative URLs in your multi-language site.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Invalid hreflang Tags for Better International SEO**

Learn how to fix hreflang validation errors including unexpected language codes and relative URLs in your multi-language site.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)5 min read Published **Jan 18, 2025**

The `**hreflang**` attribute tells search engines which version of a page to show users based on their language or region. When it's misconfigured, Google might show French users your English page - or ignore your translations entirely.

**The scale of the problem:** Implementation errors are widespread, and [**~~common hreflang errors and how to fix them~~**](https://developers.google.com/search/docs/specialty/international/localized-versions) are a major focus for international SEO. This is one of the most error-prone SEO implementations.

## What's the Problem?

Lighthouse flags two specific issues with hreflang:

**1. Unexpected Language Code**

Invalid or misspelled language codes mean Google can't identify the language.

```html
<!-- Wrong: "uk" is the country code for Ukraine, not United Kingdom -->
<link rel="alternate" hreflang="uk" href="https://example.com/en-gb/" />

<!-- Wrong: invented language code -->
<link rel="alternate" hreflang="esp" href="https://example.com/es/" />
```

**2. Relative href Value**

The href must be an absolute URL. Relative URLs are rejected.

```html
<!-- Wrong: relative URL -->
<link rel="alternate" hreflang="es" href="/es/" />

<!-- Right: absolute URL -->
<link rel="alternate" hreflang="es" href="https://example.com/es/" />
```

These mistakes are common because hreflang has strict syntax requirements that aren't obvious.

## How to Identify This Issue

### Chrome DevTools

1. Open DevTools (F12) → Elements tab
2. Search for `**hreflang**` in the HTML
3. Verify each link element has:
   - A valid language code (ISO 639-1) or language-region code
   - An absolute URL starting with `**https://**` or `**http://**`

You can also check the response headers for HTTP header-based hreflang:

- Network tab → select the document → Headers → Look for `**Link:**` headers

### Lighthouse

Run a Lighthouse SEO audit. Look for "Document doesn't have a valid hreflang" which shows each failing element with the specific error (unexpected language or relative URL).

## The Fix

### 1. Use Valid Language Codes

Language codes must follow ISO 639-1 (two-letter codes) or BCP 47 format.

```html
<!-- Valid language codes -->
<link rel="alternate" hreflang="en" href="https://example.com/" />
<link rel="alternate" hreflang="es" href="https://example.com/es/" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/" />
<link rel="alternate" hreflang="zh" href="https://example.com/zh/" />

<!-- Valid language-region codes -->
<link rel="alternate" hreflang="en-US" href="https://example.com/en-us/" />
<link rel="alternate" hreflang="en-GB" href="https://example.com/en-gb/" />
<link rel="alternate" hreflang="pt-BR" href="https://example.com/pt-br/" />
<link rel="alternate" hreflang="zh-TW" href="https://example.com/zh-tw/" />
```

Common mistakes to avoid:

- Use `**en-GB**` not `**uk**` for UK English
- Use `**zh-TW**` not `**tw**` for Traditional Chinese
- Use `**es**` not `**esp**` for Spanish
- Use `**pt**` not `**por**` for Portuguese

### 2. Always Use Absolute URLs

Every href must include the full URL with protocol and domain.

```html
<!-- Before: relative URLs -->
<link rel="alternate" hreflang="en" href="/" />
<link rel="alternate" hreflang="es" href="/es/" />

<!-- After: absolute URLs -->
<link rel="alternate" hreflang="en" href="https://example.com/" />
<link rel="alternate" hreflang="es" href="https://example.com/es/" />
```

If you're generating hreflang tags dynamically, construct the full URL:

```javascript
const baseUrl = 'https://example.com'
const hreflangs = [
  { lang: 'en', path: '/' },
  { lang: 'es', path: '/es/' },
  { lang: 'fr', path: '/fr/' },
]

hreflangs.map(h => ({
  rel: 'alternate',
  hreflang: h.lang,
  href: `${baseUrl}${h.path}`,
}))
```

### 3. Include x-default for Fallback

Add `**x-default**` to specify which page to show when no language matches.

```html
<link rel="alternate" hreflang="x-default" href="https://example.com/" />
<link rel="alternate" hreflang="en" href="https://example.com/" />
<link rel="alternate" hreflang="es" href="https://example.com/es/" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/" />
```

Typically, `**x-default**` points to your primary language version or a language selector page.

### 4. Add hreflang to All Alternate Pages

Every page in your hreflang set must include links to all other versions, including itself.

```html
<!-- On https://example.com/ (English) -->
<link rel="alternate" hreflang="en" href="https://example.com/" />
<link rel="alternate" hreflang="es" href="https://example.com/es/" />

<!-- On https://example.com/es/ (Spanish) - must have the same links -->
<link rel="alternate" hreflang="en" href="https://example.com/" />
<link rel="alternate" hreflang="es" href="https://example.com/es/" />
```

If the Spanish page doesn't link back to the English page, Google may ignore the hreflang entirely.

### 5. Choose the Right Implementation

You can implement hreflang in three places:

**HTML head (most common):**

```html
<head>
  <link rel="alternate" hreflang="en" href="https://example.com/" />
  <link rel="alternate" hreflang="es" href="https://example.com/es/" />
</head>
```

**HTTP headers (for non-HTML files like PDFs):**

```http
Link: <https://example.com/file.pdf>; rel="alternate"; hreflang="en",
      <https://example.com/es/file.pdf>; rel="alternate"; hreflang="es"
```

**XML sitemap (for large sites):**

```xml
<url>
  <loc>https://example.com/</loc>
  <xhtml:link rel="alternate" hreflang="en" href="https://example.com/" />
  <xhtml:link rel="alternate" hreflang="es" href="https://example.com/es/" />
</url>
```

Pick one method and stick with it. Lighthouse only checks HTML head and HTTP headers - not sitemaps.

## Framework-Specific Solutions

**Next.js**: Use `**next-intl**` or similar i18n library that handles hreflang automatically. Or add links in your `**_document.js**` or via the `**Head**` component with computed absolute URLs from your domain config.

**Nuxt**: Use `**@nuxtjs/i18n**` module which generates correct hreflang tags automatically. Set `**baseUrl**` in your i18n config so the module generates absolute URLs.

## Verify the Fix

1. Run Lighthouse SEO audit again
2. Confirm "Document has a valid hreflang" shows as passing
3. Use Google Search Console → URL Inspection to verify Google sees your hreflang
4. Check the International Targeting report in Search Console for hreflang errors

## Common Mistakes

- **Forgetting the self-referencing link**: Each page must include an hreflang link to itself. The English page needs `**hreflang="en"**` pointing to itself, not just to other languages.
- **Mixing implementation methods**: Don't use HTML head on some pages and HTTP headers on others. Pick one method for consistency.
- **Not updating hreflang when URLs change**: When you change a URL structure, update all hreflang links across all language versions. Broken links break the entire hreflang cluster.
- **Using hreflang in body**: Hreflang links must be in `**<head>**` or HTTP headers. Links in `**<body>**` are ignored by Lighthouse and may be ignored by search engines.
- **X-default on a page that redirects**: If your x-default URL redirects, it can't link back to the hreflang cluster, creating validation errors.
- **Missing self-referencing tags**: Each page must include an hreflang pointing to itself. This is one of the most [**~~common errors in international SEO implementations~~**](https://developers.google.com/search/docs/specialty/international/localized-versions).

## Related Issues

Hreflang issues often appear alongside:

- [**~~Canonical~~**](https://unlighthouse.dev/learn-lighthouse/seo/canonical) - Canonical URLs must match hreflang URLs
- [**~~HTML Lang~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/html-has-lang) - The HTML lang attribute must match hreflang language
- [**~~Meta Description~~**](https://unlighthouse.dev/learn-lighthouse/seo/meta-description) - Each language version needs unique descriptions

## Test Your Entire Site

Hreflang issues compound across a multilingual site. If your English-to-Spanish links are broken, every page in both languages is affected. Unlighthouse scans your entire site and identifies every page with hreflang errors, so you can fix the pattern once rather than hunting page by page. e by page.

### **Related **

[**SEO Audits Overview**](https://unlighthouse.dev/learn-lighthouse/seo) [**All SEO Issues**](https://unlighthouse.dev/learn-lighthouse/seo#all-seo-audits)

[**Crawlable Anchors** Learn how to fix anchor elements that search engines can't follow due to missing or invalid href attributes.](https://unlighthouse.dev/learn-lighthouse/seo/crawlable-anchors) [**HTTP Status Code** Fix pages returning 4xx or 5xx HTTP status codes that prevent proper indexing. Learn status code meanings, common causes, and how to resolve server errors.](https://unlighthouse.dev/learn-lighthouse/seo/http-status-code)

**On this page **

- [What's the Problem?](#whats-the-problem)
- [How to Identify This Issue](#how-to-identify-this-issue)
- [The Fix](#the-fix)
- [Framework-Specific Solutions](#framework-specific-solutions)
- [Verify the Fix](#verify-the-fix)
- [Common Mistakes](#common-mistakes)
- [Related Issues](#related-issues)
- [Test Your Entire Site](#test-your-entire-site)

---

- **Page:** Fix Unsuccessful HTTP Status Code for Better SEO · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/seo/http-status-code
- **Description:** Fix pages returning 4xx or 5xx HTTP status codes that prevent proper indexing. Learn status code meanings, common causes, and how to resolve server errors.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Unsuccessful HTTP Status Code for Better SEO**

Fix pages returning 4xx or 5xx HTTP status codes that prevent proper indexing. Learn status code meanings, common causes, and how to resolve server errors.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 18, 2025**

Pages returning 4xx or 5xx status codes are invisible to search engines. Google's documentation is explicit: pages with unsuccessful HTTP status codes "may not be indexed properly" - and in practice, they almost never are.

## What's the Problem?

Lighthouse flags "Page has unsuccessful HTTP status code" when your page returns any status code between 400-599. These codes signal to search engines that the page is either unavailable (4xx client errors) or broken (5xx server errors). Googlebot treats both the same way: it won't index the content.

The 4xx range indicates the request was invalid, the page doesn't exist (404), requires authentication (401/403), or the request was malformed. The 5xx range indicates server failures, your code crashed (500), a downstream service failed (502), or the server is overloaded (503). From an SEO perspective, both are equally damaging.

The impact extends beyond the single page. When Googlebot encounters many error responses on your site, it reduces crawl rate, assuming your server can't handle the load. This means even your healthy pages get crawled less frequently, delaying index updates and hurting fresh content discovery.

**Redirect limits:** [**~~Google follows maximum 10 redirect hops~~**](https://developers.google.com/search/docs/crawling-indexing/site-move-with-url-changes) before giving up. Recommend keeping chains to 3-5 hops max. Good news: [**~~301 redirects are recommended for permanent moves~~**](https://developers.google.com/search/docs/crawling-indexing/301-redirects) and consolidate link equity, but chains still waste crawl budget.

## How to Identify This Issue

### Chrome DevTools

1. Open DevTools (F12) and go to the Network tab
2. Reload the page and click on the main document request
3. Check the Status column - anything 400-599 is a problem
4. For 5xx errors, check the Response tab for error messages
5. For 4xx errors, verify the URL is correct and the resource exists

### Lighthouse

Run a Lighthouse SEO audit. The "Page has unsuccessful HTTP status code" audit fails and displays the specific status code (e.g., "404", "500", "503"). This tells you exactly what category of problem you're dealing with.

## The Fix

### 1. Fix 404 Not Found Errors

404s mean the requested URL doesn't map to any content. Common causes:

**Deleted or moved content without redirects:**

```nginx
location /old-page {
    return 301 /new-page;
}

location /blog/ {
    rewrite ^/blog/(.*)$ /articles/$1 permanent;
}
```

```js
// Next.js - next.config.js
export default {
  async redirects() {
    return [
      {
        source: '/old-page',
        destination: '/new-page',
        permanent: true,
      },
    ]
  },
}
```

**Dynamic routes not handling all cases:**

```js
// Check that your dynamic route handler validates the ID exists
export async function GET(request, { params }) {
  const post = await getPost(params.id)

  if (!post) {
    // Return 404 with proper status - don't return 200 with error message
    return new Response('Not Found', { status: 404 })
  }

  return Response.json(post)
}
```

### 2. Fix 500 Internal Server Errors

500 errors indicate unhandled exceptions in your code. Find and fix the root cause:

**Check server logs for stack traces:**

```bash
tail -100 /var/log/nginx/error.log
tail -100 /var/log/your-app/error.log

grep '" 500 ' /var/log/nginx/access.log
```

**Add error boundaries and fallbacks:**

```js
// API route with proper error handling
export async function GET(request) {
  const data = await fetchExternalAPI()
    .catch((err) => {
      console.error('External API failed:', err)
      return null
    })

  if (!data) {
    // Return graceful degradation, not a 500
    return Response.json({ items: [], cached: true })
  }

  return Response.json(data)
}
```

### 3. Fix 502/503 Gateway Errors

These indicate infrastructure problems - your app server crashed, is overloaded, or a reverse proxy can't reach the backend.

**Check upstream service health:**

```nginx
upstream backend {
    server 127.0.0.1:3000 max_fails=3 fail_timeout=30s;
    keepalive 32;
}

server {
    location / {
        proxy_pass http://backend;
        proxy_connect_timeout 5s;
        proxy_read_timeout 60s;
        proxy_next_upstream error timeout http_502 http_503;
    }
}
```

**Implement retry logic for transient failures:**

```js
async function fetchWithRetry(url, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const response = await fetch(url)
      .catch((error) => {
        console.warn('Request attempt failed; retrying.', error)
        return null
      })

    if (response?.ok)
      return response

    // Exponential backoff
    await new Promise(r => setTimeout(r, 2 ** i * 100))
  }

  return null
}
```

### 4. Handle 403 Forbidden Appropriately

If pages require authentication, don't serve them at public URLs:

```js
// Middleware to check auth before serving protected routes
export function middleware(request) {
  const isProtectedRoute = request.nextUrl.pathname.startsWith('/dashboard')
  const hasSession = request.cookies.get('session')

  if (isProtectedRoute && !hasSession) {
    // Redirect to login instead of returning 403
    return Response.redirect(new URL('/login', request.url))
  }
}
```

## Framework-Specific Solutions

**Next.js** - Use `**notFound()**` from `**next/navigation**` to properly return 404s in App Router. For API routes, always return explicit status codes. Configure `**redirects**` in `**next.config.js**` for moved content. Use error boundaries (`**error.tsx**`) to catch and handle errors gracefully.

**Nuxt** - Use `**createError({ statusCode: 404 })**` or `**showError()**` for proper error responses. Configure redirects in `**nuxt.config.ts**` under `**routeRules**`. Create `**error.vue**` at the root for custom error pages. Use `**$fetch**` with error handling instead of raw fetch.

## Verify the Fix

1. Clear any CDN or server caches that might serve stale error responses
2. Request the page directly and check the HTTP status code in DevTools
3. Run Lighthouse SEO audit and confirm the status code audit passes
4. Use `**curl -I https://your-site.com/page**` to verify status code from command line
5. Check Google Search Console's Page Indexing report for coverage issues
6. Request re-indexing in Search Console after fixing persistent errors

## Common Mistakes

- **Custom error pages returning 200**: Your pretty 404 page must still return a 404 status code, not 200. Check your framework's error page configuration.
- **Ignoring intermittent 5xx errors**: Because a page "usually" works doesn't mean Googlebot will catch it on a good day. Monitor error rates and fix flaky endpoints.
- **Blocking Googlebot then wondering why pages aren't indexed**: 403 errors from WAF rules, rate limiting, or geo-blocking prevent indexing. Whitelist known crawler IPs or user agents.
- **Soft 404s**: Returning 200 OK with "Page not found" content. [**~~Google deindexes pages that return 200 OK but have no content (soft 404s)~~**](https://developers.google.com/search/docs/crawling-indexing/http-network-errors#soft-404-errors). Return actual 404 status codes.
- **Using 302/307 for permanent moves**: These provide weak canonicalization signals. Use 301 for permanent redirects to properly consolidate SEO equity.
- **404 for temporarily removed content**: 404 is a strong "don't recrawl" signal. Use 503 with Retry-After header for temporary removals.

## Related Issues

HTTP status code issues often appear alongside:

- [**~~Is Crawlable~~**](https://unlighthouse.dev/learn-lighthouse/seo/is-crawlable) - Both block indexing, but for different reasons
- [**~~Robots.txt~~**](https://unlighthouse.dev/learn-lighthouse/seo/robots-txt) - Check robots isn't blocking before checking status codes
- [**~~Redirects~~**](https://unlighthouse.dev/learn-lighthouse/lcp/redirects) - Redirect chains can end in error codes

## Test Your Entire Site

One broken page is annoying. Fifty broken pages across your site is an SEO disaster. Scan your entire site to find all pages returning error status codes before search engines discover them.

[Scan Your Site with Unlighthouse](https://unlighthouse.dev/)

}

### **Related **

[**SEO Audits Overview**](https://unlighthouse.dev/learn-lighthouse/seo) [**All SEO Issues**](https://unlighthouse.dev/learn-lighthouse/seo#all-seo-audits)

[**hreflang** Learn how to fix hreflang validation errors including unexpected language codes and relative URLs in your multi-language site.](https://unlighthouse.dev/learn-lighthouse/seo/hreflang) [**Blocked from Indexing** Remove crawl blocks preventing search engines from indexing your pages. Fix robots.txt, meta robots, and X-Robots-Tag issues.](https://unlighthouse.dev/learn-lighthouse/seo/is-crawlable)

**On this page **

- [What's the Problem?](#whats-the-problem)
- [How to Identify This Issue](#how-to-identify-this-issue)
- [The Fix](#the-fix)
- [Framework-Specific Solutions](#framework-specific-solutions)
- [Verify the Fix](#verify-the-fix)
- [Common Mistakes](#common-mistakes)
- [Related Issues](#related-issues)
- [Test Your Entire Site](#test-your-entire-site)

---

- **Page:** Fix Page Blocked from Indexing for Better SEO · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/seo/is-crawlable
- **Description:** Remove crawl blocks preventing search engines from indexing your pages. Fix robots.txt, meta robots, and X-Robots-Tag issues.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Page Blocked from Indexing for Better SEO**

Remove crawl blocks preventing search engines from indexing your pages. Fix robots.txt, meta robots, and X-Robots-Tag issues.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)5 min read Published **Jan 18, 2025**

Your page might have perfect content, optimized keywords, and fast loading times - but if search engines can't crawl it, none of that matters. Pages blocked from indexing are invisible to organic search.

**Crawl budget note:** [**~~Noindex wastes crawl budget~~**](https://developers.google.com/search/blog/2024/12/crawling-december-resources) - Google still crawls the page before seeing the tag and dropping it. If you have pages that should never be indexed, consider using robots.txt to block crawling instead.

**JavaScript rendering caveat:** For low-authority sites, [**~~JavaScript rendering happens hours to days after initial crawl~~**](https://www.botify.com/blog/from-crawl-budget-to-render-budget) in a separate queue. If your noindex directive is JavaScript-rendered, Google may have already decided to index before seeing it.

## What's the Problem?

Search engines respect your instructions about what to crawl and index. When you (intentionally or accidentally) tell them "don't index this page," they comply. The page disappears from search results.

Three mechanisms can block indexing:

**1. Meta robots tag**

```html
<meta name="robots" content="noindex">
```

This tells all search engines to not index the page.

**2. X-Robots-Tag HTTP header**

```http
X-Robots-Tag: noindex
```

Same effect, but set at the server level rather than in HTML.

**3. robots.txt disallow**

```text
User-agent: *
Disallow: /private/
```

Prevents crawlers from accessing the URL at all.

The most common cause is accidental. A developer adds `**noindex**` during staging and forgets to remove it before launch. A robots.txt rule intended to block one directory matches more than expected. A CMS setting gets toggled without understanding the consequences.

The result is the same: search engines skip your page entirely, and you get zero organic traffic regardless of how good your content is.

## How to Identify This Issue

### Chrome DevTools

Check for meta robots tags:

1. Open Elements panel
2. Press `**Ctrl/Cmd + F**` and search for `**robots**`
3. Look for `**<meta name="robots">**` with `**noindex**` or `**none**` in the content

```js
// Console check for meta robots
const robotsMeta = document.querySelector('meta[name="robots"]')
if (robotsMeta) {
  const content = robotsMeta.content.toLowerCase()
  if (content.includes('noindex') || content.includes('none')) {
    console.warn('Page is blocked from indexing:', robotsMeta.outerHTML)
  }
}
```

Check HTTP headers in Network panel:

1. Reload with Network panel open
2. Click the main document request
3. Look for `**X-Robots-Tag**` in Response Headers

### Lighthouse

Run a Lighthouse SEO audit. Look for "Page is blocked from indexing" in the results.

The audit checks:

- `**<meta name="robots">**` for `**noindex**` or `**none**` directives
- `**X-Robots-Tag**` HTTP header for blocking directives
- `**robots.txt**` rules that disallow the page URL
- `**unavailable_after**` directives with past dates

Lighthouse tests against major bot user agents: Googlebot, Bingbot, DuckDuckBot, and others. If all bots are blocked, you fail. If at least one is allowed, you pass with a warning.

## The Fix

### 1. Remove Meta Robots Noindex

Find and remove or modify the blocking meta tag:

```html
<!-- Remove this entirely -->
<meta name="robots" content="noindex">
<meta name="robots" content="noindex, nofollow">
<meta name="robots" content="none">

<!-- Or change to allow indexing -->
<meta name="robots" content="index, follow">
```

If you need `**nofollow**` (don't follow links) but want the page indexed:

```html
<meta name="robots" content="index, nofollow">
```

For bot-specific tags, check for both generic and specific:

```html
<!-- These also block indexing -->
<meta name="googlebot" content="noindex">
<meta name="bingbot" content="noindex">
```

### 2. Remove X-Robots-Tag Header

The fix depends on your server:

**Apache (.htaccess):**

```apache
Header set X-Robots-Tag "noindex"

<If "%{REQUEST_URI} =~ m#^/admin/#">
  Header set X-Robots-Tag "noindex"
</If>
```

**Nginx:**

```nginx
add_header X-Robots-Tag "noindex";

location /admin/ {
  add_header X-Robots-Tag "noindex";
}
```

**Node.js/Express:**

```js
// Remove this middleware
app.use((req, res, next) => {
  res.setHeader('X-Robots-Tag', 'noindex')
  next()
})

// Or apply selectively
app.use('/admin', (req, res, next) => {
  res.setHeader('X-Robots-Tag', 'noindex')
  next()
})
```

### 3. Fix robots.txt Rules

Check your robots.txt for overly broad rules:

```txt
User-agent: *
Disallow: /

User-agent: *
Disallow: /admin/
Disallow: /api/
Disallow: /tmp/
```

Common mistakes:

```txt
Disallow: /*?*

Disallow: /*.pdf$

Disallow: /staging  # Also matches /staging-guide, /staging-area
```

Test your robots.txt rules:

```bash
curl https://yourdomain.com/robots.txt
```

Use Google Search Console's robots.txt Tester to verify specific URLs are allowed.

### 4. Check for Conditional Noindex

Some setups add noindex based on conditions:

```js
// Development environment check gone wrong
if (process.env.NODE_ENV !== 'production') {
  // This is correct
}

// But this is dangerous if NODE_ENV isn't set correctly in production
if (!process.env.PRODUCTION) {
  meta.push({ name: 'robots', content: 'noindex' })
}
```

Verify your production environment doesn't have staging configurations.

## Framework-Specific Solutions

**Next.js** - Check your metadata configuration:

```tsx
// Remove robots noindex from your metadata
export const metadata = {
  robots: {
    index: true, // Explicitly allow indexing
    follow: true
  }
}

// For pages that should not be indexed (intentional)
export const metadata = {
  robots: {
    index: false,
    follow: false
  }
}
```

Also check `**next.config.js**` for any custom headers adding X-Robots-Tag.

**Nuxt** - Check `**nuxt.config.ts**` and page-level settings:

```ts
// nuxt.config.ts - remove if blocking unintentionally
export default defineNuxtConfig({
  app: {
    head: {
      meta: [
        // Remove this if present
        // { name: 'robots', content: 'noindex' }
      ]
    }
  }
})
```

```html
<script setup>
// Page-level - only use for pages that shouldn't be indexed
useSeoMeta({
  robots: 'index, follow'
})
</script>
```

## Verify the Fix

After removing indexing blocks:

**1. Re-run Lighthouse**

The "Page is blocked from indexing" audit should pass.

**2. Check multiple sources**

Verify all three mechanisms are clear:

```bash
curl -s https://example.com/page | grep -i "robots"

curl -I https://example.com/page | grep -i "x-robots"

curl -s https://example.com/robots.txt
```

**3. Google Search Console**

Use URL Inspection to submit the page for indexing. The tool shows exactly what Google sees and whether indexing is allowed.

**4. Wait and verify indexing**

Search `**site:example.com/page-url**` after a few days. If the page appears, it's being indexed correctly.

## Common Mistakes

- **Removing noindex from pages that should be blocked**: Admin pages, user dashboards, checkout flows, and internal tools should remain noindexed. Don't remove blocks without understanding why they exist.
- **Leaving robots.txt Disallow in place**: Removing meta noindex but keeping robots.txt Disallow means crawlers still can't access the page. Both need to be addressed.
- **Environment-specific configurations leaking**: Staging settings deployed to production is extremely common. Always verify production environment after deployments.
- **CMS settings overriding code**: WordPress, Shopify, and other CMS platforms have their own SEO settings that might add noindex. Check the CMS configuration, not just the code.
- **Expired unavailable\_after dates**: The directive `**unavailable_after: 01-Jan-2024**` blocks indexing after that date. If you used this for temporary content, remove it when you want the content back.
- **CDN or proxy adding headers**: [**~~Cloudflare~~**](https://cloudflare.com), Fastly, or your CDN might add X-Robots-Tag. Check your edge configuration, not just origin server.

## Related Issues

Crawlability issues often appear alongside:

- [**~~Robots.txt~~**](https://unlighthouse.dev/learn-lighthouse/seo/robots-txt) - Check robots.txt for Disallow rules blocking the page
- [**~~HTTP Status Code~~**](https://unlighthouse.dev/learn-lighthouse/seo/http-status-code) - Both prevent indexing, diagnose which applies
- [**~~Canonical~~**](https://unlighthouse.dev/learn-lighthouse/seo/canonical) - Noindexed pages shouldn't be canonical targets

## Test Your Entire Site

One misconfigured template can block thousands of pages. A robots.txt typo can exclude your entire site. CMS updates can reset SEO settings to defaults. Unlighthouse scans every URL on your site and identifies every page blocked from indexing, so you can catch issues that would otherwise remain invisible until you notice organic traffic dropping.

### **Related **

[**SEO Audits Overview**](https://unlighthouse.dev/learn-lighthouse/seo) [**All SEO Issues**](https://unlighthouse.dev/learn-lighthouse/seo#all-seo-audits)

[**HTTP Status Code** Fix pages returning 4xx or 5xx HTTP status codes that prevent proper indexing. Learn status code meanings, common causes, and how to resolve server errors.](https://unlighthouse.dev/learn-lighthouse/seo/http-status-code) [**Link Text** Learn how to replace generic link text like "click here" with descriptive text that helps search engines understand your content.](https://unlighthouse.dev/learn-lighthouse/seo/link-text)

**On this page **

- [What's the Problem?](#whats-the-problem)
- [How to Identify This Issue](#how-to-identify-this-issue)
- [The Fix](#the-fix)
- [Framework-Specific Solutions](#framework-specific-solutions)
- [Verify the Fix](#verify-the-fix)
- [Common Mistakes](#common-mistakes)
- [Related Issues](#related-issues)
- [Test Your Entire Site](#test-your-entire-site)

---

- **Page:** Fix Non-Descriptive Link Text for Better SEO · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/seo/link-text
- **Description:** Learn how to replace generic link text like "click here" with descriptive text that helps search engines understand your content.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Non-Descriptive Link Text for Better SEO**

Learn how to replace generic link text like "click here" with descriptive text that helps search engines understand your content.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)4 min read Published **Jan 18, 2025**

Links with generic text like "click here" or "read more" tell search engines nothing about the destination page. Google uses anchor text to understand what the linked page is about - and you're wasting that signal.

**Accessibility overlap:** "Click here" links fail for both SEO and accessibility. Screen reader users navigating by links hear "click here, click here, click here" with no context. [**~~For linked images, alt text functions as anchor text~~**](https://developers.google.com/search/docs/crawling-indexing/links-crawlable) - so empty alt on image links means zero anchor text signal.

## What's the Problem?

When you write `**<a href="/pricing">click here</a>**` instead of `**<a href="/pricing">view our pricing plans</a>**`, you're missing two opportunities:

**1. Search Engine Context**

Anchor text is one of the signals Google uses to understand what a page is about. When multiple sites link to your page with descriptive text like "Vue.js documentation," Google associates those terms with your page. Internal links work the same way - they help Google understand the relationship between your pages.

**2. Accessibility**

Screen reader users often navigate by jumping between links. Hearing "click here, click here, click here" tells them nothing. They need context without reading surrounding text.

Lighthouse flags these generic phrases as non-descriptive:

- "click here" / "click this"
- "here" / "this"
- "read more" / "learn more" / "more"
- "go" / "start"
- "more info" / "more information"
- "see more" / "information"

The audit also detects equivalents in Japanese, Spanish, Portuguese, Korean, Swedish, German, Tamil, and Persian.

## How to Identify This Issue

### Chrome DevTools

1. Open DevTools (F12) → Elements tab
2. Press Ctrl+F (or Cmd+F on Mac) to search
3. Search for common offenders: `**>click here<**`, `**>read more<**`, `**>here<**`
4. Review each match and its destination

### Lighthouse

Run a Lighthouse SEO audit. Look for "Links do not have descriptive text" in the results. The audit lists each failing link with its destination URL and current text.

## The Fix

### 1. Describe the Destination

Replace generic text with words that describe where the link goes.

```html
<!-- Before -->
<p>To see our products, <a href="/products">click here</a>.</p>

<!-- After -->
<p>Browse our <a href="/products">complete product catalog</a>.</p>
```

```html
<!-- Before -->
<a href="/docs/getting-started">Learn more</a>

<!-- After -->
<a href="/docs/getting-started">Get started with our API</a>
```

The destination should be obvious from the link text alone.

### 2. Include Keywords Naturally

Use anchor text that includes relevant keywords for the destination page - but keep it natural.

```html
<!-- Before -->
<p>For help with deployment, <a href="/docs/deploy">click here</a>.</p>

<!-- After -->
<p>Our <a href="/docs/deploy">deployment documentation</a> covers all hosting options.</p>
```

Don't stuff keywords. "Click here for cheap flights booking discount airline tickets" is worse than "click here."

### 3. Avoid Redundant Phrases

Don't repeat "link" or "click" in anchor text - users know it's clickable.

```html
<!-- Bad -->
<a href="/about">Click this link to learn about us</a>

<!-- Good -->
<a href="/about">About our company</a>
```

### 4. Keep Context in Mind

Surrounding text provides context. That's fine for humans, but search engines evaluate links independently.

```html
<!-- Seems okay, but fails the audit -->
<p>Check out our new features. <a href="/features">Read more</a></p>

<!-- Better: context is in the link itself -->
<p>Check out our <a href="/features">new feature announcements</a>.</p>
```

### 5. Handle Repeated Links

When linking to the same destination multiple times, vary the text while keeping it descriptive.

```html
<!-- First mention -->
<a href="/pricing">pricing plans</a>

<!-- Later in the page -->
<a href="/pricing">compare our plans</a>
```

## Framework-Specific Solutions

**Next.js**: Use the `**Link**` component with descriptive child text. If you're using a design system with generic button text, override it at the component level or create a wrapper that enforces descriptive text.

**Nuxt**: Same principle with `**NuxtLink**`. If you have a component library with "Read more" buttons, consider a linting rule or component prop that requires descriptive text.

## Verify the Fix

1. Run Lighthouse SEO audit again
2. Confirm "Links have descriptive text" shows as passing
3. Manually spot-check key pages for remaining generic links
4. Test with a screen reader (VoiceOver on Mac, NVDA on Windows) to verify links make sense in isolation

## Common Mistakes

- **Over-optimizing anchor text**: "Best cheap affordable budget software solution" reads like spam. Keep it natural: "our pricing" or "project management software."
- **Using image-only links without alt text**: An image link with no alt text has no anchor text at all. Add descriptive alt text: `**<a href="/"><img src="logo.png" alt="Company Name homepage"></a>**`
- **Hiding descriptive text**: Don't hide descriptive text with CSS to "trick" the audit. Search engines can detect this. Make it visible for everyone.
- **Ignoring nofollow links**: Lighthouse skips `**rel="nofollow"**` links since they don't pass SEO value anyway. But they still matter for accessibility - fix them too.

## Related Issues

Link text issues often appear alongside:

- [**~~Crawlable Anchors~~**](https://unlighthouse.dev/learn-lighthouse/seo/crawlable-anchors) - Links need both valid hrefs and descriptive text
- [**~~Link Name~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/link-name) - Both SEO and accessibility require descriptive links
- [**~~Image Alt~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/image-alt) - Image links get their text from alt attributes

## Test Your Entire Site

Generic link text is often a pattern - if one "click here" slipped through, there are probably more. Unlighthouse scans your entire site and identifies every page with non-descriptive link text, so you can fix them systematically.

### **Related **

[**SEO Audits Overview**](https://unlighthouse.dev/learn-lighthouse/seo) [**All SEO Issues**](https://unlighthouse.dev/learn-lighthouse/seo#all-seo-audits)

[**Blocked from Indexing** Remove crawl blocks preventing search engines from indexing your pages. Fix robots.txt, meta robots, and X-Robots-Tag issues.](https://unlighthouse.dev/learn-lighthouse/seo/is-crawlable) [**Meta Description** Add compelling meta descriptions to improve click-through rates from search results. Learn how to write effective descriptions that drive traffic.](https://unlighthouse.dev/learn-lighthouse/seo/meta-description)

**On this page **

- [What's the Problem?](#whats-the-problem)
- [How to Identify This Issue](#how-to-identify-this-issue)
- [The Fix](#the-fix)
- [Framework-Specific Solutions](#framework-specific-solutions)
- [Verify the Fix](#verify-the-fix)
- [Common Mistakes](#common-mistakes)
- [Related Issues](#related-issues)
- [Test Your Entire Site](#test-your-entire-site)

---

- **Page:** Fix Missing Meta Description for Better SEO · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/seo/meta-description
- **Description:** Add compelling meta descriptions to improve click-through rates from search results. Learn how to write effective descriptions that drive traffic.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Missing Meta Description for Better SEO**

Add compelling meta descriptions to improve click-through rates from search results. Learn how to write effective descriptions that drive traffic.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)5 min read Published **Jan 18, 2025**

Pages with custom meta descriptions get 5.8% higher click-through rates than those using auto-generated snippets. Without one, Google decides what to show - and it's rarely optimal.

**Reality check:** [**~~Google often rewrites meta descriptions~~**](https://developers.google.com/search/docs/appearance/snippet#meta-descriptions) anyway, choosing to display content it thinks better matches the query. And [**~~many top-ranking pages lack explicit meta descriptions~~**](https://developers.google.com/search/docs/appearance/snippet). So missing descriptions won't prevent ranking - but you lose control of what appears in search results.

## What's the Problem?

When your page lacks a meta description, search engines generate one automatically by extracting text from your page content. This sounds helpful until you realize the algorithm doesn't understand context, value propositions, or what makes users click.

Google might pull a random sentence from your footer. Bing might grab your cookie policy notice. The result is a search snippet that fails to communicate why someone should visit your page over the other nine results.

**The technical issue is simple:** Lighthouse checks for a `**<meta name="description">**` tag in your document head. If it's missing or empty, you fail the audit. But the real problem is strategic - you're giving up control of the single piece of text that represents your page in search results.

Consider what happens when someone searches for "best project management software":

- **With meta description:** "Compare 15 project management tools with real user reviews. Find the right fit for teams of 1-1000. Updated January 2025."
- **Without meta description:** "...cookies to improve your experience. By continuing to use this site..."

One gets clicked. One gets scrolled past.

## How to Identify This Issue

### Chrome DevTools

Open the Elements panel and search for `**meta name="description"**`:

1. Press `**Ctrl/Cmd + F**` in Elements panel
2. Search for `**meta name="description"**`
3. Check if it exists and has content

Quick console check:

```js
const meta = document.querySelector('meta[name="description"]')
console.log(meta ? meta.content : 'No meta description found')
```

If the content is empty or missing entirely, you have the issue.

### Lighthouse

Run a Lighthouse SEO audit. Look for "Document does not have a meta description" in the results. The audit is binary - you either have a valid meta description or you don't.

Lighthouse specifically checks that:

- A `**<meta name="description">**` element exists in the document
- The `**content**` attribute contains non-empty text (not just whitespace)

## The Fix

### 1. Add the Meta Description Tag

Place this in your document's `**<head>**`:

```html
<head>
  <meta name="description" content="Your compelling description here. Aim for 150-160 characters that summarize the page and encourage clicks.">
</head>
```

Write descriptions that:

- Summarize what the page offers in 150-160 characters
- Include relevant keywords naturally (not stuffed)
- Contain a value proposition or call to action
- Are unique to each page

**Examples by page type:**

```html
<!-- Homepage -->
<meta name="description" content="Open-source project management for developers. GitHub integration, Kanban boards, and sprint planning. Free for teams up to 10.">

<!-- Product page -->
<meta name="description" content="Wireless noise-canceling headphones with 40-hour battery life. Premium audio, comfortable fit, and seamless device switching. Ships free.">

<!-- Blog post -->
<meta name="description" content="Step-by-step guide to migrating from REST to GraphQL without breaking your existing clients. Includes code examples and rollback strategies.">

<!-- Documentation -->
<meta name="description" content="Complete API reference for the Authentication module. Covers OAuth 2.0 flows, JWT tokens, refresh handling, and error codes.">
```

### 2. Template-Based Descriptions

For sites with many similar pages, create templates:

```html
<!-- Product template -->
<meta name="description" content="Buy {product_name} - {key_feature}. {price}. Free shipping on orders over $50.">

<!-- Category template -->
<meta name="description" content="Shop {category_name} - {product_count} items. Filter by {popular_filters}. Fast delivery.">

<!-- Blog template -->
<meta name="description" content="{first_150_chars_of_content}">
```

Templated descriptions are better than none, but custom descriptions outperform templates when you have the resources.

### 3. Dynamic Meta Descriptions

For SPAs and dynamic content, set descriptions programmatically:

```js
// Vanilla JS
// React Helmet
import { Helmet } from 'react-helmet'

function setMetaDescription(content) {
  let meta = document.querySelector('meta[name="description"]')
  if (!meta) {
    meta = document.createElement('meta')
    meta.name = 'description'
    document.head.appendChild(meta)
  }
  meta.content = content
}

function ProductPage({ product }) {
  return (
    <>
      <Helmet>
        <meta name="description" content={`${product.name} - ${product.shortDescription}`} />
      </Helmet>
      {/* page content */}
    </>
  )
}
```

## Framework-Specific Solutions

**Next.js** - Use the Metadata API in App Router:

```tsx
export const metadata = {
  description: 'Your page description here'
}

// Or generate dynamically
export async function generateMetadata({ params }) {
  const product = await getProduct(params.id)
  return { description: product.summary }
}
```

**Nuxt** - Use `**useSeoMeta**` composable:

```html
<script setup>
useSeoMeta({
  description: 'Your page description here'
})

// Or with dynamic data
const { data: product } = await useFetch('/api/product')
useSeoMeta({
  description: product.value.summary
})
</script>
```

## Verify the Fix

After adding meta descriptions:

**1. View page source**

Press `**Ctrl/Cmd + U**` and search for `**meta name="description"**`. Confirm it appears in the `**<head>**` with your content.

**2. Re-run Lighthouse**

The "Document does not have a meta description" audit should pass. If it still fails, check that:

- The tag is in `**<head>**`, not `**<body>**`
- The `**content**` attribute isn't empty
- The HTML has no syntax errors

**3. Test in Google Search Console**

Use the URL Inspection tool to see how Google renders your page. Check that Google detects the meta description.

**4. Preview your snippet**

Search for `**site:yourdomain.com/page-url**` to see how the description appears in actual search results. Note that Google may choose to show different text if it believes it better matches the query.

## Common Mistakes

- **Duplicate descriptions across pages**: Every page needs a unique description. Using the same text everywhere dilutes your SEO and confuses users about page differences.
- **Descriptions over 160 characters**: Google truncates long descriptions with "...". Keep the most important information in the first 120 characters.
- **Keyword stuffing**: "Best project management software, top project management, free project management tool" reads like spam and may hurt rankings.
- **Descriptions that don't match content**: If your description promises something the page doesn't deliver, users bounce immediately. Google notices.
- **Forgetting dynamic pages**: SPAs often fail to update meta tags on navigation. Test each route, not just the initial load.
- **Empty content attribute**: `**<meta name="description" content="">**` technically exists but fails the audit. The content must have actual text.

## Related Issues

Meta description issues often appear alongside:

- [**~~Document Title~~**](https://unlighthouse.dev/learn-lighthouse/accessibility/document-title) - Both are critical document metadata
- [**~~Canonical~~**](https://unlighthouse.dev/learn-lighthouse/seo/canonical) - Pages with duplicate descriptions may need canonicalization
- [**~~Hreflang~~**](https://unlighthouse.dev/learn-lighthouse/seo/hreflang) - Each language version needs unique descriptions

## Test Your Entire Site

One template with a missing meta description could affect thousands of pages. A CMS update might have broken your SEO plugin. Unlighthouse scans every URL on your site and flags pages missing meta descriptions, so you can catch issues across your entire domain, not just the pages you remember to check.

### **Related **

[**SEO Audits Overview**](https://unlighthouse.dev/learn-lighthouse/seo) [**All SEO Issues**](https://unlighthouse.dev/learn-lighthouse/seo#all-seo-audits)

[**Link Text** Learn how to replace generic link text like "click here" with descriptive text that helps search engines understand your content.](https://unlighthouse.dev/learn-lighthouse/seo/link-text) [**Invalid robots.txt** Fix robots.txt validation errors that prevent search engines from properly crawling your site. Learn syntax rules, common errors, and proper configuration.](https://unlighthouse.dev/learn-lighthouse/seo/robots-txt)

**On this page **

- [What's the Problem?](#whats-the-problem)
- [How to Identify This Issue](#how-to-identify-this-issue)
- [The Fix](#the-fix)
- [Framework-Specific Solutions](#framework-specific-solutions)
- [Verify the Fix](#verify-the-fix)
- [Common Mistakes](#common-mistakes)
- [Related Issues](#related-issues)
- [Test Your Entire Site](#test-your-entire-site)

---

- **Page:** Fix Invalid robots.txt for Better SEO · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/seo/robots-txt
- **Description:** Fix robots.txt validation errors that prevent search engines from properly crawling your site. Learn syntax rules, common errors, and proper configuration.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Fix Invalid robots.txt for Better SEO**

Fix robots.txt validation errors that prevent search engines from properly crawling your site. Learn syntax rules, common errors, and proper configuration.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw)5 min read Published **Jan 18, 2025**

A malformed robots.txt file can silently prevent Google from crawling your entire site. According to Google Search Console data, 23% of websites have robots.txt configuration errors that affect their search visibility.

**Key limits to know:**

- [**~~Max file size: 500 KiB~~**](https://developers.google.com/search/docs/crawling-indexing/robots/intro) - Google stops processing midway if larger
- [**~~Sitemap limits: 50,000 URLs OR 50MB uncompressed~~**](https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap) (whichever first)
- [**~~Google ignores ~~**`**crawl-delay**`](https://developers.google.com/search/blog/2019/07/a-note-on-unsupported-rules-in-robotstxt) - retired all code handling it on Sept 1, 2019

## What's the Problem?

Lighthouse flags "robots.txt is not valid" when your robots.txt file contains syntax errors, malformed directives, or structural problems that crawlers cannot parse correctly. When search engine bots encounter an invalid robots.txt, they may interpret your crawling instructions incorrectly or ignore them entirely.

The robots.txt file follows a strict specification. Each directive must be on its own line, use a colon separator, and follow specific formatting rules. Common errors include missing colons, invalid URL patterns, directives without a preceding User-agent declaration, and unrecognized directive names. These seem like minor issues, but they can cascade into major crawling problems.

The stakes are high: if Googlebot misinterprets your robots.txt, it might crawl pages you wanted blocked (wasting crawl budget and potentially indexing private content) or skip pages you wanted indexed (killing your search rankings). A single syntax error can flip the meaning of your entire file.

## How to Identify This Issue

### Chrome DevTools

1. Navigate to `**https://your-site.com/robots.txt**` directly
2. Look for obvious syntax errors: missing colons, typos in directive names
3. Check that every Allow/Disallow directive has a User-agent above it
4. Verify sitemap URLs are fully qualified (include https://)

### Lighthouse

Run a Lighthouse SEO audit. The "robots.txt is not valid" audit will fail and display:

- The specific line number where errors occur
- The problematic content on that line
- A description of what's wrong (e.g., "Unknown directive", "No user-agent specified")

Lighthouse also fails this audit when the robots.txt request returns a 5xx server error, indicating your server cannot reliably serve the file.

## The Fix

### 1. Correct Basic Syntax Errors

Every directive needs the format `**Directive: value**` with a colon separator:

```txt
User-agent *
Disallow /admin

User-agent: *
Disallow: /admin
```

Group member directives (Allow, Disallow) must always follow a User-agent declaration:

```txt
Disallow: /private/

User-agent: *
Disallow: /private/
```

### 2. Fix URL Pattern Errors

Allow and Disallow patterns must start with `**/**`, `*****`, or be empty:

```txt
Disallow: admin/
Disallow: private

Disallow: /admin/
Disallow: /private
Disallow: *private*
Disallow:  # Empty disallow (allows everything)
```

The `**$**` wildcard is only valid at the end of a pattern:

```txt
Disallow: /page$.html

Disallow: /page.html$
```

### 3. Validate Sitemap URLs

Sitemap directives require fully qualified URLs with valid protocols:

```txt
Sitemap: /sitemap.xml

Sitemap: ftp://example.com/sitemap.xml

Sitemap: https://example.com/sitemap.xml
```

### 4. Use Only Recognized Directives

Stick to universally supported directives. Unknown directives cause validation failures:

```txt
User-agent: *
Allow: /
Disallow: /admin/
Sitemap: https://example.com/sitemap.xml

Crawl-delay: 10
```

### Complete Valid Example

```txt
User-agent: *
Allow: /
Disallow: /admin/
Disallow: /api/
Disallow: /private/
Disallow: /*.json$

User-agent: GPTBot
Disallow: /

User-agent: CCBot
Disallow: /

Sitemap: https://example.com/sitemap.xml
Sitemap: https://example.com/sitemap-blog.xml
```

## Framework-Specific Solutions

**Next.js** - Create `**public/robots.txt**` for static content, or use `**app/robots.ts**` for dynamic generation. [**~~Next.js~~**](https://nextjs.org) serves files from `**public/**` at the root path automatically. For dynamic robots.txt based on environment, export a `**robots()**` function from `**app/robots.ts**`.

**Nuxt** - Place `**robots.txt**` in the `**public/**` directory, or use the `**@nuxtjs/robots**` module for dynamic generation. The module supports environment-based configuration and automatic sitemap URL injection via `**nuxt.config.ts**`.

## Verify the Fix

1. Navigate to `**https://your-site.com/robots.txt**` and visually inspect for errors
2. Use Google Search Console's robots.txt Tester (Settings > robots.txt)
3. Run Lighthouse SEO audit and confirm the robots.txt audit passes
4. Test specific URLs with Google's URL Inspection tool to verify intended behavior
5. Check server logs to check that robots.txt returns 200 status consistently

## Common Mistakes

- **Blocking CSS and JavaScript**: Don't block `**/css/**` or `**/js/**` directories. Googlebot needs these to render your pages correctly. Blocking render resources hurts your rankings.
- **Using robots.txt for sensitive content**: robots.txt is public and doesn't prevent indexing if pages are linked elsewhere. Use `**noindex**` meta tags or authentication for truly private content.
- **Forgetting trailing slashes**: `**/admin**` blocks only the `**/admin**` file, while `**/admin/**` blocks the directory. Be explicit about what you're blocking.
- **Testing only in production**: Many sites serve different robots.txt in staging vs production. Validate your production file, not your local one.
- **Unicode BOM at start of file**: A byte-order mark makes Google ignore invalid lines including the BOM character.
- **robots.txt in subdirectory**: Invalid. Must be in domain root ( `**/robots.txt**`). Bots won't find it anywhere else.
- **Path values not starting with `**/**` or `*****`** - Directive values like `**Disallow: admin/**` (missing leading slash) are invalid and ignored.

## Related Issues

Robots.txt issues often appear alongside:

- [**~~Is Crawlable~~**](https://unlighthouse.dev/learn-lighthouse/seo/is-crawlable) - Robots.txt can block pages from indexing
- [**~~HTTP Status Code~~**](https://unlighthouse.dev/learn-lighthouse/seo/http-status-code) - A 404 robots.txt causes different behavior than missing
- [**~~Canonical~~**](https://unlighthouse.dev/learn-lighthouse/seo/canonical) - Don't block canonical URLs in robots.txt

## Test Your Entire Site

A valid robots.txt is the first step. Search engines still need to successfully crawl and index your pages. Run a complete scan to verify your entire site is accessible and returns proper status codes.

[Scan Your Site with Unlighthouse](https://unlighthouse.dev/)

### **Related **

[**SEO Audits Overview**](https://unlighthouse.dev/learn-lighthouse/seo) [**All SEO Issues**](https://unlighthouse.dev/learn-lighthouse/seo#all-seo-audits)

[**Meta Description** Add compelling meta descriptions to improve click-through rates from search results. Learn how to write effective descriptions that drive traffic.](https://unlighthouse.dev/learn-lighthouse/seo/meta-description) 

**On this page **

- [What's the Problem?](#whats-the-problem)
- [How to Identify This Issue](#how-to-identify-this-issue)
- [The Fix](#the-fix)
- [Framework-Specific Solutions](#framework-specific-solutions)
- [Verify the Fix](#verify-the-fix)
- [Common Mistakes](#common-mistakes)
- [Related Issues](#related-issues)
- [Test Your Entire Site](#test-your-entire-site)

---

- **Page:** Troubleshooting Playwright Lighthouse Integration · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/playwright/troubleshooting
- **Description:** Fix common issues when running Lighthouse with Playwright: port conflicts, authentication problems, flaky scores, and Chrome version mismatches.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Troubleshooting Playwright Lighthouse Integration**

Fix common issues when running Lighthouse with Playwright: port conflicts, authentication problems, flaky scores, and Chrome version mismatches.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw) Published **Jan 27, 2026** Updated **Aug 9, 2026**

Common issues and solutions when integrating Lighthouse with [**~~Playwright~~**](https://playwright.dev).

## Port Already in Use

**Error**: `**Error: listen EADDRINUSE: address already in use :::9222**`

The debugging port is already occupied, usually from a previous run that didn't close properly.

**Solution**: Identify the process before stopping it, or assign a different port:

```bash
# Show the process listening on port 9222
lsof -nP -iTCP:9222 -sTCP:LISTEN
```

```js
const PORT = 9223
```

For CI environments, use proper cleanup:

```js
async function audit() {
  let browser
  try {
    browser = await chromium.launch({
      args: [`--remote-debugging-port=${PORT}`],
    })
    // ... audit logic
  }
  finally {
    if (browser)
      await browser.close()
  }
}
```

## Authentication State Lost

**Symptom**: Lighthouse audits a login page instead of the authenticated page.

**Cause**: Lighthouse opens a new page context, losing cookies/session.

**Solution**: Use `**disableStorageReset: true**`:

```js
const result = await lighthouse(url, {
  port: PORT,
  disableStorageReset: true, // Prevents Lighthouse from clearing storage
})
```

See [**~~Authentication Guide~~**](https://unlighthouse.dev/learn-lighthouse/playwright/authentication) for complete examples.

## Flaky or Inconsistent Scores

**Symptom**: Performance scores vary significantly between runs (±10-20 points).

**Causes**:

- Network variability
- CPU load on the machine
- Shared CI runners
- Third-party script timing

**Solutions**:

1. **Run multiple audits and use median**:

```js
const runs = 3
const scores = []
for (let i = 0; i < runs; i++) {
  const result = await lighthouse(url, { port: PORT })
  scores.push(result.lhr.categories.performance.score)
}
scores.sort((a, b) => a - b)
const median = scores[Math.floor(scores.length / 2)]
```

1. **Use the provided network without Lighthouse simulation for local diagnostics**:

```js
const result = await lighthouse(url, {
  port: PORT,
  throttlingMethod: 'provided',
})
```

Use simulated throttling again for performance budgets. Unthrottled scores describe your test machine and should not be compared with PageSpeed Insights.

1. **Use dedicated CI runners** instead of shared ones.

## Chrome/Chromium Version Mismatch

**Error**: `**Protocol error**` or `**Target closed**` or `**Cannot find context with specified id**`

**Cause**: The installed Playwright package, browser binary, and Lighthouse version came from different lockfile states or caches.

**Solution**: Check the installed versions, reinstall Playwright's matching Chromium, and let Playwright use its bundled executable:

```bash
npm ls @playwright/test lighthouse
npx playwright install chromium
```

Playwright warns that custom executables may not work with its APIs. If you deliberately test branded Chrome, select a supported channel and keep that choice explicit:

```js
const browser = await chromium.launch({
  channel: 'chrome',
  args: [`--remote-debugging-port=${PORT}`],
})
```

## Timeout Errors

**Error**: `**Lighthouse timeout**` or `**Navigation timeout exceeded**`

**Causes**:

- Page takes too long to load
- `**waitUntil: 'networkidle'**` waiting for never-ending requests
- Large pages with many resources

**Solutions**:

1. **Increase Lighthouse timeout**:

```js
const result = await lighthouse(url, {
  port: PORT,
  maxWaitForLoad: 60000, // 60 seconds (default is 45s)
})
```

1. **Use different wait strategy**:

```js
// Instead of networkidle, wait for specific element
await page.goto(url)
await page.waitForSelector('#main-content')
```

1. **Check for infinite polling requests** (analytics, websockets).

## Sandbox Errors

**Error**: `**No usable sandbox!**` or `**Running as root without --no-sandbox is not supported**`

**Cause**: Chrome sandboxing issues, common in Docker/CI.

**Solution**: Disable sandbox (only in trusted CI environments):

```js
const browser = await chromium.launch({
  args: [
    `--remote-debugging-port=${PORT}`,
    '--no-sandbox',
    '--disable-setuid-sandbox',
  ],
})
```

Only disable sandbox in controlled CI environments, never in production or when processing untrusted URLs.

## Multiple Concurrent Audits Fail

**Error**: Audits interfere with each other or return incorrect results.

**Cause**: Multiple Lighthouse instances trying to use the same debugging port.

**Solution**: Use different ports for parallel audits:

```js
async function auditWithDynamicPort(url) {
  const port = 9222 + Math.floor(Math.random() * 1000)
  const browser = await chromium.launch({
    args: [`--remote-debugging-port=${port}`],
  })
  // ... use `port` variable
}
```

Or run audits sequentially with a single worker:

```bash
# Playwright Test
npx playwright test --workers=1
```

## Lighthouse Reports Show Wrong Page

**Symptom**: Report shows homepage or login page instead of target URL.

**Causes**:

- Redirects before audit runs
- Authentication issues
- URL mismatch between Playwright navigation and Lighthouse call

**Solution**: Verify URL after navigation:

```js
await page.goto(targetUrl, { waitUntil: 'networkidle' })

// Check actual URL
const actualUrl = page.url()
if (actualUrl !== targetUrl) {
  console.warn(`Redirected from ${targetUrl} to ${actualUrl}`)
}

// Use actual URL for Lighthouse
const result = await lighthouse(actualUrl, { port: PORT })
```

## Empty or Incomplete Reports

**Symptom**: Lighthouse report missing metrics or categories.

**Causes**:

- Page not fully loaded
- JavaScript errors on page
- Missing viewport settings

**Solution**: Check page readiness:

```js
await page.goto(url, { waitUntil: 'networkidle' })

// Wait for critical content
await page.waitForSelector('[data-testid="main-content"]')

// Check for console errors
page.on('console', (msg) => {
  if (msg.type() === 'error')
    console.warn('Page error:', msg.text())
})
```

## CI-Specific Issues

### GitHub Actions: Chrome Not Found

```yaml
- name: Install Chrome
  run: npx playwright install chromium --with-deps
```

The `**--with-deps**` flag installs system dependencies required by Chromium.

### Docker: Missing Dependencies

Add to Dockerfile:

```dockerfile
RUN apt-get update && apt-get install -y \
    libnss3 \
    libatk1.0-0 \
    libatk-bridge2.0-0 \
    libcups2 \
    libdrm2 \
    libxkbcommon0 \
    libxcomposite1 \
    libxdamage1 \
    libxrandr2 \
    libgbm1 \
    libasound2
```

Or use Playwright's [**~~Docker image~~**](https://playwright.dev/docs/docker). Pin the image tag to the same Playwright version as `**@playwright/test**`; mismatched versions can prevent the client from locating browser executables.

**Crash / Target Closed in Docker**: If Chrome crashes with "Target closed" or "Page crashed", it's often due to small shared memory `**/dev/shm**`. Add this flag:

```js
const browser = await chromium.launch({
  args: [
    `--remote-debugging-port=${PORT}`,
    '--disable-dev-shm-usage', // Critical for Docker
  ],
})
```

## Visual Debugging

Use Playwright's [**~~Inspector~~**](https://playwright.dev/docs/debug#playwright-inspector) to pause execution right before the Lighthouse audit to verify the page state.

```bash
# Run with Inspector
PWDEBUG=1 npx playwright test
```

When paused:

1. Check that the page has logged you in (if expected).
2. Verify the browser has fully loaded the DOM.
3. Check for any overlay/modals that might block Lighthouse.

## Still Stuck?

- Check [**~~Lighthouse GitHub Issues~~**](https://github.com/GoogleChrome/lighthouse/issues)
- Check [**~~Playwright GitHub Issues~~**](https://github.com/microsoft/playwright/issues)
- For site-wide auditing without these integration headaches, try [**~~Unlighthouse~~**](https://unlighthouse.dev/guide/getting-started/installation)

### **Related **

[**Playwright Setup Guide**](https://unlighthouse.dev/learn-lighthouse/playwright) [**Authentication**](https://unlighthouse.dev/learn-lighthouse/playwright/authentication) [**CI/CD Integration**](https://unlighthouse.dev/learn-lighthouse/playwright/ci-cd)

[**CI/CD** Automate Lighthouse audits with Playwright in GitHub Actions. Run performance tests on every PR with thresholds and artifact reports.](https://unlighthouse.dev/learn-lighthouse/playwright/ci-cd) [**SEO** Pass every Lighthouse SEO audit. Crawlability, canonical, meta description, robots.txt, hreflang, status codes — each check explained with fixes and examples.](https://unlighthouse.dev/learn-lighthouse/seo)

**On this page **

- [Port Already in Use](#port-already-in-use)
- [Authentication State Lost](#authentication-state-lost)
- [Flaky or Inconsistent Scores](#flaky-or-inconsistent-scores)
- [Chrome/Chromium Version Mismatch](#chromechromium-version-mismatch)
- [Timeout Errors](#timeout-errors)
- [Sandbox Errors](#sandbox-errors)
- [Multiple Concurrent Audits Fail](#multiple-concurrent-audits-fail)
- [Lighthouse Reports Show Wrong Page](#lighthouse-reports-show-wrong-page)
- [Empty or Incomplete Reports](#empty-or-incomplete-reports)
- [CI-Specific Issues](#ci-specific-issues)
- [Visual Debugging](#visual-debugging)
- [Still Stuck?](#still-stuck)

---

- **Page:** Bulk Lighthouse Testing for Large Sites · Unlighthouse
- **Source:** https://unlighthouse.dev/guide/recipes/large-sites
- **Description:** Scan large websites with thousands of pages efficiently. Configure sampling, URL filtering, and optimization strategies for bulk Lighthouse testing.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Recipes**

# **Bulk Lighthouse Testing for Large Sites**

[Copy for LLMs](https://unlighthouse.dev/guide/recipes/large-sites.md)

Scan websites with thousands of pages efficiently. Unlike single-page tools like PageSpeed Insights, Unlighthouse handles large sites with smart sampling, parallel scanning, and configurable limits.

- **Automatic discovery** - Finds all pages via sitemap and crawling
- **Smart sampling** - Tests representative pages from each template
- **Parallel scanning** - Multiple Chrome instances for speed
- **Aggregated results** - Site-wide scores and insights

Unlighthouse includes smart defaults for large sites. Understanding these helps balance completeness with performance.

## Default Large Site Configuration

These defaults optimize scanning for sites with thousands of pages:

- [**~~ignoreI18nPages~~**](https://unlighthouse.dev/api-doc/config#scanner-ignorei18npages) enabled
- [**~~maxRoutes~~**](https://unlighthouse.dev/api-doc/config#scanner-maxroutes) set to 200
- [**~~skipJavascript~~**](https://unlighthouse.dev/api-doc/config#scanner-skipjavascript) enabled
- [**~~samples~~**](https://unlighthouse.dev/api-doc/config#scanner-samples) set to 1
- [**~~throttling~~**](https://unlighthouse.dev/api-doc/config#scanner-throttle) disabled
- [**~~crawler~~**](https://unlighthouse.dev/api-doc/config#scanner-crawler) enabled
- [**~~dynamicSampling~~**](https://unlighthouse.dev/api-doc/config#scanner-dynamicsampling) set to 5

For example, when scanning a blog with thousands of posts, it may be redundant to scan every single blog post, as the DOM is very similar. Using the configuration we can select exactly how many posts should be scanned.

## Manually select URLs

You can configure Unlighthouse to use an explicit list of relative paths. This can be useful if you have a fairly complex and large site.

See [**~~Manually providing URLs~~**](https://unlighthouse.dev/guide/guides/url-discovery#manually-providing-urls) for more information.

## Provide Route Definitions (optional)

To make the most intelligent sampling decisions, Unlighthouse needs to know which page files are available. When running using the integration API, Unlighthouse will automatically provide this information.

Using the CLI you should follow the [**~~providing route definitions~~**](https://unlighthouse.dev/guide/guides/route-definitions) guide.

Note: When no route definitions are provided it will match based on URL fragments, i.e `**/blog/post-slug-3**` will be mapped to `**blog-slug**`.

## Exclude URL Patterns

Paths to ignore from scanning.

For example, if your site has a documentation section, that doesn't need to be scanned.

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  scanner: {
    exclude: [
      '/docs/*',
    ],
  },
})
```

## Include URL Patterns

Explicitly include paths; this will exclude any paths not listed here.

For example, if you run a blog and want to only scan your article and author pages.

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  scanner: {
    include: [
      '/articles/*',
      '/authors/*',
    ],
  },
})
```

## Change Dynamic Sampling Limit

By default, a URLs will be matched to a specific route definition 5 times.

You can change the sample limit with:

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  scanner: {
    dynamicSampling: 20, // 20 samples per page template
  },
})
```

## Disabling Sampling

In cases where the route definitions aren't provided, a less-smart sampling will occur where URLs under the same parent will be sampled.

For these instances you may want to disable the sample as follows:

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  scanner: {
    dynamicSampling: false, // Disable sampling completely
  },
})
```

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/recipes/large-sites.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/recipes/large-sites.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/recipes/large-sites.md) on GitHub or provide anonymous feedback below.

### **Related **

[**Dynamic Sampling**](https://unlighthouse.dev/guide/guides/dynamic-sampling) [**URL Discovery**](https://unlighthouse.dev/guide/guides/url-discovery) [**Route Definitions**](https://unlighthouse.dev/guide/guides/route-definitions)

[**Improving Accuracy** Optimize Lighthouse scan accuracy with multiple samples and reduced concurrency for more reliable, consistent Core Web Vitals results.](https://unlighthouse.dev/guide/recipes/improving-accuracy) [**SPAs** Configure Unlighthouse to scan single-page applications (SPAs) with client-side routing like React, Vue, and Angular apps.](https://unlighthouse.dev/guide/recipes/spa)

**On this page **

- [Default Large Site Configuration](#default-large-site-configuration)
- [Manually select URLs](#manually-select-urls)
- [Provide Route Definitions (optional)](#provide-route-definitions-optional)
- [Exclude URL Patterns](#exclude-url-patterns)
- [Include URL Patterns](#include-url-patterns)
- [Change Dynamic Sampling Limit](#change-dynamic-sampling-limit)
- [Disabling Sampling](#disabling-sampling)

---

- **Page:** Authentication for Lighthouse Scans · Unlighthouse
- **Source:** https://unlighthouse.dev/guide/guides/authentication
- **Description:** Scan password-protected websites with Unlighthouse. Configure basic auth, cookies, headers, localStorage, and programmatic login flows.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Guides**

# **Authentication for Lighthouse Scans**

[Copy for LLMs](https://unlighthouse.dev/guide/guides/authentication.md)

Need to scan pages behind a login? Unlighthouse supports every common auth pattern. Find yours below.

## Quick Reference

| **Auth Type** | **Best For** | **Config Key** |
| --- | --- | --- |
| Basic Auth | Staging environments with HTTP basic auth | `**auth**` |
| Cookies | Session tokens, JWTs in cookies | `**cookies**` |
| Headers | Bearer tokens, API keys | `**extraHeaders**` |
| localStorage | SPAs storing tokens in localStorage | `**localStorage**` |
| Programmatic | Complex login flows, 2FA | `**hooks.authenticate**` |

## Basic Auth

For sites using HTTP Basic Authentication (the browser popup):

```ts
export default defineUnlighthouseConfig({
  auth: {
    username: process.env.AUTH_USER,
    password: process.env.AUTH_PASS,
  },
})
```

Or via CLI:

```bash
unlighthouse --site staging.example.com --auth admin:secretpass
```

## Cookies

Most common for session-based auth. Grab your session cookie from browser DevTools (Application → Cookies):

```ts
export default defineUnlighthouseConfig({
  cookies: [
    {
      name: 'session_id',
      value: 'abc123...',
      domain: 'example.com', // Must match your site
      path: '/',
    },
  ],
})
```

**Getting the cookie value:**

1. Log into your site in Chrome
2. Open DevTools → Application → Cookies
3. Copy the session cookie value
4. Paste into config (or use environment variable)

CLI shorthand:

```bash
unlighthouse --site example.com --cookies "session_id=abc123"

# Multiple cookies
unlighthouse --site example.com --cookies "session_id=abc123;csrf_token=xyz789"
```

## Headers (Bearer Tokens, API Keys)

For APIs or sites expecting `**Authorization**` headers:

```ts
export default defineUnlighthouseConfig({
  extraHeaders: {
    Authorization: `Bearer ${process.env.API_TOKEN}`,
  },
})
```

CLI:

```bash
unlighthouse --site api.example.com --extra-headers "Authorization:Bearer abc123"
```

## Query Params

Some staging environments use URL tokens:

```ts
export default defineUnlighthouseConfig({
  defaultQueryParams: {
    access_token: process.env.STAGING_TOKEN,
  },
})
```

Every scanned URL will include `**?access_token=...**`

## localStorage (SPAs)

For React/Vue/Angular apps storing auth tokens in localStorage:

```ts
export default defineUnlighthouseConfig({
  localStorage: {
    auth_token: process.env.AUTH_TOKEN,
    user_id: '12345',
  },
})
```

Unlighthouse sets these before each page loads.

## Programmatic Login (Complex Flows)

For login forms, OAuth flows, or anything the simpler methods can't handle:

```ts
export default defineUnlighthouseConfig({
  hooks: {
    async authenticate({ page }) {
      // Navigate to login
      await page.goto('https://example.com/login')

      // Fill form
      await page.type('input[name="email"]', 'test@example.com')
      await page.type('input[name="password"]', process.env.PASSWORD)

      // Submit and wait for redirect
      await Promise.all([
        page.click('button[type="submit"]'),
        page.waitForNavigation(),
      ])
    },
  },
})
```

This runs once before scanning starts. The session persists for all pages.

## Auth Not Sticking?

If authentication isn't persisting between page scans:

```ts
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    userDataDir: './.unlighthouse-session', // Persist browser data
  },
  lighthouseOptions: {
    disableStorageReset: true, // Don't clear storage between pages
    skipAboutBlank: true,
  },
})
```

## Debugging Auth Issues

Can't tell if auth is working? Watch it happen:

```ts
export default defineUnlighthouseConfig({
  debug: true,
  puppeteerOptions: {
    headless: false, // See the browser
    slowMo: 100, // Slow it down
  },
  puppeteerClusterOptions: {
    maxConcurrency: 1, // One at a time
  },
})
```

Now you can watch the browser and see exactly where auth fails.

See the [**~~Debugging Guide~~**](https://unlighthouse.dev/guide/guides/debugging) for more techniques.

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/authentication.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/guides/authentication.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/authentication.md) on GitHub or provide anonymous feedback below.

### **Related **

[**Debugging**](https://unlighthouse.dev/guide/guides/debugging) [**Puppeteer Configuration**](https://unlighthouse.dev/guide/guides/puppeteer) [**Configuration**](https://unlighthouse.dev/guide/guides/config)

[**Debugging** Debug and troubleshoot Unlighthouse scans using logging, browser inspection, and diagnostic tools.](https://unlighthouse.dev/guide/guides/debugging) [**Chrome Dependency** Configure Chrome browser settings for Unlighthouse scanning, including system Chrome usage and custom installations.](https://unlighthouse.dev/guide/guides/chrome-dependency)

**On this page **

- [Quick Reference](#quick-reference)
- [Basic Auth](#basic-auth)
- [Cookies](#cookies)
- [Headers (Bearer Tokens, API Keys)](#headers-bearer-tokens-api-keys)
- [Query Params](#query-params)
- [localStorage (SPAs)](#localstorage-spas)
- [Programmatic Login (Complex Flows)](#programmatic-login-complex-flows)
- [Auth Not Sticking?](#auth-not-sticking)
- [Debugging Auth Issues](#debugging-auth-issues)

---

- **Page:** Chrome Dependency · Unlighthouse
- **Source:** https://unlighthouse.dev/guide/guides/chrome-dependency
- **Description:** Configure Chrome browser settings for Unlighthouse scanning, including system Chrome usage and custom installations.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Guides**

# **Chrome Dependency**

[Copy for LLMs](https://unlighthouse.dev/guide/guides/chrome-dependency.md)

Unlighthouse uses your system Chrome installation to keep package size minimal. When Chrome isn't available, it automatically downloads a compatible Chromium binary.

## Disabling system Chrome

You can disable the system chrome usage by modifying the `**chrome.useSystem**` flag.

This will make Unlighthouse download and use the latest Chrome binary instead.

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  chrome: {
    useSystem: false
  },
})
```

## Customizing the fallback installer

When Chrome can't be found on your system or if the `**chrome.useSystem: false**` flag is passed, then a fallback will be attempted.

This fallback will download a chrome binary for your system and use that path.

There are a number of options you can customize on this.

- `**chrome.useDownloadFallback**` - Disables the fallback installer
- `**chrome.downloadFallbackVersion**` - Which version of chromium to use (default `**1095492**`)
- `**chrome.downloadFallbackCacheDir**` - Where the binary should be saved (default `**$home/.unlighthouse**`)

```ts
export default defineUnlighthouseConfig({
  chrome: {
    useDownloadFallback: true,
    downloadFallbackVersion: '1095492',
    downloadFallbackCacheDir: '/tmp/unlighthouse',
  },
})
```

## Using your own chrome path

You can provide your own chrome path by setting `**puppeteerOptions.executablePath**`.

```ts
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    executablePath: '/usr/bin/chrome',
  },
})
```

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/chrome-dependency.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/guides/chrome-dependency.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/chrome-dependency.md) on GitHub or provide anonymous feedback below.

### **Related **

[**Puppeteer Configuration**](https://unlighthouse.dev/guide/guides/puppeteer) [**Common Errors**](https://unlighthouse.dev/guide/guides/common-errors) [**Docker**](https://unlighthouse.dev/guide/guides/docker)

[**Authentication** Scan password-protected websites with Unlighthouse. Configure basic auth, cookies, headers, localStorage, and programmatic login flows.](https://unlighthouse.dev/guide/guides/authentication) [**Common Errors** Troubleshoot common issues encountered when running Unlighthouse scans, including browser connection and environment problems.](https://unlighthouse.dev/guide/guides/common-errors)

**On this page **

- [Disabling system Chrome](#disabling-system-chrome)
- [Customizing the fallback installer](#customizing-the-fallback-installer)
- [Using your own chrome path](#using-your-own-chrome-path)

---

- **Page:** Debugging Lighthouse Scans · Unlighthouse
- **Source:** https://unlighthouse.dev/guide/guides/debugging
- **Description:** Debug and troubleshoot Unlighthouse scans using logging, browser inspection, and diagnostic tools.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Guides**

# **Debugging Lighthouse Scans**

[Copy for LLMs](https://unlighthouse.dev/guide/guides/debugging.md)

Scan not working? Here's how to figure out why.

## Start Here: Debug Logs

90% of issues become obvious with debug logging:

```bash
unlighthouse --site example.com --debug
```

This shows you:

- What URLs are being discovered
- Which pages are being scanned
- Any errors or timeouts
- Chrome connection status

## Watch the Browser

Can't tell what's happening? Watch it:

```ts
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    headless: false, // Show the browser window
    slowMo: 250, // Slow down so you can see what's happening
    devtools: true, // Open Chrome DevTools
  },
  puppeteerClusterOptions: {
    maxConcurrency: 1, // One page at a time
  },
})
```

Now you'll see exactly what Unlighthouse sees—useful for:

- Auth issues (is login working?)
- JavaScript errors (check the console)
- Missing content (is the page rendering?)
- Blocked requests (check Network tab)

Visual mode is slow. Only use it to diagnose specific problems.

## Common Issues

### Pages Timing Out

Your site might be slow or have heavy JavaScript:

```ts
export default defineUnlighthouseConfig({
  lighthouseOptions: {
    maxWaitForLoad: 60000, // Wait up to 60s (default: 45s)
  },
})
```

### SPA Not Rendering

JavaScript apps need time to hydrate:

```ts
export default defineUnlighthouseConfig({
  scanner: {
    skipJavascript: false, // Wait for JS to execute
  },
  lighthouseOptions: {
    maxWaitForLoad: 45000,
  },
})
```

### SSL/Certificate Errors

On localhost or staging with self-signed certs:

```ts
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    ignoreHTTPSErrors: true,
    args: ['--ignore-certificate-errors'],
  },
})
```

### Chrome Won't Start

Try using bundled Chromium instead of system Chrome:

```ts
export default defineUnlighthouseConfig({
  chrome: {
    useSystem: false, // Download and use bundled Chromium
  },
})
```

Or point to a specific Chrome:

```ts
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    executablePath: '/usr/bin/google-chrome-stable',
  },
})
```

### Failed Network Requests

Log all failed requests to find what's breaking:

```ts
export default defineUnlighthouseConfig({
  hooks: {
    'puppeteer:before-goto': async (page) => {
      page.on('requestfailed', (req) => {
        console.log('❌ Failed:', req.url(), req.failure()?.errorText)
      })
    },
  },
})
```

## Still Stuck?

1. Check [**~~Common Errors~~**](https://unlighthouse.dev/guide/guides/common-errors) for known issues
2. Search [**~~GitHub Issues~~**](https://github.com/harlan-zw/unlighthouse/issues)
3. Ask on [**~~Discord~~**](https://discord.gg/275MBUBvgP) with your debug logs

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/1.debugging.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/guides/debugging.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/1.debugging.md) on GitHub or provide anonymous feedback below.

### **Related **

[**Common Errors**](https://unlighthouse.dev/guide/guides/common-errors) [**Configuration**](https://unlighthouse.dev/guide/guides/config) [**Puppeteer Configuration**](https://unlighthouse.dev/guide/guides/puppeteer)

[**Configuration** Configure Unlighthouse for your specific needs using configuration files and inline options.](https://unlighthouse.dev/guide/guides/config) [**Authentication** Scan password-protected websites with Unlighthouse. Configure basic auth, cookies, headers, localStorage, and programmatic login flows.](https://unlighthouse.dev/guide/guides/authentication)

**On this page **

- [Start Here: Debug Logs](#start-here-debug-logs)
- [Watch the Browser](#watch-the-browser)
- [Common Issues](#common-issues)
- [Still Stuck?](#still-stuck)

---

- **Page:** Unlighthouse --desktop Flag &amp; Device Configuration · Unlighthouse
- **Source:** https://unlighthouse.dev/guide/guides/device
- **Description:** Run Unlighthouse in desktop mode with the --desktop flag: npx unlighthouse --site <url> --desktop. Configure mobile, desktop, or custom viewports with throttling.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Guides**

# **Unlighthouse --desktop Flag & Device Configuration**

[Copy for LLMs](https://unlighthouse.dev/guide/guides/device.md)

Run Unlighthouse in desktop mode with the `**--desktop**` flag:

```bash
npx unlighthouse --site https://example.com --desktop
```

This overrides the default mobile emulation and scans every page using a desktop viewport. Prefer a config file? Set `**scanner.device: 'desktop'**` instead.

## When to use `**--desktop**`

Mobile is the default because Google uses mobile-first indexing. But desktop scans still matter for:

- B2B SaaS dashboards (95%+ desktop traffic)
- Admin panels and internal tools
- Documentation sites
- Benchmarking against PageSpeed Insights desktop scores

The `**--desktop**` flag is equivalent to the `**--device desktop**` long form and takes precedence over any config file setting.

## Device Types

### Desktop Scanning

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  scanner: {
    device: 'desktop',
  },
})
```

### Mobile Scanning (Default)

```ts
export default defineUnlighthouseConfig({
  scanner: {
    device: 'mobile',
  },
})
```

## Custom Dimensions

Test specific viewport sizes for responsive breakpoints:

```ts
export default defineUnlighthouseConfig({
  lighthouseOptions: {
    screenEmulation: {
      width: 1800,
      height: 1000,
    },
  },
})
```

## Network Throttling

Throttling simulates slower network and CPU conditions for more realistic performance testing:

```ts
export default defineUnlighthouseConfig({
  scanner: {
    throttle: true,
  },
})
```

Throttling is automatically enabled for production sites and disabled for localhost by default.

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/device.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/guides/device.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/device.md) on GitHub or provide anonymous feedback below.

### **Related **

[**Lighthouse Configuration**](https://unlighthouse.dev/guide/guides/lighthouse) [**Config Reference**](https://unlighthouse.dev/api-doc/config) [**Core Web Vitals Glossary**](https://unlighthouse.dev/glossary)

[**Common Errors** Troubleshoot common issues encountered when running Unlighthouse scans, including browser connection and environment problems.](https://unlighthouse.dev/guide/guides/common-errors) [**Docker** Run Unlighthouse site-wide Lighthouse scans in Docker containers. Dockerfile examples and CI/CD configuration.](https://unlighthouse.dev/guide/guides/docker)

**On this page **

- [When to use --desktop](#when-to-use-desktop)
- [Device Types](#device-types)
- [Custom Dimensions](#custom-dimensions)
- [Network Throttling](#network-throttling)

---

- **Page:** Dynamic Sampling · Unlighthouse
- **Source:** https://unlighthouse.dev/guide/guides/dynamic-sampling
- **Description:** Automatically sample similar pages to reduce scan time for sites with many similar URLs like blogs or e-commerce.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Guides**

# **Dynamic Sampling**

[Copy for LLMs](https://unlighthouse.dev/guide/guides/dynamic-sampling.md)

Automatically group similar pages and scan only representative samples. This significantly reduces scan time for sites with many similar URLs like blogs, e-commerce product pages, or documentation sites.

## How it works

When dynamic sampling is enabled, it will group paths into chunks based on their path tree.

For example, let's imagine we have a blog on our site and there are hundreds of blog posts. Scanning every blog post will take a long time and may even break Unlighthouse.

The path structure is `**/blog/{post}**`.

Unlighthouse will turn this path structure into groups based on the `**/blog**` prefix. By default, it will sample 5 paths starting with this prefix.

A sample being a random selection of paths within this group.

For example if we have the posts:

- `**/blog/post-a**`
- `**/blog/post-b**`
- `**/blog/post-c**`
- `**/blog/post-d**`
- `**/blog/post-e**`
- `**/blog/post-f**`
- `**/blog/post-g**`
- `**/blog/post-h**`
- `**/blog/post-i**`

After sampling, we may end up with the random selection:

- `**/blog/post-c**`
- `**/blog/post-d**`
- `**/blog/post-e**`
- `**/blog/post-h**`
- `**/blog/post-i**`

## Usage

It is configured using the `**scanner.dynamicSampling**` option.

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  scanner: {
    dynamicSampling: 10, // Number of samples per group (default: 5)
  },
})
```

### Disable Dynamic Sampling

```ts
export default defineUnlighthouseConfig({
  scanner: {
    dynamicSampling: false,
  },
})
```

Alternatively, you can disable it using the CLI `**--disable-dynamic-sampling**`.

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/dynamic-sampling.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/guides/dynamic-sampling.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/dynamic-sampling.md) on GitHub or provide anonymous feedback below.

### **Related **

[**Route Definitions**](https://unlighthouse.dev/guide/guides/route-definitions) [**Large Sites**](https://unlighthouse.dev/guide/recipes/large-sites) [**URL Discovery**](https://unlighthouse.dev/guide/guides/url-discovery)

[**Docker** Run Unlighthouse site-wide Lighthouse scans in Docker containers. Dockerfile examples and CI/CD configuration.](https://unlighthouse.dev/guide/guides/docker) [**Static Reports** Generate static Lighthouse reports for your entire site. Export as HTML, CSV, or JSON. Deploy to Netlify, CloudFlare, or any static host.](https://unlighthouse.dev/guide/guides/generating-static-reports)

**On this page **

- [How it works](#how-it-works)
- [Usage](#usage)

---

- **Page:** Run Lighthouse in Docker · Unlighthouse
- **Source:** https://unlighthouse.dev/guide/guides/docker
- **Description:** Run Unlighthouse site-wide Lighthouse scans in Docker containers. Dockerfile examples and CI/CD configuration.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Guides**

# **Run Lighthouse in Docker**

[Copy for LLMs](https://unlighthouse.dev/guide/guides/docker.md)

Run Unlighthouse in Docker containers for consistent CI/CD environments. Docker requires special Puppeteer configuration due to sandboxing restrictions.

Docker support is community-maintained and experimental. Use the CI integration for best results.

## Unlighthouse Config

It's recommended you only use the `**@unlighthouse/ci**` with Docker. Hosting the client does not have known support.

You will need to remove the Chrome sandbox in a Docker environment, this will require using an `**unlighthouse.config.ts**` file.

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  puppeteerOptions: {
    headless: true,
    args: [
      '--no-sandbox',
      '--disable-setuid-sandbox',
      '--disable-gpu',
      '--ignore-certificate-errors',
    ],
  },
})
```

If you're using the `**unlighthouse**` binary instead of the CI integration, then you will need to tell Unlighthouse not to use the server and close when the reports are finished.

```ts
export default defineUnlighthouseConfig({
  server: {
    open: false,
  },
  hooks: {
    'worker-finished': async () => {
      process.exit(0)
    },
  },
})
```

## Docker File

Please see the following community repos:

- [**~~indykoning—Unlighthouse Docker~~**](https://github.com/indykoning/unlighthouse-docker)

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/docker.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/guides/docker.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/docker.md) on GitHub or provide anonymous feedback below.

### **Related **

[**CI Integration**](https://unlighthouse.dev/integrations/ci) [**Puppeteer Configuration**](https://unlighthouse.dev/guide/guides/puppeteer) [**Chrome Dependency**](https://unlighthouse.dev/guide/guides/chrome-dependency)

[**Device Configuration** Run Unlighthouse in desktop mode with the --desktop flag: npx unlighthouse --site \<url> --desktop. Configure mobile, desktop, or custom viewports with throttling.](https://unlighthouse.dev/guide/guides/device) [**Dynamic Sampling** Automatically sample similar pages to reduce scan time for sites with many similar URLs like blogs or e-commerce.](https://unlighthouse.dev/guide/guides/dynamic-sampling)

**On this page **

- [Unlighthouse Config](#unlighthouse-config)
- [Docker File](#docker-file)

---

- **Page:** Integrations · Unlighthouse
- **Source:** https://unlighthouse.dev/guide/getting-started/integrations
- **Description:** Integrate Unlighthouse into your existing build tools, frameworks, and CI/CD pipelines for automated Lighthouse testing.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Getting Started**

# **Integrations**

[Copy for LLMs](https://unlighthouse.dev/guide/getting-started/integrations.md)

Choose how to integrate Unlighthouse into your workflow: manual CLI scans for development, automated CI/CD checks for deployment pipelines, or build tool integration for framework-specific setups.

## Command Line

| **Provider** | **Use Case** |
| --- | --- |
| [**~~CLI~~**](https://unlighthouse.dev/integrations/cli) | Scan a production site such as [**~~unlighthouse.dev~~**](https://unlighthouse.dev/).<br><br> You can manually provide a project mapping for [**~~routes definitions~~**](https://unlighthouse.dev/guide/guides/route-definitions). |
| [**~~CI~~**](https://unlighthouse.dev/integrations/ci) | Run scans on sites based on automation events, i.e releasing and make [**~~assertions on scores~~**](https://unlighthouse.dev/integrations/ci#assertions).<br><br> Can also be used to generate report sites such as [**~~inspect.unlighthouse.dev~~**](https://inspect.unlighthouse.dev/). |

## Build tools / Frameworks

**Deprecation Notice**: Build tool integrations are deprecated and will be removed in v1.0. We recommend using the CLI or CI integrations instead. [**~~Learn more about deprecations~~**](https://unlighthouse.dev/integration-deprecations)

| **Provider** | **Features** |
| --- | --- |
| [**~~Nuxt.js~~**](https://unlighthouse.dev/integrations/nuxt) | Hot Module Reloading, Automatic Route Discovery |
| [**~~Vite~~**](https://unlighthouse.dev/integrations/vite) | Hot Module Reloading, Automatic Route Discovery |
| [**~~webpack~~**](https://unlighthouse.dev/integrations/webpack) | Hot Module Reloading |

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/1.getting-started/1.integrations.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/getting-started/integrations.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/1.getting-started/1.integrations.md) on GitHub or provide anonymous feedback below.

### **Related **

[**CLI Integration**](https://unlighthouse.dev/integrations/cli) [**CI Integration**](https://unlighthouse.dev/integrations/ci) [**Configuration**](https://unlighthouse.dev/guide/guides/config)

[**CLI** Install and run Unlighthouse CLI to scan your entire website with Lighthouse. npm, pnpm, and yarn installation options.](https://unlighthouse.dev/guide/getting-started/unlighthouse-cli) [**How It Works** Learn how Unlighthouse automatically discovers pages, runs Lighthouse audits in parallel, and generates site-wide performance reports.](https://unlighthouse.dev/guide/getting-started/how-it-works)

**On this page **

- [Command Line](#command-line)
- [Build tools / Frameworks](#build-tools-frameworks)

---

- **Page:** Lighthouse Configuration · Unlighthouse
- **Source:** https://unlighthouse.dev/guide/guides/lighthouse
- **Description:** Customize Google Lighthouse audit settings, categories, and performance thresholds within Unlighthouse scans.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Guides**

# **Lighthouse Configuration**

[Copy for LLMs](https://unlighthouse.dev/guide/guides/lighthouse.md)

Customize audit categories, performance thresholds, and behavior through the `**lighthouseOptions**` configuration key. Unlighthouse passes these options directly to Google Lighthouse.

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  lighthouseOptions: {
    throttlingMethod: 'devtools',
  },
})
```

For complete options, see the [**~~Lighthouse Configuration docs~~**](https://github.com/GoogleChrome/lighthouse/blob/master/docs/configuration.md).

## Aliases

Unlighthouse aims to minimise and simplify configuration, where possible.

For this reason, a number of configurations aliases are provided for your convenience.

- [**~~Switching device: mobile and desktop~~**](https://unlighthouse.dev/guide/guides/device)
- [**~~Toggle Throttling~~**](https://unlighthouse.dev/guide/guides/device#network-throttling)

You can always configure lighthouse directly if you are comfortable with the configuration.

## Selecting Categories

By default, Unlighthouse will scan the categories: `**'performance', 'accessibility', 'best-practices', 'seo'**`.

The performance category measures [**~~Core Web Vitals~~**](https://unlighthouse.dev/glossary) including [**~~LCP~~**](https://unlighthouse.dev/glossary/lcp), [**~~CLS~~**](https://unlighthouse.dev/glossary/cls), and [**~~INP~~**](https://unlighthouse.dev/glossary/inp).

It can be useful to remove certain categories from being scanned to improve scan times. The Unlighthouse UI will adapt to any categories you select.

**Only Performance**

```ts
export default defineUnlighthouseConfig({
  lighthouseOptions: {
    onlyCategories: ['performance'],
  },
})
```

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/lighthouse.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/guides/lighthouse.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/lighthouse.md) on GitHub or provide anonymous feedback below.

### **Related **

[**Device Configuration**](https://unlighthouse.dev/guide/guides/device) [**Config Reference**](https://unlighthouse.dev/api-doc/config) [**Core Web Vitals Glossary**](https://unlighthouse.dev/glossary)

[**Static Reports** Generate static Lighthouse reports for your entire site. Export as HTML, CSV, or JSON. Deploy to Netlify, CloudFlare, or any static host.](https://unlighthouse.dev/guide/guides/generating-static-reports) [**Puppeteer** Configure Puppeteer launch options in Unlighthouse: headless mode, Chrome args, viewport settings, executable path, and navigation hooks.](https://unlighthouse.dev/guide/guides/puppeteer)

**On this page **

- [Aliases](#aliases)
- [Selecting Categories](#selecting-categories)

---

- **Page:** Route Definitions · Unlighthouse
- **Source:** https://unlighthouse.dev/guide/guides/route-definitions
- **Description:** Configure route discovery and custom sampling patterns for better page organization and intelligent scanning.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Guides**

# **Route Definitions**

[Copy for LLMs](https://unlighthouse.dev/guide/guides/route-definitions.md)

Map URLs to source files for intelligent [**~~dynamic sampling~~**](https://unlighthouse.dev/guide/guides/dynamic-sampling). Framework integrations discover routes automatically; CLI users may need manual configuration for optimal sampling.

## Pages directory

By default, the `**pages/**` dir is scanned for files with extensions `**.vue**` and `**.md**`, from the `**root**` directory.

If your project has a different setup you can modify the configuration.

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  root: './app',
  discovery: {
    pagesDir: 'routes',
    fileExtensions: ['jsx', 'md'],
  },
})
```

## Custom sampling

When you have URL patterns which don't use URL segments or the mapping is failing, it can be useful to map the sampling yourself.

By using the `**customSampling**` option you map regex to a route definition.

In the below example we will map any URL such as `**/q-search-query**`, `**/q-where-is-the-thing**` to a single route definition, which allows the sampling to work.

```ts
export default defineUnlighthouseConfig({
  scanner: {
    customSampling: {
      '/q-(.*?)': {
        name: 'search-query',
      },
    },
  },
})
```

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/route-definitions.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/guides/route-definitions.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/route-definitions.md) on GitHub or provide anonymous feedback below.

### **Related **

[**Dynamic Sampling**](https://unlighthouse.dev/guide/guides/dynamic-sampling) [**URL Discovery**](https://unlighthouse.dev/guide/guides/url-discovery) [**Configuration**](https://unlighthouse.dev/guide/guides/config)

[**Puppeteer** Configure Puppeteer launch options in Unlighthouse: headless mode, Chrome args, viewport settings, executable path, and navigation hooks.](https://unlighthouse.dev/guide/guides/puppeteer) [**URL Discovery** How Unlighthouse discovers pages using sitemaps, robots.txt, and internal link crawling. Configure URL sources and filters.](https://unlighthouse.dev/guide/guides/url-discovery)

**On this page **

- [Pages directory](#pages-directory)
- [Custom sampling](#custom-sampling)

---

- **Page:** Puppeteer Launch Options · Unlighthouse
- **Source:** https://unlighthouse.dev/guide/guides/puppeteer
- **Description:** Configure Puppeteer launch options in Unlighthouse: headless mode, Chrome args, viewport settings, executable path, and navigation hooks.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Guides**

# **Puppeteer Launch Options**

[Copy for LLMs](https://unlighthouse.dev/guide/guides/puppeteer.md)

Unlighthouse uses [**~~Puppeteer~~**](https://pptr.dev/) to control Chrome for Lighthouse audits. Configure browser behavior, navigation hooks, and Chrome flags via `**puppeteerOptions**`.

## All Available Options

```ts
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    // See: https://pptr.dev/api/puppeteer.launchoptions
  },
})
```

Full reference: [**~~Puppeteer LaunchOptions API~~**](https://pptr.dev/api/puppeteer.launchoptions)

## Common Configurations

### Headless Mode

```ts
// Run with visible browser (debugging)
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    headless: false,
  },
})
```

### Custom Chrome Executable

```ts
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    executablePath: '/usr/bin/google-chrome',
  },
})
```

### Chrome Arguments

Common args for CI/Docker environments:

```ts
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    args: [
      '--no-sandbox',
      '--disable-setuid-sandbox',
      '--disable-dev-shm-usage',
      '--disable-gpu',
    ],
  },
})
```

### Viewport Settings

```ts
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    defaultViewport: {
      width: 1920,
      height: 1080,
    },
  },
})
```

### Timeout Configuration

```ts
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    timeout: 60000, // 60 seconds
  },
})
```

### User Data Directory

Persist browser data between runs:

```ts
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    userDataDir: './.puppeteer-data',
  },
})
```

## Navigation Hooks

Hook into Puppeteer's page navigation for custom logic.

### Before Page Load

```ts
export default defineUnlighthouseConfig({
  hooks: {
    'puppeteer:before-goto': async (page) => {
      // Set localStorage before navigation
      await page.evaluateOnNewDocument((token) => {
        localStorage.setItem('auth', token)
      }, process.env.AUTH_TOKEN)
    },
  },
})
```

### Modify Page Content

```ts
export default defineUnlighthouseConfig({
  hooks: {
    'puppeteer:before-goto': async (page) => {
      page.waitForNavigation().then(async () => {
        // Remove elements that cause CLS
        await page.evaluate(() => {
          document.querySelector('.cookie-banner')?.remove()
        })
      })
    },
  },
})
```

## Troubleshooting

### Chrome not found

See [**~~Chrome Dependency Guide~~**](https://unlighthouse.dev/guide/guides/chrome-dependency).

### Connection refused in Docker

Add `**--no-sandbox**` and `**--disable-dev-shm-usage**` args.

### Memory issues

Reduce concurrent workers or add `**--disable-dev-shm-usage**`.

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/puppeteer.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/guides/puppeteer.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/puppeteer.md) on GitHub or provide anonymous feedback below.

### **Related **

[**Chrome Dependency**](https://unlighthouse.dev/guide/guides/chrome-dependency) [**Authentication**](https://unlighthouse.dev/guide/guides/authentication) [**Docker**](https://unlighthouse.dev/guide/guides/docker)

[**Lighthouse Config** Customize Google Lighthouse audit settings, categories, and performance thresholds within Unlighthouse scans.](https://unlighthouse.dev/guide/guides/lighthouse) [**Route Definitions** Configure route discovery and custom sampling patterns for better page organization and intelligent scanning.](https://unlighthouse.dev/guide/guides/route-definitions)

**On this page **

- [All Available Options](#all-available-options)
- [Common Configurations](#common-configurations)
- [Navigation Hooks](#navigation-hooks)
- [Troubleshooting](#troubleshooting)

---

- **Page:** Generate Lighthouse Reports · Unlighthouse
- **Source:** https://unlighthouse.dev/guide/guides/generating-static-reports
- **Description:** Generate static Lighthouse reports for your entire site. Export as HTML, CSV, or JSON. Deploy to Netlify, CloudFlare, or any static host.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Guides**

# **Generate Lighthouse Reports**

[Copy for LLMs](https://unlighthouse.dev/guide/guides/generating-static-reports.md)

Create static, shareable Lighthouse reports for your entire site. Export as interactive HTML dashboards, CSV for spreadsheet analysis, or JSON for CI/CD integration.

## Report Types

| **Format** | **Use Case** | **Command** |
| --- | --- | --- |
| HTML | Shareable dashboards | `**--build-static**` |
| JSON | CI/CD integration | `**--reporter json**` |
| CSV | Spreadsheet analysis | `**--reporter csv**` |
| LHCI | Server upload | `**--reporter lighthouseServer**` |

Unlike single-page Lighthouse reports, Unlighthouse aggregates results across your entire site.

Static reports are perfect for stakeholder reviews, automated deployments, and long-term performance tracking.

## Installation

Install the CLI globally to use `**unlighthouse-ci**`:

```bash
npm install -g @unlighthouse/cli
```

For complete CI features, see the [**~~CI Integration Guide~~**](https://unlighthouse.dev/integrations/ci).

## HTML Reports

You can create static, self-hosted reports for your sites using the CI. This allows you to generate an always up-to-date version of how your site is performing overall.

You can see an example of this here: [**~~https://inspect.unlighthouse.dev/~~**](https://inspect.unlighthouse.dev/).

You can generate a report like this by providing the `**--build-static**` flag.

```bash
unlighthouse-ci --site <your-site> --build-static
```

This will generate files in your `**outputPath**` (`**.unlighthouse**` by default). You can upload the `**client**` directory to a static host from there.

If you want to preview the static report you can run `**npx sirv-cli .unlighthouse/client**`

Note: You will need to host your site using a web server.

### CloudFlare Pages Example

You should create a CloudFlare Pages site using [**~~Direct Upload~~**](https://developers.cloudflare.com/pages/platform/direct-upload/).

You will use the [**~~wrangler~~**](https://developers.cloudflare.com/pages/platform/using-wrangler) CLI to upload the static report.

You will need to init wrangler and configure it for your requirements.

```bash
wrangler init
```

You can then run the following command to generate the static report and upload it to CloudFlare Pages.

```bash
unlighthouse-ci --site www.example.com --build-static && wrangler pages publish .unlighthouse
```

### GitHub Actions & Netlify Example

This example is for GitHub Actions and deploys a static client build to Netlify.

```yml
name: Assertions and static report

on:
  workflow_dispatch:

jobs:
  demo:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Dependencies
        run: npm add -g @unlighthouse/cli puppeteer

      - name: Unlighthouse assertions and client
        run: unlighthouse-ci --site <your-site> --build-static

      - name: Deploy report to Netlify
        uses: nwtgck/actions-netlify@v3.0
        with:
          publish-dir: ./.unlighthouse
          production-branch: main
          production-deploy: true
          github-token: ${{ secrets.GITHUB_TOKEN }}
          deploy-message: New Release Deploy from GitHub Actions
          enable-pull-request-comment: false
          enable-commit-comment: true
          overwrites-pull-request-comment: true
        env:
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_DEMO_SITE_ID }}
        timeout-minutes: 1
```

## CSV Reports

You can generate a CSV report by providing the `**--reporter csv**` or `**--reporter csvExpanded**` flag.

```bash
unlighthouse-ci --site <your-site> --reporter csv
```

Note: This report format is experimental and may change in the future.

This will generate a report like the following (`**csvExpanded**` sample):

```csv
URL,Score,Performance,Accessibility,Best Practices,SEO,Largest Contentful Paint,Cumulative Layout Shift,FID,Blocking,Color Contrast,Headings,Image Alts,Link Names,Errors,Inspector Issues,Images Responsive,Image Aspect Ratio,Indexable,Tap Targets
"/",93,72,100,100,100,3211.44,0,290.36,562.29,1,1,1,1,1,1,1,1,1,1
"/blog",94,77,100,100,100,3911.7,0,205.57,260.03,1,1,1,1,1,1,1,1,1,1
"/blog/2023-april",88,51,100,100,100,4925.84,0,311.24,797.95,1,1,1,1,1,1,1,1,1,1
"/blog/2023-february",96,82,100,100,100,3207.98,0,209.96,302.01,1,1,1,1,1,1,1,1,1,1
"/blog/nuxt-3-migration-cheatsheet",85,43,97,100,100,4373.88,0,1581.52,2820.75,0,1,1,1,1,1,1,1,1,1
"/blog/vue-automatic-component-imports",93,74,97,100,100,1696.51,0,793.36,1314.27,0,1,1,1,1,1,1,1,1,1
"/blog/vue-use-head-v1",82,30,97,100,100,8053.8,0,379.59,1127.99,0,1,1,1,1,1,1,1,1,1
"/projects",92,66,100,100,100,3666.86,0,322.48,625.51,1,1,1,1,1,1,1,1,1,1
"/sponsors",92,69,100,100,100,4438.15,0,362.62,408.63,1,1,1,1,1,1,1,1,1,1
"/talks",98,90,100,100,100,864.86,0,390.93,427.94,1,1,1,1,1,1,1,1,1,1
```

## JSON Reports

You can generate a JSON report by providing the `**--reporter json**` or `**--reporter jsonExpanded**` flag.

```bash
unlighthouse-ci --site <your-site> --reporter json
```

Note: This report format is experimental and may change in the future.

This will generate a report like the following (`**json**` sample):

```json
[
  {
    "path": "/",
    "score": 0.97,
    "performance": 0.87,
    "accessibility": 1,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/blog",
    "score": 0.98,
    "performance": 0.91,
    "accessibility": 1,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/blog/2023-february",
    "score": 0.91,
    "performance": 0.65,
    "accessibility": 1,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/blog/modern-package-development",
    "score": 0.9,
    "performance": 0.61,
    "accessibility": 0.97,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/blog/scale-your-vue-components",
    "score": 0.87,
    "performance": 0.51,
    "accessibility": 0.97,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/blog/vue-automatic-component-imports",
    "score": 0.88,
    "performance": 0.53,
    "accessibility": 0.97,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/blog/vue-use-head-v1",
    "score": 0.97,
    "performance": 0.9,
    "accessibility": 0.97,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/projects",
    "score": 0.94,
    "performance": 0.77,
    "accessibility": 1,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/sponsors",
    "score": 0.97,
    "performance": 0.88,
    "accessibility": 1,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/talks",
    "score": 0.94,
    "performance": 0.74,
    "accessibility": 1,
    "best-practices": 1,
    "seo": 1
  }
]
```

## LHCI Reports

You can upload your reports to a Lighthouse CI server using the `**lighthouseServer**` reporter.

You will need to provide the `**--lhci-host**` and `**--lhci-build-token**` flags.

```bash
unlighthouse-ci --site <your-site> --reporter lighthouseServer --lhci-host <lhci host> --lhci-build-token <lhci buildToken>
```

This will upload your reports to the Lighthouse CI server.

### Basic Auth

You can provide basic auth credentials using the `**--lhci-auth**` flag.

```bash
unlighthouse-ci --site <your-site> --reporter lighthouseServer --lhci-host <lhci host> --lhci-build-token <lhci buildToken> --lhci-auth <username>:<password>
```

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/generating-static-reports.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/guides/generating-static-reports.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/generating-static-reports.md) on GitHub or provide anonymous feedback below.

### **Related **

[**CI Integration**](https://unlighthouse.dev/integrations/ci) [**Configuration**](https://unlighthouse.dev/guide/guides/config) [**UI Customization**](https://unlighthouse.dev/guide/recipes/client)

[**Dynamic Sampling** Automatically sample similar pages to reduce scan time for sites with many similar URLs like blogs or e-commerce.](https://unlighthouse.dev/guide/guides/dynamic-sampling) [**Lighthouse Config** Customize Google Lighthouse audit settings, categories, and performance thresholds within Unlighthouse scans.](https://unlighthouse.dev/guide/guides/lighthouse)

**On this page **

- [Report Types](#report-types)
- [Installation](#installation)
- [HTML Reports](#html-reports)
- [CSV Reports](#csv-reports)
- [JSON Reports](#json-reports)
- [LHCI Reports](#lhci-reports)

---

- **Page:** Customizing the UI · Unlighthouse
- **Source:** https://unlighthouse.dev/guide/recipes/client
- **Description:** Modify Unlighthouse client interface columns and display to show custom metrics and data.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Recipes**

# **Customizing the UI**

[Copy for LLMs](https://unlighthouse.dev/guide/recipes/client.md)

Customize the Unlighthouse dashboard to display metrics relevant to your workflow. Replace default columns, add custom audit displays, and configure how results appear.

## Customizing Columns

Replace or add columns to display specific Lighthouse metrics:

### Example: Replace FCP with Server Response Time

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  hooks: {
    'resolved-config': function (config) {
      config.client.columns.performance[2] = {
        cols: 1,
        label: 'Response Time',
        tooltip: 'Time for the server to respond',
        sortKey: 'numericValue',
        key: 'report.audits.server-response-time',
      }
    },
  },
})
```

See the [**~~Column API Reference~~**](https://unlighthouse.dev/api-doc/glossary#columns) for all available column options.

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/recipes/client.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/recipes/client.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/recipes/client.md) on GitHub or provide anonymous feedback below.

### **Related **

[**Glossary**](https://unlighthouse.dev/api-doc/glossary) [**Configuration**](https://unlighthouse.dev/guide/guides/config) [**Static Reports**](https://unlighthouse.dev/guide/guides/generating-static-reports)

[**URL Discovery** How Unlighthouse discovers pages using sitemaps, robots.txt, and internal link crawling. Configure URL sources and filters.](https://unlighthouse.dev/guide/guides/url-discovery) [**Improving Accuracy** Optimize Lighthouse scan accuracy with multiple samples and reduced concurrency for more reliable, consistent Core Web Vitals results.](https://unlighthouse.dev/guide/recipes/improving-accuracy)

---

- **Page:** Common Errors · Unlighthouse
- **Source:** https://unlighthouse.dev/guide/guides/common-errors
- **Description:** Troubleshoot common issues encountered when running Unlighthouse scans, including browser connection and environment problems.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Guides**

# **Common Errors**

[Copy for LLMs](https://unlighthouse.dev/guide/guides/common-errors.md)

Solutions for frequently encountered issues when running Unlighthouse scans. Ensure you're using the latest version before troubleshooting.

For general debugging techniques, see the [**~~Debugging Guide~~**](https://unlighthouse.dev/guide/guides/debugging).

## `**connect ECONNREFUSED 127.0.0.1:<port>**`

**Example**

> *Error: Unable to launch browser for worker, error message: connect ECONNREFUSED 127.0.0.1:51667*

This error is thrown when Chromium is unable to launch. This happens when puppeteer is unable to connect to the browser. This can be from a number of reasons:

- The environment is not configured correctly, likely when using Windows and WSL.
- You have a firewall or antivirus blocking Chrome or Chromium from launching or connecting to the required port.
- You are using an unsupported version of Chrome or Chromium.

**Windows and WSL Solution**

- Install Puppeteer on WSL following the [**~~documentation~~**](https://pptr.dev/troubleshooting#running-puppeteer-on-wsl-windows-subsystem-for-linux).
- Install Chrome in WSL following the [**~~documentation~~**](https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps#install-google-chrome-for-linux).

**Other Environments**

- You can try disabling the system Chrome, instead using the fallback.

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  chrome: {
    useSystem: false,
  },
})
```

## Can't stop the scan with `**Ctrl+C**`

Unlighthouse keeps running after a scan so you can browse the dashboard. Press `**Ctrl+C**` in the terminal to stop it; this shuts down the dev server and closes Chrome.

If `**Ctrl+C**` does nothing, you are almost certainly running inside **Git Bash (MinTTY)** on Windows. MinTTY does not forward `**Ctrl+C**` to native console programs such as Node, so the process keeps running and you have to kill it from Task Manager.

**Solutions**

- Wrap the command with [**~~winpty~~**](https://github.com/rprichard/winpty), which ships with Git for Windows:

```bash
winpty npx unlighthouse --site example.com
```

- Or run the command from **PowerShell**, **Command Prompt**, or **Windows Terminal** instead of Git Bash, where `**Ctrl+C**` works as expected.

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/common-errors.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/guides/common-errors.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/common-errors.md) on GitHub or provide anonymous feedback below.

### **Related **

[**Debugging**](https://unlighthouse.dev/guide/guides/debugging) [**Chrome Dependency**](https://unlighthouse.dev/guide/guides/chrome-dependency) [**Puppeteer Configuration**](https://unlighthouse.dev/guide/guides/puppeteer)

[**Chrome Dependency** Configure Chrome browser settings for Unlighthouse scanning, including system Chrome usage and custom installations.](https://unlighthouse.dev/guide/guides/chrome-dependency) [**Device Configuration** Run Unlighthouse in desktop mode with the --desktop flag: npx unlighthouse --site \<url> --desktop. Configure mobile, desktop, or custom viewports with throttling.](https://unlighthouse.dev/guide/guides/device)

**On this page **

- [connect ECONNREFUSED 127.0.0.1:\<port>](#connect-econnrefused-127001port)
- [Can't stop the scan with Ctrl+C](#cant-stop-the-scan-with-ctrlc)

---

- **Page:** URL Discovery · Unlighthouse
- **Source:** https://unlighthouse.dev/guide/guides/url-discovery
- **Description:** How Unlighthouse discovers pages using sitemaps, robots.txt, and internal link crawling. Configure URL sources and filters.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Guides**

# **URL Discovery**

[Copy for LLMs](https://unlighthouse.dev/guide/guides/url-discovery.md)

Unlighthouse automatically finds all pages on your site using multiple discovery methods. Configure which sources to use and filter results to scan exactly what you need.

Unlighthouse discovers URLs through multiple methods:

1. Add the specified `**site**` from `**--site**` or config
2. Manually providing URLs via the `**--urls**` flag or `**urls**` on the provider.
3. `**robotsTxt**` - Reading robots.txt, if it exists. Provides sitemap URLs and disallowed paths.
4. `**sitemap**` - Reading sitemap.xml, if it exists
5. `**crawler**` - Inspecting internal links
6. Using provided static [**~~route definitions~~**](https://unlighthouse.dev/api-doc/glossary#route-definition)

## Robots.txt

When a robots.txt is found, it will attempt to read the sitemap and disallowed paths.

### Disabling robots

You may not want to use the robots.txt in all occasions. For example if you want to scan URLs which are disallowed.

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  scanner: {
    // disable robots.txt scanning
    robotsTxt: false,
  },
})
```

## Sitemap.xml

By default, the sitemap config will be read from your `**/robots.txt**`. Otherwise, it will fall back to using `**/sitemap.xml**`.

Note: When a sitemap exists with over 50 paths, it will disable the crawler.

### Manual sitemap paths

You may provide an array of sitemap paths to scan.

```ts
export default defineUnlighthouseConfig({
  scanner: {
    sitemap: [
      '/sitemap.xml',
      '/sitemap2.xml',
    ],
  },
})
```

### Disabling scan

If you know your site doesn't have a sitemap, it may make sense to disable it.

```ts
export default defineUnlighthouseConfig({
  scanner: {
    // disable sitemap scanning
    sitemap: false,
  },
})
```

## Crawler

When enabled, the crawler will inspect the HTML payload of a page and extract internal links. These internal links will be queued up and scanned if they haven't already been scanned.

## Disable crawling

If you have many pages with many internal links, it may be a good idea to disable the crawling.

```ts
export default defineUnlighthouseConfig({
  scanner: {
    crawler: false,
  },
})
```

## Manually Providing URLs

While not recommended for most use cases, you may provide relative URLs within your configuration file, or use the `**--urls**` flag.

This will disable the crawler and sitemap scanning.

Can be provided statically.

```ts
export default defineUnlighthouseConfig({
  urls: [
    '/about',
    '/other-page',
  ],
})
```

Or you can return a function or promise.

```ts
export default defineUnlighthouseConfig({
  urls: async () => await getUrls(),
})
```

Specify explicit relative URLs as a comma-separated list.

```bash
unlighthouse --site https://example.com --urls /about,/other-page
```

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/url-discovery.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/guides/url-discovery.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/url-discovery.md) on GitHub or provide anonymous feedback below.

### **Related **

[**Route Definitions**](https://unlighthouse.dev/guide/guides/route-definitions) [**Large Sites**](https://unlighthouse.dev/guide/recipes/large-sites) [**Configuration**](https://unlighthouse.dev/guide/guides/config)

[**Route Definitions** Configure route discovery and custom sampling patterns for better page organization and intelligent scanning.](https://unlighthouse.dev/guide/guides/route-definitions) [**UI Customization** Modify Unlighthouse client interface columns and display to show custom metrics and data.](https://unlighthouse.dev/guide/recipes/client)

**On this page **

- [Robots.txt](#robotstxt)
- [Sitemap.xml](#sitemapxml)
- [Crawler](#crawler)
- [Disable crawling](#disable-crawling)
- [Manually Providing URLs](#manually-providing-urls)

---

- **Page:** Improving Lighthouse Accuracy · Unlighthouse
- **Source:** https://unlighthouse.dev/guide/recipes/improving-accuracy
- **Description:** Optimize Lighthouse scan accuracy with multiple samples and reduced concurrency for more reliable, consistent Core Web Vitals results.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Recipes**

# **Improving Lighthouse Accuracy**

[Copy for LLMs](https://unlighthouse.dev/guide/recipes/improving-accuracy.md)

Lighthouse scores can vary 5-10 points between runs due to network conditions, CPU load, and browser state. These techniques improve consistency for reliable [**~~Core Web Vitals~~**](https://unlighthouse.dev/glossary) measurement.

## Why Scores Vary

Single Lighthouse runs can fluctuate by 5-10 points due to:

- CPU load from other browser tabs or processes
- Network latency variations
- Memory pressure
- Background service workers

For reliable performance monitoring, use multiple samples.

## Multiple Samples Per URL

Run Lighthouse multiple times and average the results for better accuracy:

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  scanner: {
    samples: 3, // Run 3 scans per URL and average results
  },
})
```

Use `**samples: 3**` for development, `**samples: 5**` for CI/production audits.

## Reduce Parallel Scans

Limit concurrent workers to reduce CPU contention and improve score consistency:

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  puppeteerClusterOptions: {
    maxConcurrency: 1, // Single worker for maximum accuracy
  },
})
```

## Enable Throttling

Network throttling simulates real-world conditions and reduces score variability:

```ts
export default defineUnlighthouseConfig({
  scanner: {
    throttle: true, // Simulate 4G network
  },
})
```

## Recommended Production Config

For the most accurate results:

```ts
export default defineUnlighthouseConfig({
  scanner: {
    samples: 5,
    throttle: true,
  },
  puppeteerClusterOptions: {
    maxConcurrency: 1,
  },
})
```

Higher accuracy increases scan time significantly. Balance accuracy needs with scan duration.

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/recipes/improving-accuracy.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/recipes/improving-accuracy.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/recipes/improving-accuracy.md) on GitHub or provide anonymous feedback below.

### **Related **

[**Configuration**](https://unlighthouse.dev/guide/guides/config) [**Device Configuration**](https://unlighthouse.dev/guide/guides/device) [**Core Web Vitals Glossary**](https://unlighthouse.dev/glossary)

[**UI Customization** Modify Unlighthouse client interface columns and display to show custom metrics and data.](https://unlighthouse.dev/guide/recipes/client) [**Large Sites** Scan large websites with thousands of pages efficiently. Configure sampling, URL filtering, and optimization strategies for bulk Lighthouse testing.](https://unlighthouse.dev/guide/recipes/large-sites)

**On this page **

- [Why Scores Vary](#why-scores-vary)
- [Multiple Samples Per URL](#multiple-samples-per-url)
- [Reduce Parallel Scans](#reduce-parallel-scans)
- [Enable Throttling](#enable-throttling)
- [Recommended Production Config](#recommended-production-config)

---

- **Page:** Single-Page Applications · Unlighthouse
- **Source:** https://unlighthouse.dev/guide/recipes/spa
- **Description:** Configure Unlighthouse to scan single-page applications (SPAs) with client-side routing like React, Vue, and Angular apps.

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Recipes**

# **Single-Page Applications**

[Copy for LLMs](https://unlighthouse.dev/guide/recipes/spa.md)

Scan React, Vue, Angular, and other SPAs with client-side routing. SPAs require JavaScript execution for link discovery and accurate [**~~Core Web Vitals~~**](https://unlighthouse.dev/glossary) measurement.

## Enable JavaScript Execution

Allow Puppeteer to execute JavaScript before extracting page content:

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  scanner: {
    skipJavascript: false, // Enable JS execution for SPAs
  },
})
```

## Wait for Hydration

SPAs often need time to hydrate. Configure wait conditions:

```ts
export default defineUnlighthouseConfig({
  scanner: {
    skipJavascript: false,
  },
  lighthouseOptions: {
    maxWaitForLoad: 45000, // Wait up to 45s for page load
  },
})
```

## Provide URLs Manually

If automatic crawling misses routes, provide them explicitly:

```ts
export default defineUnlighthouseConfig({
  urls: [
    '/',
    '/about',
    '/products',
    '/contact',
  ],
  scanner: {
    skipJavascript: false,
  },
})
```

## SPA Performance Considerations

SPAs typically have worse [**~~LCP~~**](https://unlighthouse.dev/glossary/lcp) scores because:

- Content renders after JavaScript execution
- Initial HTML is often empty or minimal
- Hydration adds to [**~~INP~~**](https://unlighthouse.dev/glossary/inp) delays

Consider SSR or SSG for content-heavy pages to improve Core Web Vitals.

Enabling JavaScript execution increases scan time but is necessary for accurate SPA scanning.

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/recipes/spa.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/recipes/spa.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/recipes/spa.md) on GitHub or provide anonymous feedback below.

### **Related **

[**URL Discovery**](https://unlighthouse.dev/guide/guides/url-discovery) [**Puppeteer Configuration**](https://unlighthouse.dev/guide/guides/puppeteer) [**LCP for SPAs**](https://unlighthouse.dev/glossary/lcp)

[**Large Sites** Scan large websites with thousands of pages efficiently. Configure sampling, URL filtering, and optimization strategies for bulk Lighthouse testing.](https://unlighthouse.dev/guide/recipes/large-sites) [**CLI** Scan your entire website with Lighthouse from the command line. Alternative to lighthouse CLI that audits all pages automatically.](https://unlighthouse.dev/integrations/cli)

**On this page **

- [Enable JavaScript Execution](#enable-javascript-execution)
- [Wait for Hydration](#wait-for-hydration)
- [Provide URLs Manually](#provide-urls-manually)
- [SPA Performance Considerations](#spa-performance-considerations)

---

- **Page:** Lighthouse on Authenticated Pages with Playwright · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/playwright/authentication
- **Description:** Run Lighthouse audits on pages behind login. Learn how to preserve authentication state when Lighthouse opens a new browser context.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Lighthouse on Authenticated Pages with Playwright**

Run Lighthouse audits on pages behind login. Learn how to preserve authentication state when Lighthouse opens a new browser context.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw) Published **Jan 27, 2026** Updated **Aug 9, 2026**

Running Lighthouse on pages that require authentication is tricky. Lighthouse opens a fresh page context, which means your login state doesn't automatically carry over.

## The Problem

When you navigate to a protected page with [**~~Playwright~~**](https://playwright.dev) and then run Lighthouse:

```js
// This won't work as expected
await page.goto('https://app.example.com/login')
await page.fill('#email', 'user@example.com')
await page.fill('#password', 'password')
await page.click('button[type="submit"]')
await page.waitForURL('**/dashboard')

// Lighthouse opens a NEW page — login state is lost
const result = await lighthouse('https://app.example.com/dashboard', { port: PORT })
// ❌ Redirects to login page
```

Lighthouse creates its own page to run audits, discarding Playwright's authenticated session.

## Solution: Storage State

Playwright can save and restore session state (cookies, localStorage, sessionStorage). Save it after login, then configure Lighthouse to use the same browser context.

### Step 1: Save Authentication State

```js
import { writeFileSync } from 'node:fs'
import { chromium } from '@playwright/test'

const PORT = 9222

async function saveAuthState() {
  const browser = await chromium.launch({
    args: [`--remote-debugging-port=${PORT}`],
  })

  const context = await browser.newContext()
  const page = await context.newPage()

  // Perform login
  await page.goto('https://app.example.com/login')
  await page.fill('#email', 'user@example.com')
  await page.fill('#password', 'password')
  await page.click('button[type="submit"]')
  await page.waitForURL('**/dashboard')

  // Save storage state
  const storageState = await context.storageState()
  writeFileSync('auth.json', JSON.stringify(storageState))

  await browser.close()
}
```

### Step 2: Run Lighthouse with Saved State

```js
import { readFileSync } from 'node:fs'
import { chromium } from '@playwright/test'
import lighthouse from 'lighthouse'

const PORT = 9222

async function auditAuthenticatedPage(url) {
  const browser = await chromium.launch({
    args: [`--remote-debugging-port=${PORT}`],
  })

  // Load saved authentication state
  const storageState = JSON.parse(readFileSync('auth.json', 'utf-8'))
  const context = await browser.newContext({ storageState })
  const page = await context.newPage()

  // Navigate to authenticated page
  await page.goto(url, { waitUntil: 'networkidle' })

  // Run Lighthouse with storage reset disabled
  const result = await lighthouse(url, {
    port: PORT,
    disableStorageReset: true, // Critical: preserves cookies/storage
    logLevel: 'error',
  })

  await browser.close()
  return result.lhr
}

auditAuthenticatedPage('https://app.example.com/dashboard')
```

**Critical**: Always set `**disableStorageReset: true**`. Without this, Lighthouse clears cookies and storage before the audit, logging you out.

## Complete Working Example

Full script that handles login and audit in one flow:

```js
import { existsSync, readFileSync, writeFileSync } from 'node:fs'
import { chromium } from '@playwright/test'
import lighthouse from 'lighthouse'

const PORT = 9222
const AUTH_FILE = 'auth.json'

async function login(context) {
  const page = await context.newPage()
  await page.goto('https://app.example.com/login')
  await page.fill('#email', process.env.TEST_USER_EMAIL)
  await page.fill('#password', process.env.TEST_USER_PASSWORD)
  await page.click('button[type="submit"]')
  await page.waitForURL('**/dashboard')
  await page.close()
}

async function auditWithAuth(url) {
  const browser = await chromium.launch({
    args: [`--remote-debugging-port=${PORT}`],
  })

  let context

  // Reuse saved auth if available
  if (existsSync(AUTH_FILE)) {
    const storageState = JSON.parse(readFileSync(AUTH_FILE, 'utf-8'))
    context = await browser.newContext({ storageState })
  }
  else {
    context = await browser.newContext()
    await login(context)
    // Save for future runs
    const state = await context.storageState()
    writeFileSync(AUTH_FILE, JSON.stringify(state))
  }

  const page = await context.newPage()
  await page.goto(url, { waitUntil: 'networkidle' })

  const result = await lighthouse(url, {
    port: PORT,
    disableStorageReset: true,
    output: 'html',
  })

  writeFileSync('lighthouse-report.html', result.report)
  await browser.close()

  return result.lhr
}

auditWithAuth('https://app.example.com/dashboard')
```

## Simplifying with Playwright Project Dependencies

Modern Playwright (v1.31+) allows defining [**~~setup projects~~**](https://playwright.dev/docs/test-global-setup-teardown#project-dependencies). This separates login logic from your tests.

**1. Configure `**playwright.config.ts**`:**

```ts
import { defineConfig } from '@playwright/test'

export default defineConfig({
  projects: [
    { name: 'setup', testMatch: /.*\.setup\.ts/ },
    {
      name: 'lighthouse',
      use: {
        // Automatically load auth state
        storageState: 'playwright/.auth/user.json',
      },
      dependencies: ['setup'], // Run setup first
    },
  ],
})
```

**2. Create setup file `**auth.setup.ts**`:**

```ts
import { test as setup } from '@playwright/test'

setup('authenticate', async ({ page }) => {
  await page.goto('https://app.example.com/login')
  // ... perform login ...
  await page.context().storageState({ path: 'playwright/.auth/user.json' })
})
```

**3. Run audit (no login logic needed):**

```ts
test('dashboard performance', async ({ page }) => {
  // Page is already authenticated!
  await page.goto('https://app.example.com/dashboard')

  // Connect Lighthouse to this authenticated session
  // (Use the port and disableStorageReset pattern)
})
```

## Alternative: Cookie Injection via CDP

For token-based auth where `**storageState**` doesn't work (e.g., custom auth headers), inject cookies directly:

```js
import { chromium } from '@playwright/test'
import lighthouse from 'lighthouse'

const PORT = 9222

async function auditWithCookies(url, cookies) {
  const browser = await chromium.launch({
    args: [`--remote-debugging-port=${PORT}`],
  })

  const context = await browser.newContext()

  // Add cookies to context
  await context.addCookies(cookies)

  const page = await context.newPage()
  await page.goto(url, { waitUntil: 'networkidle' })

  const result = await lighthouse(url, {
    port: PORT,
    disableStorageReset: true,
  })

  await browser.close()
  return result.lhr
}

// Usage
auditWithCookies('https://app.example.com/dashboard', [
  {
    name: 'session_token',
    value: 'your-token-here',
    domain: 'app.example.com',
    path: '/',
  },
])
```

## Handling Session Expiry

Long test runs cause session tokens to expire. Add a check:

```js
async function verifyAuthenticated(page, context) {
  await page.goto('https://app.example.com/dashboard')

  // Check if redirected to login
  if (page.url().includes('/login')) {
    await login(context)
    const state = await context.storageState()
    writeFileSync(AUTH_FILE, JSON.stringify(state))
    await page.goto('https://app.example.com/dashboard')
  }
}
```

## Common Pitfalls

| **Issue** | **Solution** |
| --- | --- |
| Session lost after audit | Add `**disableStorageReset: true**` |
| CSRF token invalid | Re-login before each audit |
| Cookies not applying | Check `**domain**` matches exactly |
| Auth works in Playwright but not Lighthouse | Lighthouse uses a new page - check that cookies are on the context, not just the page |

### **Related **

[**Troubleshooting**](https://unlighthouse.dev/learn-lighthouse/playwright/troubleshooting) [**CI/CD Integration**](https://unlighthouse.dev/learn-lighthouse/playwright/ci-cd) [**Playwright Guide**](https://unlighthouse.dev/learn-lighthouse/playwright)

[**Playwright** Run Google Lighthouse audits with Playwright for automated performance, accessibility, and SEO testing. Complete setup guide with code examples.](https://unlighthouse.dev/learn-lighthouse/playwright) [**CI/CD** Automate Lighthouse audits with Playwright in GitHub Actions. Run performance tests on every PR with thresholds and artifact reports.](https://unlighthouse.dev/learn-lighthouse/playwright/ci-cd)

**On this page **

- [The Problem](#the-problem)
- [Solution: Storage State](#solution-storage-state)
- [Complete Working Example](#complete-working-example)
- [Simplifying with Playwright Project Dependencies](#simplifying-with-playwright-project-dependencies)
- [Alternative: Cookie Injection via CDP](#alternative-cookie-injection-via-cdp)
- [Handling Session Expiry](#handling-session-expiry)
- [Common Pitfalls](#common-pitfalls)

---

- **Page:** Playwright Lighthouse in GitHub Actions · Unlighthouse
- **Source:** https://unlighthouse.dev/learn-lighthouse/playwright/ci-cd
- **Description:** Automate Lighthouse audits with Playwright in GitHub Actions. Run performance tests on every PR with thresholds and artifact reports.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Playwright Lighthouse in GitHub Actions**

Automate Lighthouse audits with Playwright in GitHub Actions. Run performance tests on every PR with thresholds and artifact reports.

[![Harlan Wilton](https://avatars.githubusercontent.com/u/5326365?v=4)Harlan Wilton](https://x.com/harlan-zw) Published **Jan 27, 2026** Updated **Aug 9, 2026**

Run Lighthouse audits automatically on every pull request. This guide covers GitHub Actions setup with Playwright-based Lighthouse integration.

**Alternative**: For dedicated CI tooling, consider [**~~Lighthouse CI~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/github-actions) which is purpose-built for CI pipelines with historical tracking and [**~~GitHub~~**](https://github.com) status checks.

## Basic Workflow (Script)

Create `**.github/workflows/lighthouse.yml**`:

```yaml
name: Lighthouse Audit
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright browsers
        run: npx playwright install chromium --with-deps

      - name: Run Lighthouse audit
        run: node scripts/lighthouse-audit.js

      - name: Upload report
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: lighthouse-report
          path: lighthouse-report.html
          retention-days: 14
```

Create `**scripts/lighthouse-audit.js**`:

```js
import { writeFileSync } from 'node:fs'
import { chromium } from '@playwright/test'
import lighthouse from 'lighthouse'

const PORT = 9222
const URL = process.env.AUDIT_URL || 'https://example.com'
const THRESHOLDS = {
  'performance': 80,
  'accessibility': 90,
  'best-practices': 80,
  'seo': 80,
}

async function audit() {
  const browser = await chromium.launch({
    args: [`--remote-debugging-port=${PORT}`],
  })

  const page = await browser.newPage()
  await page.goto(URL, { waitUntil: 'networkidle' })

  const result = await lighthouse(URL, {
    port: PORT,
    output: 'html',
    logLevel: 'error',
  })

  writeFileSync('lighthouse-report.html', result.report)

  const { categories } = result.lhr
  const scores = {
    performance: Math.round(categories.performance.score * 100),
    accessibility: Math.round(categories.accessibility.score * 100),
    bestPractices: Math.round(categories['best-practices'].score * 100),
    seo: Math.round(categories.seo.score * 100),
  }

  // Save scores for PR comment
  writeFileSync('lighthouse-results.json', JSON.stringify(scores, null, 2))

  let failed = false
  for (const [key, threshold] of Object.entries(THRESHOLDS)) {
    const score = scores[key === 'best-practices' ? 'bestPractices' : key]
    const status = score >= threshold ? '✅' : '❌'
    console.log(`${status} ${key}: ${score} (threshold: ${threshold})`)
    if (score < threshold)
      failed = true
  }

  await browser.close()

  if (failed) {
    console.error('\nLighthouse audit failed to meet thresholds')
    process.exit(1)
  }
}

audit()
```

## Testing Preview Deployments

For [**~~Vercel~~**](https://vercel.com), [**~~Netlify~~**](https://netlify.com), or Cloudflare Pages preview URLs (using the script approach):

```yaml
# ... (same as above)
- name: Run Lighthouse
  run: node scripts/lighthouse-audit.js
  env:
    AUDIT_URL: ${{ github.event.deployment_status.target_url }}
```

### Testing Preview Deployments (Playwright Test)

If you are using the `**playwright.config.ts**` setup, override the `**baseURL**`:

```yaml
- name: Run Playwright Lighthouse
  run: npx playwright test
  env:
    PLAYWRIGHT_TEST_BASE_URL: ${{ github.event.deployment_status.target_url }}
```

## Testing Multiple URLs

Audit several pages in one workflow:

```js
// scripts/lighthouse-audit.js
const URLS = [
  'https://example.com/',
  'https://example.com/pricing',
  'https://example.com/docs',
]

async function auditAll() {
  const browser = await chromium.launch({
    args: [`--remote-debugging-port=${PORT}`],
  })

  const results = []

  for (const url of URLS) {
    const page = await browser.newPage()
    await page.goto(url, { waitUntil: 'networkidle' })

    const result = await lighthouse(url, {
      port: PORT,
      logLevel: 'error',
    })

    results.push({
      url,
      performance: Math.round(result.lhr.categories.performance.score * 100),
      accessibility: Math.round(result.lhr.categories.accessibility.score * 100),
    })

    await page.close()
  }

  await browser.close()

  console.table(results)

  // Fail if any page is below threshold
  const failed = results.some(r => r.performance < 80)
  if (failed)
    process.exit(1)
}
```

## With Authentication

For protected pages, use saved auth state:

```yaml
- name: Run Lighthouse on authenticated pages
  run: node scripts/lighthouse-auth-audit.js
  env:
    TEST_USER_EMAIL: ${{ secrets.TEST_USER_EMAIL }}
    TEST_USER_PASSWORD: ${{ secrets.TEST_USER_PASSWORD }}
```

See [**~~Authentication Guide~~**](https://unlighthouse.dev/learn-lighthouse/playwright/authentication) for the full script.

## Reducing Variance

Lighthouse scores vary between runs. Run multiple times and use median:

```js
async function auditWithMedian(url, runs = 3) {
  const scores = []

  for (let i = 0; i < runs; i++) {
    const result = await lighthouse(url, { port: PORT, logLevel: 'error' })
    scores.push(result.lhr.categories.performance.score * 100)
  }

  scores.sort((a, b) => a - b)
  return scores[Math.floor(scores.length / 2)] // Median
}
```

Run at least three audits and compare the median. Keep the runner size, Chrome version, Lighthouse version, and throttling settings fixed between builds. Playwright recommends one worker in CI when reproducibility matters.

## PR Comments with Results

Post Lighthouse scores as a PR comment:

```yaml
- name: Comment PR
  if: github.event_name == 'pull_request'
  uses: actions/github-script@v7
  with:
    script: |
      import fs from 'fs'
      const results = JSON.parse(fs.readFileSync('lighthouse-results.json'))

      const body = `## Lighthouse Results

      | Metric | Score |
      |--------|-------|
      | Performance | ${results.performance} |
      | Accessibility | ${results.accessibility} |
      | Best Practices | ${results.bestPractices} |
      | SEO | ${results.seo} | `

      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body
      })
```

## Installing browsers in CI

[**~~Playwright does not recommend caching browser binaries~~**](https://playwright.dev/docs/ci#caching-browsers). Restoring the cache often takes as long as downloading the browser, and Linux system dependencies still need a separate install. Install only Chromium for this job:

```yaml
- name: Install Chromium and system dependencies
  run: npx playwright install chromium --with-deps
```

## Full Production Workflow

Use Playwright's [`**webServer**`](https://playwright.dev/docs/test-webserver) configuration to handle starting/stopping your app automatically.

**1. Configure `**playwright.config.ts**`:**

```ts
import { defineConfig } from '@playwright/test'

export default defineConfig({
  webServer: {
    command: 'npm run preview',
    port: 4173,
    timeout: 120 * 1000,
    reuseExistingServer: !process.env.CI,
  },
})
```

**2. Update GitHub Actions Workflow:**

```yaml
name: Lighthouse CI
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - run: npm ci
      - run: npx playwright install chromium --with-deps
      - run: npm run build

      # Playwright starts the server automatically!
      - name: Run Lighthouse
        run: npx playwright test
```

## Scaling with Sharding

Lighthouse audits are slow. For large sites, run tests in parallel across multiple machines using [**~~Playwright~~**](https://playwright.dev) [**~~Sharding~~**](https://playwright.dev/docs/test-sharding).

```yaml
jobs:
  lighthouse:
    strategy:
      fail-fast: false
      matrix:
        shardIndex: [1, 2, 3, 4]
        shardTotal: [4]
    runs-on: ubuntu-latest
    steps:
      # ... setup steps ...

      - name: Run Lighthouse (Shard ${{ matrix.shardIndex }}/${{ matrix.shardTotal }})
        run: npx playwright test --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}

      - name: Upload Blob Report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: blob-report-${{ matrix.shardIndex }}
          path: blob-report
          retention-days: 1
```

You can then merge these reports in a separate job using `**npx playwright merge-reports**`.

## When to Use Lighthouse CI Instead

For advanced CI features, [**~~Lighthouse CI~~**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci) provides:

- Historical tracking across builds
- GitHub status checks (not just comments)
- Baseline comparisons
- Built-in assertion presets

The Playwright approach works well for simpler setups or when you need custom control over the browser context (like authentication).

### **Related **

[**Lighthouse CI with GitHub Actions**](https://unlighthouse.dev/learn-lighthouse/lighthouse-ci/github-actions) [**Authentication**](https://unlighthouse.dev/learn-lighthouse/playwright/authentication) [**Troubleshooting**](https://unlighthouse.dev/learn-lighthouse/playwright/troubleshooting)

[**Authentication** Run Lighthouse audits on pages behind login. Learn how to preserve authentication state when Lighthouse opens a new browser context.](https://unlighthouse.dev/learn-lighthouse/playwright/authentication) [**Troubleshooting** Fix common issues when running Lighthouse with Playwright: port conflicts, authentication problems, flaky scores, and Chrome version mismatches.](https://unlighthouse.dev/learn-lighthouse/playwright/troubleshooting)

**On this page **

- [Basic Workflow (Script)](#basic-workflow-script)
- [Testing Preview Deployments](#testing-preview-deployments)
- [Testing Multiple URLs](#testing-multiple-urls)
- [With Authentication](#with-authentication)
- [Reducing Variance](#reducing-variance)
- [PR Comments with Results](#pr-comments-with-results)
- [Installing browsers in CI](#installing-browsers-in-ci)
- [Full Production Workflow](#full-production-workflow)
- [Scaling with Sharding](#scaling-with-sharding)
- [When to Use Lighthouse CI Instead](#when-to-use-lighthouse-ci-instead)

---

- **Page:** Integration Deprecations · Unlighthouse
- **Source:** https://unlighthouse.dev/integration-deprecations
- **Description:** Build tool integrations are deprecated in v1.0. Learn about migration paths and alternatives.

Star Unlighthouse on GitHubUnlighthouse on GitHub

# **Integration Deprecations**

[Copy for LLMs](https://unlighthouse.dev/integration-deprecations.md)

The following build tool integrations are deprecated and will be removed in v1.0:

- `**@unlighthouse/nuxt**`
- `**@unlighthouse/vite**`
- `**@unlighthouse/webpack**`

Start migrating to [**~~CLI~~**](https://unlighthouse.dev/integrations/cli) or [**~~CI~~**](https://unlighthouse.dev/integrations/ci) integrations for continued support.

## Background

When Unlighthouse was being developed, the goal was to make it as simple as possible to use with your development site.

To allow for this, integrations where added that set up Unlighthouse automatically for you.

This provided the site URL, automatic rescans on page updates and route discovery, which allowed for smarter sampling of dynamic routes.

## Why Deprecate?

Simply, the integrations are too difficult to maintain, error-prone and provide low-value.

In nearly all raised issues related to integration, they weren't needed and the CLI could be used instead.

## Upgrading

You should remove any of the following packages from your project.

- `**@unlighthouse/nuxt**`
- `**@unlighthouse/vite**`
- `**@unlighthouse/webpack**`

Instead, you should simply use the CLI.

```bash
npx unlighthouse --site localhost:3000
```

The HMR integration be solved by manually rescanning routes using the UI.

The route discovery will still work when scanned in the root directory or an app with `**pages**`.

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/integration-deprecations.md)

[Markdown For LLMs](https://unlighthouse.dev/integration-deprecations.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/integration-deprecations.md) on GitHub or provide anonymous feedback below.

### **Related **

[**CLI Integration**](https://unlighthouse.dev/integrations/cli) [**CI Integration**](https://unlighthouse.dev/integrations/ci) [**Configuration**](https://unlighthouse.dev/guide/guides/config)

**On this page **

- [Background](#background)
- [Why Deprecate?](#why-deprecate)
- [Upgrading](#upgrading)