npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@code-pushup/lighthouse-plugin

v0.53.1

Published

Code PushUp plugin for measuring web performance and quality with Lighthouse 🔥

Downloads

489

Readme

@code-pushup/lighthouse-plugin

npm downloads dependencies

🕵️ Code PushUp plugin for measuring web performance and quality with Lighthouse. 🔥


The plugin parses your Lighthouse configuration and lints all audits of the official Lighthouse CLI.

Detected Lighthouse audits are mapped to Code PushUp audits. Audit reports are calculated based on the original implementation. Additionally, Lighthouse categories are mapped to Code PushUp groups which can make it easier to assemble the categories.

For more infos visit the official docs.

Getting started

  1. If you haven't already, install @code-pushup/cli and create a configuration file.

  2. Install as a dev dependency with your package manager:

    npm install --save-dev @code-pushup/lighthouse-plugin
    yarn add --dev @code-pushup/lighthouse-plugin
    pnpm add --save-dev @code-pushup/lighthouse-plugin
  3. Add this plugin to the plugins array in your Code PushUp CLI config file (e.g. code-pushup.config.ts).

    Pass in the URL you want to measure, along with optional flags and config data.

    import lighthousePlugin from '@code-pushup/lighthouse-plugin';
    
    export default {
      // ...
      plugins: [
        // ...
        await lighthousePlugin('https://example.com'),
      ],
    };
  4. Run the CLI with npx code-pushup collect and view or upload the report (refer to CLI docs).

Optionally set up categories

Reference audits (or groups) which you wish to include in custom categories (use npx code-pushup print-config --onlyPlugins=lighthouse to list audits and groups).

Assign weights based on what influence each Lighthouse audit has on the overall category score (assign weight 0 to only include as extra info, without influencing category score). The plugin exports the helper lighthouseAuditRef and lighthouseGroupRef to reference Lighthouse category references for audits and groups.

Reference audits directly with lighthouseGroupRef

import { lighthouseGroupRef } from './utils';

export default {
  // ...
  categories: [
    {
      slug: 'performance',
      title: 'Performance',
      refs: [lighthouseGroupRef('performance')],
    },
    {
      slug: 'a11y',
      title: 'Accessibility',
      refs: [lighthouseGroupRef('accessibility')],
    },
    {
      slug: 'best-practices',
      title: 'Best Practices',
      refs: [lighthouseGroupRef('best-practices')],
    },
    {
      slug: 'seo',
      title: 'SEO',
      refs: [lighthouseGroupRef('seo')],
    },
    {
      slug: 'pwa',
      title: 'PWA',
      isBinary: true,
      refs: [lighthouseGroupRef('pwa')],
    },
  ],
};

Reference groups with lighthouseAuditRef

The Lighthouse categories are reflected as groups. Referencing individual audits offers more granularity. However, keep maintenance costs of a higher number of audits in mind as well.

import { lighthouseAuditRef } from './utils';

export default {
  // ...
  categories: [
    {
      slug: 'pwa',
      title: 'PWA',
      isBinary: true,
      refs: [lighthouseAuditRef('installable-manifest', 2), lighthouseAuditRef('splash-screen', 1), lighthouseAuditRef('themed-omnibox', 1), lighthouseAuditRef('content-width', 1), lighthouseAuditRef('themed-omnibox', 2), lighthouseAuditRef('viewport', 2), lighthouseAuditRef('maskable-icon', 1), lighthouseAuditRef('pwa-cross-browser', 0), lighthouseAuditRef('pwa-page-transitions', 0), lighthouseAuditRef('pwa-each-page-has-url', 0)],
    },
  ],
};

Flags

The plugin accepts an optional second argument, flags.

flags is a JavaScript object containing Lighthouse CLI flags.

Within the flags object, external configuration files can be referenced using options like configPath , preset, or budgetPath. These options allow Lighthouse to load custom configurations, audit presets, or performance budgets from external json or JavaScript files.

For a complete list of available options, refer to the official Lighthouse documentation.

[!TIP]
If you are new to working with the Lighthouse CLI, flags can be passed like this: lighthouse https://example.com --output=json --chromeFlags='--headless=shell'

With the plugin, the configuration would be:

// code-pushup.config.ts
...
lighthousePlugin('https://example.com', {
  output: 'json',
  chromeFlags: ['--headless=shell'],
});

[!note] The following flags are not supported in the current implementation:

  • list-all-audits - Prints a list of all available audits and exits. Alternative: npx code-pushup print-config --onlyPlugins lighthouse
  • list-locales - Prints a list of all supported locales and exits.
  • list-trace-categories - Prints a list of all required trace categories and exits.
  • view - Open HTML report in your browser

Chrome Flags for Tooling

We recommend using Chrome flags for more stable runs in a tooling environment. The chrome-launcher package offers a well-documented set of flags specifically designed to ensure reliable execution.

The latest version of @code-pushup/lighthouse-plugin provides DEFAULT_CHROME_FLAGS, a pre-configured constant that includes Chrome’s default flags for stable, headless execution out of the box. This means you do not need to specify chromeFlags manually unless you want to modify them.

Default Usage

If no chromeFlags are provided, the plugin automatically applies the default configuration:

import lighthousePlugin from '@code-pushup/lighthouse-plugin';

lighthousePlugin('https://example.com', {
  output: 'json',
  // Defaults to DEFAULT_CHROME_FLAGS internally
});

Adding Extra Flags

If additional Chrome flags are required (e.g., verbose logging or debugging), they can be appended to the default flags:

import lighthousePlugin, { DEFAULT_CHROME_FLAGS } from '@code-pushup/lighthouse-plugin';

lighthousePlugin('https://example.com', {
  output: 'json',
  chromeFlags: DEFAULT_CHROME_FLAGS.concat(['--verbose']),
});

Overriding Default Flags

To completely override the default flags and provide a custom configuration:

import lighthousePlugin from '@code-pushup/lighthouse-plugin';

lighthousePlugin('https://example.com', {
  output: 'json',
  chromeFlags: ['--verbose'],
});

Config

The plugin accepts a third optional argument, config.

config is the Lighthouse configuration as a JS object.

For a complete guide on Lighthouse configuration read the official documentation on configuring

[!TIP]
If you are not used to work with the Lighthouse CLI you would pass a config like this: lighthouse --config-path=path/to/custom-config.js https://example.com

And in a separate file you would place the following object:

// custom-config.js file
export default {
  extends: 'lighthouse:default',
  settings: {
    onlyAudits: ['first-meaningful-paint', 'speed-index', 'interactive'],
  },
};

Now with the plugin it would look like this:

// code-pushup.config.ts
...
lighthousePlugin('https://example.com', undefined, {
  extends: 'lighthouse:default',
  settings: {
    onlyAudits: [
      'first-meaningful-paint',
      'speed-index',
      'interactive',
     ],
 }
})

If you want to contribute, please refer to CONTRIBUTING.md.