Puppeteer Launch Options for Lighthouse Audits

Unlighthouse uses Puppeteer to control Chrome for Lighthouse audits. Configure browser behavior, navigation hooks, and Chrome flags via puppeteerOptions.

All Available Options

export default defineUnlighthouseConfig({
  puppeteerOptions: {
    // See: https://pptr.dev/api/puppeteer.launchoptions
  },
})

Full reference: Puppeteer LaunchOptions API

Common Configurations

Headless Mode

// Run with visible browser (debugging)
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    headless: false,
  },
})

Custom Chrome Executable

export default defineUnlighthouseConfig({
  puppeteerOptions: {
    executablePath: '/usr/bin/google-chrome',
  },
})

Chrome Arguments

Common args for CI/Docker environments:

export default defineUnlighthouseConfig({
  puppeteerOptions: {
    args: [
      '--no-sandbox',
      '--disable-setuid-sandbox',
      '--disable-dev-shm-usage',
      '--disable-gpu',
    ],
  },
})

Viewport Settings

export default defineUnlighthouseConfig({
  puppeteerOptions: {
    defaultViewport: {
      width: 1920,
      height: 1080,
    },
  },
})

Timeout Configuration

export default defineUnlighthouseConfig({
  puppeteerOptions: {
    timeout: 60000, // 60 seconds
  },
})

User Data Directory

Persist browser data between runs:

export default defineUnlighthouseConfig({
  puppeteerOptions: {
    userDataDir: './.puppeteer-data',
  },
})

Navigation Hooks

Hook into Puppeteer's page navigation for custom logic.

Before Page Load

export default defineUnlighthouseConfig({
  hooks: {
    'puppeteer:before-goto': async (page) => {
      // Set localStorage before navigation
      await page.evaluateOnNewDocument((token) => {
        localStorage.setItem('auth', token)
      }, process.env.AUTH_TOKEN)
    },
  },
})

Modify Page Content

export default defineUnlighthouseConfig({
  hooks: {
    'puppeteer:before-goto': async (page) => {
      page.waitForNavigation().then(async () => {
        // Remove elements that cause CLS
        await page.evaluate(() => {
          document.querySelector('.cookie-banner')?.remove()
        })
      })
    },
  },
})