Configuration reference

Full reference for the Lighthouse config object, settings, artifacts, audits, categories, and built-in presets.

The Lighthouse config object is the primary way to customize a run. Use it to limit which audits run, change throttling settings, add custom checks, adjust scoring, and more.

Config extension with extends: 'lighthouse:default' is the recommended approach. Build from scratch only when you need complete control over every audit.

---

Config object schema

Property	Type	Description
extends	string | undefined	Inherit from a base config. Currently only 'lighthouse:default' is supported.
settings	object | undefined	Runtime settings such as throttling, output format, and audit selection.
artifacts	object[]	Gatherers that collect data from the page. Concatenated with the base config’s artifacts on extension.
audits	string[]	Audit IDs to run. Concatenated on extension.
categories	object | undefined	Scoring groups that aggregate audits into a reportable score.
groups	object | undefined	Visual display groups for audits within a category.
plugins	string[]	Plugin package names to load and run.

---

extends

Controls whether your config inherits the full default Lighthouse configuration.

Value	Behavior
'lighthouse:default'	Inherits all default artifacts, audits, categories, and groups. Your settings, audits, and artifacts are merged on top.
undefined (omitted)	Starts from scratch. You must define all artifacts, audits, and categories yourself.

extends only supports 'lighthouse:default'. To use other built-in configs such as lr-desktop-config, import them directly as JS modules or use the --preset CLI flag.

export default {
  extends: 'lighthouse:default',
  settings: {
    onlyCategories: ['performance'],
  },
};

---

settings

The settings object controls runtime behavior: which audits run, throttling, output format, and more.

Audit selection

Option	Type	Description
onlyCategories	string[]	Run only the listed categories. Additive with onlyAudits. Reduces audit time.
onlyAudits	string[]	Run only the listed audit IDs. Additive with onlyCategories.
skipAudits	string[]	Exclude the listed audit IDs. Takes priority over onlyCategories. Cannot be used alongside onlyAudits.

Throttling

Option	Type	Description
throttlingMethod	'devtools' | 'simulate' | 'provided'	Throttling implementation. simulate (default) models network conditions without actually throttling.
throttling.rttMs	number	Simulated round-trip time at the TCP layer (ms).
throttling.throughputKbps	number	Simulated download throughput (Kbps).
throttling.requestLatencyMs	number	Emulated RTT at the HTTP layer (ms).
throttling.downloadThroughputKbps	number	Emulated download throughput (Kbps).
throttling.uploadThroughputKbps	number	Emulated upload throughput (Kbps).
throttling.cpuSlowdownMultiplier	number	CPU slowdown multiplier (4× default for mobile).

Output

Option	Type	Description
output	string | string[]	Output format(s). Choices: 'html', 'json', 'csv'.
maxWaitForLoad	number	Milliseconds to wait before considering the page loaded.
locale	string	Locale for the report (e.g. 'en-US').

Emulation

Option	Type	Description
formFactor	'mobile' | 'desktop'	Determines performance scoring model and skips mobile-only audits when 'desktop'.
screenEmulation	object	Screen dimensions and scale factor. Set disabled: true to turn off.
emulatedUserAgent	string | false	User agent string. Set to false to disable UA spoofing.

Other settings

Option	Type	Description
gatherMode	boolean | string	Save artifacts to disk after gathering.
auditMode	boolean | string	Read artifacts from disk instead of launching a browser.
disableStorageReset	boolean	Skip clearing cache and storage before the run.
blockedUrlPatterns	string[]	Block requests matching these URL patterns.
extraHeaders	object	Additional HTTP headers to send with every request.
onlyCategories	string[]	Alias for the onlyCategories audit-selection option above.

{
  settings: {
    onlyCategories: ['performance'],
    onlyAudits: ['works-offline'],
    throttlingMethod: 'simulate',
    throttling: {
      rttMs: 150,
      throughputKbps: 1638.4,
      cpuSlowdownMultiplier: 4,
    },
    formFactor: 'mobile',
    output: 'json',
  },
}

---

artifacts

An array of gatherer definitions that collect data from the page. Each entry maps an artifact ID to a gatherer implementation.

{
  artifacts: [
    {id: 'Accessibility', gatherer: 'accessibility'},
    {id: 'AnchorElements', gatherer: 'anchor-elements'},
    {id: 'MyCustomData', gatherer: './custom-gatherer.js'},
  ],
}

Field	Type	Description
id	string	Unique identifier for the artifact. Audits reference this ID in requiredArtifacts.
gatherer	string	Path to the gatherer module. Built-in gatherers are referenced by name; custom ones by file path.

When using extends: 'lighthouse:default', your artifacts array is concatenated with the default set, not replaced.

