---
title: "Configuration · Unlighthouse"
canonical_url: "https://unlighthouse.dev/guide/guides/config"
last_updated: "2026-04-13T07:29:34Z"
meta:
  description: "Configure Unlighthouse for your specific needs using configuration files and inline options."
  "og:description": "Configure Unlighthouse for your specific needs using configuration files and inline options."
  "og:title": "Configuration · Unlighthouse"
---

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Guides**

# **Configuration**

[Copy for LLMs](https://unlighthouse.dev/guide/guides/config.md)

Most scans work without any config. But when you need control—excluding paths, adjusting concurrency, setting up auth—here's how.

## The Config File

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/*'],
  },
})
```

Now run `**unlighthouse**` without flags. It picks up your config automatically.

The import is optional—skip it if you have resolution issues. The config still works.

## Config File Location

Unlighthouse looks for these files in order:

- `**unlighthouse.config.ts**`
- `**unlighthouse.config.js**`
- `**unlighthouse.config.mjs**`

Or specify one explicitly:

```bash
unlighthouse --config-file ./configs/production.config.ts
```

## Common Configs

### Skip Paths You Don't Care About

```ts
export default defineUnlighthouseConfig({
  site: 'https://example.com',
  scanner: {
    exclude: [
      '/api/*', // API routes
      '/admin/*', // Admin pages
      '/*.pdf', // PDF files
      '/amp/*', // AMP versions
    ],
  },
})
```

Or scan *only* specific paths:

```ts
export default defineUnlighthouseConfig({
  scanner: {
    include: ['/products/*', '/blog/*'], // Only these
  },
})
```

### Desktop Instead of Mobile

Default is mobile. Switch to desktop:

```ts
export default defineUnlighthouseConfig({
  scanner: {
    device: 'desktop',
  },
})
```

### More Accurate Scores

Lighthouse scores vary between runs. For reliable numbers:

```ts
export default defineUnlighthouseConfig({
  scanner: {
    samples: 3, // Run 3x per page, average the results
    throttle: true, // Simulate real network (slower but realistic)
  },
  puppeteerClusterOptions: {
    maxConcurrency: 1, // One at a time (less CPU contention)
  },
})
```

Trade-off: Much slower scans. Use for CI assertions, not development.

### Protected Sites (Auth)

```ts
export default defineUnlighthouseConfig({
  // Basic auth
  auth: {
    username: process.env.AUTH_USER,
    password: process.env.AUTH_PASS,
  },
  // Cookie auth
  cookies: [
    { name: 'session', value: process.env.SESSION_TOKEN, domain: '.example.com' },
  ],
})
```

See [**~~full authentication guide~~**](https://unlighthouse.dev/guide/guides/authentication).

### CI Performance Budgets

Fail your build if scores drop:

```ts
export default defineUnlighthouseConfig({
  ci: {
    budget: {
      'performance': 80,
      'accessibility': 90,
      'best-practices': 80,
      'seo': 90,
    },
    buildStatic: true, // Generate shareable HTML report
  },
})
```

## Advanced

### Customize Lighthouse Directly

Pass options straight to Lighthouse:

```ts
export default defineUnlighthouseConfig({
  lighthouseOptions: {
    onlyCategories: ['performance', 'accessibility'], // Skip SEO/best-practices
    skipAudits: ['uses-http2'], // Ignore specific audits
    throttlingMethod: 'devtools',
  },
})
```

### React to Scan Events

```ts
export default defineUnlighthouseConfig({
  hooks: {
    'task-complete': (path, report) => {
      if (report.score.performance < 0.5) {
        console.warn(`⚠️ ${path} scored ${report.score.performance}`)
      }
    },
    'worker-finished': () => {
      console.log('All done!')
    },
  },
})
```

### Environment-Based Config

```ts
export default defineUnlighthouseConfig(() => {
  const isProd = process.env.NODE_ENV === 'production'

  return {
    site: isProd ? 'https://mysite.com' : 'http://localhost:3000',
    scanner: {
      samples: isProd ? 3 : 1,
      throttle: isProd,
    },
  }
})
```

## Full Reference

See [**~~Config Reference~~**](https://unlighthouse.dev/api-doc/config) for every option with types and defaults.

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/0.config.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/guides/config.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/0.config.md) on GitHub or provide anonymous feedback below.

### **Related **

[**Config Reference**](https://unlighthouse.dev/api-doc/config) [**Debugging**](https://unlighthouse.dev/guide/guides/debugging) [**CLI Integration**](https://unlighthouse.dev/integrations/cli)

[**How It Works** Learn how Unlighthouse automatically discovers pages, runs Lighthouse audits in parallel, and generates site-wide performance reports.](https://unlighthouse.dev/guide/getting-started/how-it-works) [**Debugging** Debug and troubleshoot Unlighthouse scans using logging, browser inspection, and diagnostic tools.](https://unlighthouse.dev/guide/guides/debugging)

**On this page **

- [The Config File](#the-config-file)
- [Config File Location](#config-file-location)
- [Common Configs](#common-configs)
- [Advanced](#advanced)
- [Full Reference](#full-reference)