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'],
}
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.',
},
},
};
lighthouse https://example.com --config-path=./custom-config.js
