---
title: "Configuration"
description: "Configuration for the Unlighthouse v1 beta."
canonical_url: "https://unlighthouse.dev/v1/guide/guides/config"
last_updated: "2026-10-03T08:07:15.738Z"
---

Create `unlighthouse.config.ts` in your project root.

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  site: 'https://example.com',
  scanner: {
    exclude: ['/admin/*', '/api/*'],
    samples: 3,
    perfConcurrency: 'serial',
  },
})
```

Run `pnpm exec unlighthouse` to use this config.
Explicit CLI flags override configured values.

## Config location

```sh
pnpm exec unlighthouse --root ./project --config-file unlighthouse.config.ts
```

`root` controls config lookup and relative output paths.

## Select URLs and devices

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  site: 'https://example.com',
  urls: ['/', '/about'],
  scanner: { device: 'desktop' },
})
```

Explicit `urls` disable link following.
Supply a `site` when your URLs come from a provider function.
Use `--device mobile,desktop` for a device matrix.

## CI budgets

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  site: 'https://example.com',
  ci: { reporter: 'json', budget: { performance: 80, accessibility: 90 } },
})
```

Run this config with `pnpm exec unlighthouse-ci`.
Budgets use percentages from 1 to 100.

## Authentication and browser settings

Use [Authentication](/guide/guides/authentication) for headers, basic auth, and storage seeding.
Use [Chrome Options](/guide/guides/puppeteer) for supported browser settings.
Legacy Puppeteer cluster options and config hooks are unsupported.

## Scan events

Register events through the [host API](/api-doc#register-hooks).
Use `onResolvedConfig` for work that must happen before runtime initialization.

See the [Config Reference](/api-doc/config) and [migration guide](/guide/guides/migrating-to-v1).

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.