---
title: "Configuration · Unlighthouse"
meta:
  "og:description": "Configure Unlighthouse for your specific needs using configuration files and inline options."
  "og:title": "Configuration · Unlighthouse"
  description: "Configure Unlighthouse for your specific needs using configuration files and inline options."
---

**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](#the-config-file)

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

```
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](#config-file-location)

Unlighthouse looks for these files in order:

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

Or specify one explicitly:

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

## [Common Configs](#common-configs)

### [Skip Paths You Don't Care About](#skip-paths-you-dont-care-about)

```
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:

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

### [Desktop Instead of Mobile](#desktop-instead-of-mobile)

Default is mobile. Switch to desktop:

```
export default {
  scanner: {
    device: 'desktop',
  },
}
```

### [More Accurate Scores](#more-accurate-scores)

Lighthouse scores vary between runs. For reliable numbers:

```
export default {
  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)](#protected-sites-auth)

```
export default {
  // 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](#ci-performance-budgets)

Fail your build if scores drop:

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

## [Advanced](#advanced)

### [Customize Lighthouse Directly](#customize-lighthouse-directly)

Pass options straight to Lighthouse:

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

### [React to Scan Events](#react-to-scan-events)

```
export default {
  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](#environment-based-config)

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

[**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)