Configuration
Introduction
Unlighthouse provides flexible configuration options to customize scanning behavior, performance settings, and report generation. While each integration supports inline configuration, complex projects benefit from dedicated configuration files.
This guide covers configuration file setup, common patterns, and advanced customization options.
Configuration File
File Discovery
Unlighthouse automatically discovers configuration files in your project root:
- Default:
unlighthouse.config.ts - Custom: Use
configFileoption or--config-fileCLI flag
Basic Configuration
import { defineUnlighthouseConfig } from 'unlighthouse/config'
export default defineUnlighthouseConfig({
site: 'https://example.com',
scanner: {
exclude: ['/private/*']
},
debug: true,
})
unlighthouse/config package has issues resolving you can safely remove the import.Configuration Options
For a complete list of configuration options, see the Config Reference.
Common Configuration Patterns
Performance Optimization
Optimize scanning for large sites:
import { defineUnlighthouseConfig } from 'unlighthouse/config'
export default defineUnlighthouseConfig({
site: 'https://large-site.com',
scanner: {
device: {
concurrency: 3,
},
samples: 3,
throttle: true,
maxRoutes: 100,
},
})
Route Filtering
Exclude specific patterns from scanning:
export default defineUnlighthouseConfig({
site: 'https://example.com',
scanner: {
exclude: [
'/api/**',
'/**/*.pdf',
'/**/amp',
'/admin/**',
],
include: ['/products/**'],
},
})
Device Configuration
Customize viewport and user agent:
export default defineUnlighthouseConfig({
scanner: {
device: 'desktop', // or 'mobile'
// Custom device settings
customDevice: {
viewport: {
width: 1920,
height: 1080,
},
userAgent: 'Custom User Agent String',
},
},
})
Authentication Setup
Configure authentication for protected sites:
export default defineUnlighthouseConfig({
scanner: {
// Basic auth
auth: {
username: process.env.AUTH_USER,
password: process.env.AUTH_PASS,
},
// Cookies for session auth
cookies: [
{
name: 'session',
value: process.env.SESSION_TOKEN,
domain: '.example.com',
},
],
},
})
CI/CD Configuration
Optimize for continuous integration:
export default defineUnlighthouseConfig({
ci: {
// Generate static reports
buildStatic: true,
// Set performance budgets
budget: {
'performance': 90,
'accessibility': 95,
'best-practices': 90,
'seo': 90,
},
},
scanner: {
// Faster scans for CI
samples: 1,
throttle: false,
},
})
Advanced Configuration
Custom Lighthouse Configuration
Extend Lighthouse's default configuration:
export default defineUnlighthouseConfig({
lighthouseOptions: {
// Custom Lighthouse flags
onlyCategories: ['performance', 'accessibility'],
// Disable specific audits
skipAudits: ['uses-http2'],
// Custom gathering settings
throttlingMethod: 'devtools',
},
})
Hook System
Respond to scanning events:
export default defineUnlighthouseConfig({
hooks: {
'reporter:done': (reports) => {
console.log(`Scanned ${reports.length} pages`)
},
'task:complete': (result) => {
if (result.report.score.performance < 0.5) {
console.warn(`Poor performance: ${result.route.path}`)
}
},
},
})
Dynamic Configuration
Generate configuration based on environment:
export default defineUnlighthouseConfig(() => {
const isProduction = process.env.NODE_ENV === 'production'
return {
site: isProduction
? 'https://production.com'
: 'http://localhost:3000',
scanner: {
samples: isProduction ? 3 : 1,
throttle: isProduction,
},
}
})
For complete configuration options, refer to the API Config Reference.