Each integration comes with a way to configure Unlighthouse inline; however, you may want to create a separate configuration file when dealing with complex sites.

Configuration file

By default, a unlighthouse.config.ts file within the root (or cwd) directory will be read. You can change the name of the configuration file with the configFile option, or --config flag for the CLI.

Local dependency - with Typescript

When you load Unlighthouse into your project as a dev dependency and you're using Typescript, you can make use of proper configuration types.

/// <reference types="unlighthouse" />import {defineConfig} from 'unlighthouse'export default defineConfig({  // example  site: '',  scanner: {    exclude: ['/private-zone/*']  },  debug: true,})

Global dependency

You can still provide a configuration file when using Unlighthouse globally, however, you won't be able to make use of the types or defineConfig function, instead you'll need to export a plain object.

export default {  // example  site: '',  scanner: {    exclude: ['/private-zone/*']  },  debug: true,}

See the list of config options in the Config Reference.


export default {  site: '',  scanner: {    // exclude specific routes    exclude: [      '/.*?pdf',      '.*/amp',      'en-*',    ],    // run lighthouse for each URL 3 times    samples: 3,    // use desktop to scan    device: 'desktop',    // enable the throttling mode    throttle: true,  },  debug: true,}