Lighthouse Configuration

Customize audit categories, performance thresholds, and behavior through the lighthouseOptions configuration key. Unlighthouse passes these options directly to Google Lighthouse.

Unlighthouse v1 runs Lighthouse 13. See the Lighthouse 13 release notes for the full changelog; the additions that affect Unlighthouse are the new agentic-browsing category and the expanded insight audits, both covered below.

import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  lighthouseOptions: {
    throttlingMethod: 'devtools',
  },
})

For complete options, see the Lighthouse Configuration docs.

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
• Toggle 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', 'agentic-browsing'.

The Performance category uses Lighthouse lab measurements, including LCP, CLS, and TBT. TBT is a responsiveness diagnostic, not a Core Web Vital. Core Web Vitals are LCP, INP, and CLS. A field assessment requires eligible real-user measurements. The agentic-browsing category is new in Lighthouse 13 (see below).

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

export default defineUnlighthouseConfig({
  lighthouseOptions: {
    onlyCategories: ['performance'],
  },
})

Agentic Browsing (Lighthouse 13)

Lighthouse 13 adds the agentic-browsing category, which measures how well a page can be driven by AI agents. Unlighthouse scans it by default and surfaces it as a fifth score alongside performance, accessibility, best-practices, and SEO.

Chrome's agentic browsing scoring docs mark this category as experimental. Current Chrome guidance requires Chrome 150 or later for the category, and WebMCP-specific audits require the WebMCP origin trial. Unlighthouse enables the DevTools WebMCP feature flag for local Lighthouse launches, but the final result still depends on the Chrome binary and remote browser service you run against.

Unlike the traditional categories, agentic browsing is displayed as a fraction rather than a 0-100 gauge. Unlighthouse preserves that display mode in the UI, API, and JSON reports.

The category rolls up these audits:

• agent-accessibility-tree — is the page's accessibility tree usable by an agent?
• webmcp-registered-tools — does the page register WebMCP tools?
• webmcp-form-coverage — how many forms are exposed as agent-callable tools?
• webmcp-schema-validity — are the registered tool schemas valid?
• cumulative-layout-shift — is the page stable enough for an agent to interact with it?
• llms-txt — does an optional llms.txt file follow Lighthouse's recommendations?

The built-in agentic-browsing pack reconciles these across every route into a single readiness report (WebMCP coverage, llms.txt presence, agent-accessibility pass rate). Drop the category to skip the work:

export default defineUnlighthouseConfig({
  lighthouseOptions: {
    onlyCategories: ['performance', 'accessibility', 'best-practices', 'seo'],
  },
})

Adapter support

Insight Audits

Lighthouse insight audits retain their native IDs and titles. Timing savings use milliseconds. CLS savings are dimensionless. The insights pack groups affected URLs and estimates for each metric. priorityOrderByMetric ranks insights within each metric. worstRoutesByMetric lists the largest estimates for that metric. The main insight list follows native ID order. Estimates across metrics are not additive.