Config #

Configuring Unlighthouse #

There are multiple ways to configure Unlighthouse. See the configuration documentation for your implementation.

• Config file - unlighthouse.config.ts
• CLI arguments
• Nuxt module options
• webpack plugin options
• Vite plugin options

Root Options #

site #

• Type: string

The site that will be scanned.

root #

• Type: string
• Default: cwd()

The path that we'll be performing the scan from, this should be the path to the app that represents the site. Using this path we can auto-discover the provider

cache #

• Type: boolean
• Default: true

Should reports be saved to the local file system and re-used between runs for the scanned site.

Note: This makes use of cache-bursting for when the configuration changes, since this may change the report output.

configFile #

• Type: string|null
• Default: null

Load the configuration from a custom config file. By default, it attempts to load configuration from unlighthouse.config.ts.

You can set up multiple configuration files for different sites you want to scan. For example:

• staging-unlighthouse.config.ts
• production-unlighthouse.config.ts

outputPath #

• Type: string
• Default: ./lighthouse/

Where to emit lighthouse reports and the runtime client.

debug #

• Type: boolean
• Default: false

Display the loggers' debug messages.

hooks #

• Type: NestedHooks<UnlighthouseHooks>
• Default: {}

Hooks to run. See the Hooks section for more information.

routerPrefix #

• Type: string
• Default: ''

The URL path prefix for the client and API to run from. Useful when you want to serve the application from an existing integrations server.

For example, you could run Unlighthouse from /__unlighthouse .

export default {
  routerPrefix: '/__unlighthouse'
}

apiPrefix #

• Type: string
• Default: /api/

The path that the API should be served from.

urls #

• Type: string[]|(() => string[])|(() => Promise<string[]>)
• Default: []

Provide a list of URLs that should be used explicitly. Will disable sitemap and crawler.

See Manually Providing URLs.

CI Options #

Change the behaviour of unlighthouse in CI mode.

ci.budget #

• Type: number|Record<Partial<LighthouseCategories>, number>
• Default: null

Provide a budget for each page as a numeric total score, or an object mapping the category to the score. Should be a number between 1-100.

For example, if you wanted to make sure all of your pages met a specific accessibility score, you could do:

export default {
  ci: {
    budget: {
      accessibility: 90
    }
  },
}

ci.buildStatic #

• Type: boolean
• Default: false

Injects the required data into the client files, so it can be hosted statically.

Combine this with uploading to a site, and you can see the results of your unlighthouse scan on a live site.

Client Options #

See Modifying client for more information.

client.columns #

• Type: Record<UnlighthouseTabs, UnlighthouseColumn[]>

Modify the default columns used on the client.

client.groupRoutesKey #

• Type: string
• Default: route.definition.name

Which key to use to group the routes.

Discovery Options #

See Route Definitions for more information.

discovery.pagesDir #

• Type: string
• Default: ./pages

The location of the page files that will be matched to the routes.

Note: This is for fallback behaviour when the integration doesn't provide a way to gather the route definitions.

discovery.supportedExtensions #

• Type: string
• Default: ['vue', 'md']

Which file extensions in the pages dir should be considered.

Scanner Options #

scanner.customSampling #

• Type: Record<string, RouteDefinition>
• Default: {}

Setup custom mappings for a regex string to a route definition. This is useful when you have a complex site which doesn't use URL path segments to separate pages.

See custom sampling for more information.

scanner.ignoreI18nPages #

• Type: boolean
• Default: true

When the page HTML is extracted and processed, we look for an x-default link to identify if the page is an i18n copy of another page. If it is, then we skip it because it would be a duplicate scan.

scanner.maxRoutes #

• Type: number|false
• Default: 200

The maximum number of routes that should be processed. This helps avoid issues when the site requires a specific configuration to be able to run properly

scanner.include #

• Type: string[]|null
• Default: null

Paths to explicitly include from the search, this will exclude any paths not listed here.

See Include URL Patterns for more information.

scanner.exclude #

• Type: string[]|null
• Default: null

Paths to ignore from scanning.

See Exclude URL Patterns for more information.

scanner.skipJavascript #

• Type: boolean
• Default: true

Does javascript need to be executed in order to fetch internal links and SEO data.

Disabling this can speed up scans but may break the parsing.

See Handling SPAs for more information.

scanner.samples #

• Type: number
• Default: 1

How many samples of each route should be done. This is used to improve false-positive results.

See Run Lighthouse Multiple Times and Improving Accuracy for more information.

scanner.throttle #

• Type: boolean
• Default: true

Should lighthouse run with throttling enabled. This is an alias for manually configuring lighthouse.

Note: This will be disabled by default for local scans.

See Toggling Throttling for more information.

scanner.crawler #

• Type: boolean
• Default: true

Should the crawler be used to detect URLs. This will parse the HTML of scanned pages for internal links and queue them for scanning.

See URL Discovery for more information.

scanner.dynamicSampling #

• Type: number|false
• Default: 5

When a route definition is provided, you're able to configure the worker to sample the dynamic routes to avoid redundant route reports.

See Change Dynamic Sampling Limit for more information.

scanner.sitemap #

• Type: boolean
• Default: true

Whether the sitemap.xml will be attempted to be read from the site.

scanner.device #

• Type: boolean
• Default: mobile

Alias to switch the device used for scanning. Set to false if you want to manually configure it.

See Switching between mobile and desktop for more information.

Lighthouse Options #

Changes the default behaviour of Google Lighthouse.

See Configure Google Lighthouse for more information.

Puppeteer Options #

Change the behaviour of puppeteer.

See puppeteer.connect(options) for all available configurations.

Puppeteer Cluster Options #

Change the behaviour of puppeteer-cluster.

By default the concurrency will be set on the CPU cores you have available.

See Cluster.launch(options) for available configuration.