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

> Customize Lighthouse by passing a config object to control which audits run, how they are scored, and what settings apply.

The Lighthouse config object is the primary way to customize a Lighthouse run. You can use it to limit which audits run, add custom checks, adjust throttling, tweak scoring, and more.

## Passing a config

<Steps>
  <Step title="Create a config file">
    Create a JavaScript file that exports your config object. Most configs extend `lighthouse:default` to inherit the full default set of audits, artifacts, and categories.

    ```js custom-config.js theme={null}
    export default {
      extends: 'lighthouse:default',
      settings: {
        onlyAudits: [
          'speed-index',
          'interactive',
        ],
      },
    };
    ```
  </Step>

  <Step title="Pass the config to Lighthouse">
    Use the `--config-path` flag when running from the CLI, or pass the config as the third argument when using the Node API.

    <Tabs>
      <Tab title="CLI">
        ```bash theme={null}
        lighthouse --config-path=path/to/custom-config.js https://example.com
        ```
      </Tab>

      <Tab title="Node API">
        ```js theme={null}
        import lighthouse from 'lighthouse';
        import config from './path/to/custom-config.js';

        await lighthouse('https://example.com/', { port: 9222 }, config);
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Config properties

| Property     | Type                  | Description                                                               |
| ------------ | --------------------- | ------------------------------------------------------------------------- |
| `extends`    | `string \| undefined` | Inherit from a built-in config. Only `'lighthouse:default'` is supported. |
| `settings`   | `Object \| undefined` | Control runtime options such as throttling and which audits to run.       |
| `artifacts`  | `Object[]`            | List of artifacts (data gathered from the page) to collect.               |
| `audits`     | `string[]`            | Audits to run against the collected artifacts.                            |
| `categories` | `Object \| undefined` | How to group and score audits in the report.                              |
| `groups`     | `Object \| undefined` | Visual groupings of audits within a category.                             |
| `plugins`    | `string[]`            | Plugin packages to include, which can add their own audits.               |

### `extends`

Setting `extends: 'lighthouse:default'` makes your config inherit the default artifacts, audits, groups, and categories. You can then add to or override only what you need.

<Tip>
  Config extension is the recommended approach for running custom Lighthouse. Without `extends`, you must define all artifacts and audits yourself.
</Tip>

```js theme={null}
export default {
  extends: 'lighthouse:default',
  settings: {
    skipAudits: ['uses-http2'],
  },
};
```

<Note>
  `extends` only supports `'lighthouse:default'`. To use other built-in presets such as `perf`, `desktop`, or `experimental`, use the `--preset` CLI flag or import the config file directly.
</Note>

### `settings`

The `settings` object controls runtime behavior. The most commonly used options are:

| Option           | Type       | Description                                                                                            |
| ---------------- | ---------- | ------------------------------------------------------------------------------------------------------ |
| `onlyCategories` | `string[]` | Run only the specified categories. Additive with `onlyAudits`. Reduces total audit time.               |
| `onlyAudits`     | `string[]` | Run only the specified audits. Additive with `onlyCategories`. Reduces total audit time.               |
| `skipAudits`     | `string[]` | Exclude the specified audits. Takes priority over `onlyCategories`. Not usable alongside `onlyAudits`. |

```js theme={null}
export default {
  extends: 'lighthouse:default',
  settings: {
    onlyCategories: ['performance'],
    skipAudits: ['uses-http2'],
  },
};
```

For the full list of settings options, see the [configuration reference](/api/configuration-reference).

### `artifacts`

Artifacts are the raw data gathered from a page load. Each artifact is produced by a gatherer. On extension, artifacts are concatenated with the defaults.

| Field      | Type     | Description                                                  |
| ---------- | -------- | ------------------------------------------------------------ |
| `id`       | `string` | Unique identifier used to reference this artifact in audits. |
| `gatherer` | `string` | The gatherer module that produces this artifact.             |

```js theme={null}
{
  artifacts: [
    { id: 'Accessibility', gatherer: 'accessibility' },
    { id: 'AnchorElements', gatherer: 'anchor-elements' },
  ],
}
```

### `audits`

The list of audit modules to run. Audits receive artifacts and produce scored results.

```js theme={null}
{
  audits: [
    'first-contentful-paint',
    'byte-efficiency/unminified-css',
  ],
}
```

### `categories`

Categories group audits and produce an overall score. Each category entry appears in the Lighthouse report with an aggregate score.

| Field                  | Type                | Description                                        |
| ---------------------- | ------------------- | -------------------------------------------------- |
| `title`                | `string`            | Display name of the category.                      |
| `description`          | `string`            | Description shown in the report.                   |
| `auditRefs`            | `Object[]`          | Audits to include in this category.                |
| `auditRefs[$i].id`     | `string`            | The audit ID to include.                           |
| `auditRefs[$i].weight` | `number`            | Scoring weight for this audit within the category. |
| `auditRefs[$i].group`  | `string` (optional) | Display group ID for this audit.                   |

```js theme={null}
{
  categories: {
    performance: {
      title: 'Performance',
      auditRefs: [
        { id: 'first-contentful-paint', weight: 3, group: 'metrics' },
        { id: 'interactive', weight: 5, group: 'metrics' },
      ],
    },
  },
}
```

<Note>
  Many tools that consume Lighthouse do not need to group or score audit results. In those cases, omitting `categories` is fine.
</Note>

### `groups`

Groups control how audits are visually organized within a category in the report.

<Warning>
  The report renderer has hardcoded display logic tied to specific group names. Adding arbitrary groups without matching renderer logic may not display as expected.
</Warning>

```js theme={null}
{
  groups: {
    metrics: {
      title: 'Metrics',
      description: 'These metrics encapsulate your web app\'s performance across a number of dimensions.',
    },
  },
}
```

## Built-in presets

Lighthouse ships with several preset configs you can use via the `--preset` CLI flag:

| Preset         | Description                                                                               |
| -------------- | ----------------------------------------------------------------------------------------- |
| `perf`         | Runs only performance audits for faster results.                                          |
| `desktop`      | Applies desktop viewport and scoring calibration instead of the default mobile emulation. |
| `experimental` | Enables experimental audits not yet in the default config.                                |

```bash theme={null}
# Run with the desktop preset
lighthouse --preset=desktop https://example.com

# Run with the perf preset
lighthouse --preset=perf https://example.com
```

## Config extension

Config extension lets you build on the default Lighthouse setup with minimal boilerplate. When `extends: 'lighthouse:default'` is set, the default artifacts, audits, groups, and categories are automatically included. You only need to specify what you want to change.

```js custom-config.js theme={null}
export default {
  extends: 'lighthouse:default',
  settings: {
    onlyCategories: ['performance', 'accessibility'],
  },
  audits: [
    // add custom audits here
  ],
};
```

For more on the full config schema, see the [configuration reference](/api/configuration-reference).