Noncollinear Perpendicular Microcrystalline
    Have ideas to improve npm?Join in the discussion! »

    @foo-software/lighthouse-persist

    2.0.0 • Public • Published

    @foo-software/lighthouse-persist

    A tool for persisting Lighthouse audit results for website monitoring and analysis. Performance, SEO, progressive web app, best practices are exposed in a results object and included in an HTML report. Save reports locally or upload to your AWS S3 bucket.

    See a full example report here. This HTML report is generated by lighthouse.

    What it Does

    • Defines the output option as html.
    • Runs all Lighthouse audits - Performance, SEO, progressive web app, best practices. Parameters support custom Lighthouse options and configuration.
    • Extracts content of the HTML report, populates it in a file and saves locally and / or uploads to the AWS S3 bucket specified by parameters.
    • Exposes the result similar to that of using lighthouse directly.
    • Uses the latest major version of Lighthouse under the hood.

    Install

    npm install @foo-software/lighthouse-persist

    Usage

    Below are a few standard ways of using this module. See parametes and response payload for more details.

    Save Report to Local Directory.

    const path = require('path');
    const lighthousePersist = require('@foo-software/lighthouse-persist').default;
    
    (async () => {
      const { localReport, result } = await lighthousePersist({
        url: 'https://www.foo.software',
    
        // example if you have an "artifacts" directory in your root directory
        outputDirectory: path.resolve('./artifacts')
      });
    
      console.log({ localReport, result });
    })();

    Upload Report to S3

    const lighthousePersist = require('@foo-software/lighthouse-persist').default;
    
    (async () => {
      const { report, result } = await lighthousePersist({
        url: 'https://www.foo.software',
        awsAccessKeyId: 'abc123',
        awsBucket: 'myBucket',
        awsRegion: 'us-east-1',
        awsSecretAccessKey: 'def456'
      });
    
      console.log({ report, result });
    })();

    Run Lighthouse with PageSpeed Insights API

    There are a few benefits of running Lighthouse via PageSpeed Insights API.

    1. Offload resource consumption to Google 🙌! If you haven't noticed Lighthouse memory and CPU consumption is expensive.
    2. Get consistent results by running Lighthouse in a stable, consistent environment.
    3. Get additional data like loadingExperience and originLoadingExperience from the CrUX API (under the hood).

    The downside is that you won't have all the configuration options by not using Lighthouse directly, like specific network settings and extraHeaders. But in most cases, the default settings are all you need. You can still target mobile or desktop via strategy. If using @foo-software/lighthouse-persist strategy will be derived from config.settings.emulatedFormFactor and defaults to mobile.

    This module will get results from PageSpeed Insights API, and generate an HTML report (optionally), and provide the result consistently with the other examples. The only mandatory parameter to run with PageSpeed Insights API is psiKey.

    const lighthousePersist = require('@foo-software/lighthouse-persist').default;
    
    (async () => {
      const { loadingExperience, report, result } = await lighthousePersist({
        url: 'https://www.foo.software',
        awsAccessKeyId: 'abc123',
        awsBucket: 'myBucket',
        awsRegion: 'us-east-1',
        awsSecretAccessKey: 'def456',
        psiKey: 'ghi789',
      });
    
      console.log({ loadingExperience, report, result });
    })();

    Parameters

    There are two different ways to persist reports. Both ways have required params. Using both is also supported. The url param is required always.

    1. Saving reports in a local directory requires the outputDirectory param.
    2. Uploading reports to S3 requires awsAccessKeyId, awsBucket, awsRegion, and awsSecretAccessKey params.
    Name Description Type Default
    awsAccessKeyId The AWS accessKeyId for an S3 bucket. string undefined
    awsBucket The AWS Bucket for an S3 bucket. string undefined
    awsRegion The AWS region for an S3 bucket. string undefined
    awsSecretAccessKey The AWS secretAccessKey for an S3 bucket. string undefined
    config The Lighthouse configuration. object The default config should align with Chrome DevTools. See the exact default config here or snapshot here.
    finalScreenshotAwsBucket The AWS Bucket for an S3 bucket. If this is defined, the final screenshot will be uploaded here string undefined
    options The Lighthouse programmatic options, similar to the CLI. object See the exact default options here or snapshot here.
    outputDirectory An absolute directory path to output report. You can do this an an alternative or combined with an S3 upload. string undefined
    psiKey To run Lighthouse via PageSpeed Insights API, provide your API key. WARNING: some Lighthouse options are not available with PageSpeed Insights (example: extraHeaders). strategy will be derived from config.settings.emulatedFormFactor and defaults to mobile. string undefined
    url The URL to run audits against. string undefined

    Response Payload

    The result of calling the default function with the parameters above is an object with the below properties.

    Name Description Type
    finalScreenshot A URL to the final screenshot image. This will only be defined if finalScreenshotAwsBucket parameter was. string
    loadingExperience If psiKey was specified and the PageSpeed Insights response includes loadingExperience as documented, then this will be populated with an object per the shape described in the documentation. It's possible this data will not exist for some URLs. Read more about the CrUX API. object
    localReport A local path to the report (if applicable). string
    result A comprehensive result - the equivalent of what is returned when using the lighthouse module directly. object
    originLoadingExperience If psiKey was specified and the PageSpeed Insights response includes originLoadingExperience as documented, then this will be populated with an object per the shape described in the documentation. It's possible this data will not exist for some URLs. Read more about the CrUX API. object
    report A URL to the report HTML file. string

    Taking it to Another Level

    If you're interested running Lighthouse audits on your web pages automatically - check out www.foo.software. Foo runs audits automatically, stores results and provides charts in a timeline view. You can also trigger runs via Foo's public REST API and tag (with a build number for example).

    Credits

    This package was brought to you by Foo - a website quality monitoring tool. Automatically test and monitor website performance, SEO and accessibility with Lighthouse. Analyze historical records of Lighthouse tests with automated monitoring. Report with confidence about SEO and performance improvements to stay on top of changes when they happen!

    Install

    npm i @foo-software/lighthouse-persist

    DownloadsWeekly Downloads

    640

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    43 kB

    Total Files

    28

    Last publish

    Collaborators

    • avatar