---

audits

An array of audit IDs or file paths to include in the run. Built-in audits are referenced by their ID; custom audits by their module path.

{
  audits: [
    'first-contentful-paint',
    'byte-efficiency/unminified-css',
    './audits/my-custom-audit.js',
  ],
}

---

categories

Defines how audit results are grouped and scored into top-level category scores.

{
  categories: {
    performance: {
      title: 'Performance',
      description: 'This category judges your page performance.',
      auditRefs: [
        {id: 'first-contentful-paint', weight: 10, group: 'metrics'},
        {id: 'interactive', weight: 10, group: 'metrics'},
        {id: 'speed-index', weight: 10, group: 'metrics'},
      ],
    },
  },
}

Field	Type	Description
title	string	Display name of the category.
description	string	Explanation of what the category measures.
supportedModes	string[]	User flow modes this category supports. Omit to support all modes.
auditRefs	object[]	Audits included in this category.
auditRefs[].id	string	Audit ID to include.
auditRefs[].weight	number	Contribution to the overall category score.
auditRefs[].group	string	Optional display group ID for visual clustering.

Many programmatic consumers of Lighthouse skip the categories section entirely. Scores are only computed if categories are defined.

---

groups

Defines visual display groups that cluster audits within a category in the HTML report.

{
  groups: {
    'metrics': {
      title: 'Metrics',
      description: 'These metrics encapsulate your web app\'s performance.',
    },
    'diagnostics': {
      title: 'Diagnostics',
      description: 'Additional information about your page\'s performance.',
    },
  },
}

Field	Type	Description
title	string	Display name of the group.
description	string	Short description shown in the report.

---

plugins

An array of Lighthouse plugin package names to load. Plugins can add custom audits and categories.

{
  plugins: ['lighthouse-plugin-field-performance'],
}

See the plugin documentation for how to author plugins.

---

Built-in configs

Lighthouse ships several reference configs. Use them directly via import or the --preset CLI flag.

Config	CLI preset	Description
lighthouse:default	(base)	The standard full Lighthouse config. All categories enabled with mobile emulation and simulated throttling.
core/config/lr-desktop-config.js	—	Google Lighthouse desktop form factor config. Used by PageSpeed Insights.
core/config/lr-mobile-config.js	—	Google Lighthouse mobile form factor config. Used by PageSpeed Insights.
core/config/perf-config.js	perf	Performance-only config. Runs only the performance category.
core/config/desktop-config.js	desktop	Desktop preset. Disables mobile emulation and adjusts throttling.

import lighthouse, {desktopConfig} from 'lighthouse';

// Use the built-in desktop config
const result = await lighthouse('https://example.com', {port: chrome.port}, desktopConfig);

# Via CLI
lighthouse https://example.com --preset=desktop
lighthouse https://example.com --preset=perf

---

Complete custom config example

The following config extends the Lighthouse default, limits the run to performance, adds a custom audit, and adjusts the category weights.

// custom-config.js
import MyAudit from './audits/my-audit.js';
import MyGatherer from './gatherers/my-gatherer.js';

export default {
  extends: 'lighthouse:default',

  settings: {
    onlyCategories: ['performance', 'custom'],
    throttlingMethod: 'simulate',
    formFactor: 'mobile',
    output: ['html', 'json'],
  },

  artifacts: [
    // Custom gatherer — appended to the default artifact list
    {id: 'MyData', gatherer: './gatherers/my-gatherer.js'},
  ],

  audits: [
    // Custom audit — appended to the default audit list
    './audits/my-audit.js',
  ],

  categories: {
    // Override the existing performance category weights
    performance: {
      title: 'Performance',
      auditRefs: [
        {id: 'first-contentful-paint', weight: 10, group: 'metrics'},
        {id: 'interactive', weight: 10, group: 'metrics'},
        {id: 'speed-index', weight: 10, group: 'metrics'},
        {id: 'total-blocking-time', weight: 30, group: 'metrics'},
        {id: 'cumulative-layout-shift', weight: 25, group: 'metrics'},
        {id: 'largest-contentful-paint', weight: 25, group: 'metrics'},
      ],
    },
    // Add a completely new category
    custom: {
      title: 'Custom checks',
      description: 'Checks added by our team.',
      auditRefs: [
        {id: 'my-audit', weight: 1},
      ],
    },
  },

  groups: {
    metrics: {
      title: 'Metrics',
      description: 'Performance metrics collected from the page.',
    },
  },
};

Use the config via CLI or Node:

CLI

lighthouse https://example.com --config-path=./custom-config.js

import lighthouse from 'lighthouse';
import config from './custom-config.js';

const result = await lighthouse('https://example.com', {port: chrome.port}, config);