Unlighthouse is a comprehensive tool designed to scan entire websites using Google Lighthouse, presented through a modern user interface with minimal configuration requirements and intelligent sampling.

It helps web developers and site administrators to identify and resolve performance, accessibility, and SEO issues across their entire site efficiently.

By leveraging powerful integrations and a smart, lightweight configuration process, Unlighthouse ensures a seamless user experience while preserving the accuracy and depth of the Lighthouse reports. From large-scale production sites to individual development environments, Unlighthouse offers a versatile solution to maintain and improve web quality metrics.

Running Unlighthouse on Your Site

Getting started with Unlighthouse is straightforward. The primary way to initiate a scan for your production site is through the Unlighthouse Command Line Interface (CLI). Here’s a quick setup guide:

1. Install Node.js (v18.x or later) if not already installed.

2. Run the initialization command:

   npx unlighthouse --site <your-site-url>
   # or
   pnpm dlx unlighthouse --site <your-site-url>
   

   This command sets up and runs the Unlighthouse scanner on the specified site, generating reports and providing immediate feedback on the site's performance and other key metrics.

Important Configurations

Unlighthouse provides a range of configurations to customize its behavior to better suit different use cases, environments, and site characteristics. Some of the key configurations include:

Excluding/Including URLs

Exclude Specific Routes: You can configure Unlighthouse to exclude certain paths from the scan. For example, to exclude documentation sections that do not need scanning:

export default {
  scanner: {
    exclude: ['/docs/*']
  }
}

Include Specific Routes: Similarly, you can specify which routes should be included in the scan, effectively excluding all others:

export default {
  scanner: {
    include: ['/articles/*', '/authors/*']
  }
}

Sampling Configurations

Dynamic Sampling Limit: You can set the number of times a URL will be matched to a specific route definition. This helps in improving the accuracy without unnecessary repetitive scans:

export default {
  scanner: {
    dynamicSampling: 20
  }
}

Disabling Dynamic Sampling: In some scenarios, dynamic sampling isn’t required. It can be disabled as follows:

export default {
  scanner: {
    dynamicSampling: false
  }
}

Device and Throttling Options

Unlighthouse allows configuration for the type of device and network condition simulations to better reflect the end-users' experience:

Emulating a Desktop Device: To emulate scans as if they are coming from a desktop:

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

Enable Throttling: To simulate slower network conditions, akin to a typical user's experience on a poor connection:

export default {
  scanner: {
    throttle: true
  }
}

Adjust Device Dimensions:

export default {
  lighthouseOptions: {
    screenEmulation: {
      width: 180,
      height: 100,
    }
  }
}

Advanced Puppeteer Configurations

Unlighthouse leverages Puppeteer for headless browser capabilities, which include custom configurations for unique scenarios:

Running in non-headless mode (Not recommended):

export default {
  puppeteerOptions: {
    headless: false,
  }
}

Custom Hook Example: For instance, you might need to perform actions like setting authentication tokens before page evaluations:

export default {
  hooks: {
    'puppeteer:before-goto': async (page) => {
      const token = await generateToken();
      await page.evaluateOnNewDocument((token) => {
        localStorage.setItem('token', token);
      }, token);
    },
  },
}

Through these configurations, Unlighthouse can be tailored to effectively handle a variety of site structures and requirements, providing valuable insights and facilitating enhanced site performance and user experience.

Here you can find more about Unlighthouse in the official documentation.

← Go back to the blog