> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/GoogleChrome/lighthouse/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

***

## 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.                                          |

<Note>
  `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.
</Note>

```js theme={null}
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. |

```js theme={null}
{
  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.

```js theme={null}
{
  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. |

<Note>
  When using `extends: 'lighthouse:default'`, your `artifacts` array is concatenated with the default set, not replaced.
</Note>

***

## `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.

```js theme={null}
{
  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.

```js theme={null}
{
  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.                   |

<Note>
  Many programmatic consumers of Lighthouse skip the `categories` section entirely. Scores are only computed if categories are defined.
</Note>

***

## `groups`

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

```js theme={null}
{
  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.

```js theme={null}
{
  plugins: ['lighthouse-plugin-field-performance'],
}
```

See the [plugin documentation](https://github.com/GoogleChrome/lighthouse/blob/main/docs/plugins.md) 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.                                           |

```js theme={null}
import lighthouse, {desktopConfig} from 'lighthouse';

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

```bash theme={null}
# 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.

```js theme={null}
// 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:

<CodeGroup>
  ```bash CLI theme={null}
  lighthouse https://example.com --config-path=./custom-config.js
  ```

  ```js Node theme={null}
  import lighthouse from 'lighthouse';
  import config from './custom-config.js';

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