Skip to main content

Lighthouse

Lighthouse is a tool to audit the runtime performance and usability of your web application. Utilized as part of a Continuous Integration (CI) process, Lighthouse can help identify issues with code quality early during development. High Velocity includes an example of this.

How it Works​

The following process happens between your GitHub repository and linked Vercel project:

  1. A Github Pull Request (PR) is opened, updated, or merged
  2. Vercel runs a new build with the changes, and creates a preview deployment with a unique URL
  3. Vercel integrates with Github Deployments, notifying deployment is complete
  4. A Github Action custom workflow is triggered, running Lighthouse tests on key application pages of the newly deployed site
  5. Lighthouse attaches the full report as a Zip archive to the Github Action run details
  6. Results are tested against expectations (aka assertions) and fail the workflow if not met
  7. Upon success, results are summarized in the Github Action run
  8. If the PR is still open, the Github Action result is included as part of the PR's build checklist

Implementation​

Lighthouse CI is the core tool, along with some other libraries for compatibility with Github Actions and Vercel.

The Github Action script should be located at .github/workflows/lighthouse_audit.yml within your repo.

A Lighthouse configuration file .github/lighthouse/lighthouserc-preview.json is also needed. This contains the assertions. Please see LHCI documentation for help with syntax and options.

Setup​

Create a Vercel Token via their portal.

Create a Github Secret for your repo, named VERCEL_TOKEN and save the token value provided by Vercel.

The Github Action's job is filtered to only run for one specific preview environment, assuming a monorepo with multiple application environments. Depending on your repo and Vercel project setup, either update the filter with the correct target environment name or remove it:

if: ${{ github.event.deployment.environment == 'Preview – diego-tailwind' }}

Finally, configure the app pages to be tested by Lighthouse per your store's catalog, products, and features:

  • Update the list of relevant page URL's in the Github Action script's lighthouse_audit step input value urls: |
  • Note that ?preview param must be appended to bypass Basic Authentication for a preview build, if set -- do not share these URL's
  • Then update the Lighthouse configuration file assertions match, if using matchingUrlPattern for path specific assertions

Default Assertions​

While Lighthouse allows us to assert at a very granular level, for this example we focus on asserting the audit result categories at a high level. Please adjust to your needs.

Performance: This result category is not static and may be impacted by preview build environment lag, any additional scripts injected by Vercel for preview tooling, as well as the Github VM and hardware running the audit workflow itself. There will be variance.

  • Per Lighthouse recommendation, running 3 tests per page to take the best number

  • Assert value based on average seen across several runs, may need adjustment through development lifecycle

  • Assert initially as a warning, perhaps convert to error as application features are near complete

Accessibility: This result category is static. Assert value set to 100% and will error if not met.

Best Practices: Static result category. Assert 100% and error if not met.

SEO: Vercel returns a noindex header rule to stop preview builds from being indexed as a security practice, to prevent phishing sites and spam. Unfortunately that lowers the result score in a preview environment. Static result category. Low assert value and set to warn only.