{"id":22021821,"url":"https://github.com/foo-software/lighthouse-persist","last_synced_at":"2025-05-07T06:42:39.370Z","repository":{"id":34923768,"uuid":"190816613","full_name":"foo-software/lighthouse-persist","owner":"foo-software","description":"Uploads a Lighthouse report to your AWS S3 account.","archived":false,"fork":false,"pushed_at":"2024-05-07T22:29:50.000Z","size":1887,"stargazers_count":13,"open_issues_count":5,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-05T23:55:31.711Z","etag":null,"topics":["accessibility","best-practices","lighthouse","lighthouse-audits","npm","performance","progressive-web-app","s3","seo"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/foo-software.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-07T22:16:02.000Z","updated_at":"2025-04-04T19:10:21.000Z","dependencies_parsed_at":"2024-05-07T23:26:42.734Z","dependency_job_id":null,"html_url":"https://github.com/foo-software/lighthouse-persist","commit_stats":{"total_commits":155,"total_committers":2,"mean_commits":77.5,"dds":"0.012903225806451646","last_synced_commit":"e3c9b9e6363cff9db0b3910e4941415315c3a721"},"previous_names":[],"tags_count":53,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foo-software%2Flighthouse-persist","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foo-software%2Flighthouse-persist/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foo-software%2Flighthouse-persist/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foo-software%2Flighthouse-persist/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/foo-software","download_url":"https://codeload.github.com/foo-software/lighthouse-persist/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252831098,"owners_count":21810777,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accessibility","best-practices","lighthouse","lighthouse-audits","npm","performance","progressive-web-app","s3","seo"],"created_at":"2024-11-30T06:15:23.700Z","updated_at":"2025-05-07T06:42:39.358Z","avatar_url":"https://github.com/foo-software.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `@foo-software/lighthouse-persist`\n\n\u003e 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.\n\n\u003cimg src=\"https://s3.amazonaws.com/foo.software/images/marketing/screenshots/lighthouse-audit-report.png\" /\u003e\n\nSee a full [example report here](https://s3.amazonaws.com/foo-software-html/lighthouse-report-example.html). This HTML report is generated by `lighthouse`.\n\n## What it Does\n\n- Defines the `output` [option](https://github.com/GoogleChrome/lighthouse#cli-options) as `html`.\n- Runs all Lighthouse audits - Performance, SEO, progressive web app, best practices. Parameters support custom Lighthouse options and configuration.\n- 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.\n- Exposes the result similar to that of using `lighthouse` directly.\n- Uses the latest major version of Lighthouse under the hood.\n\n## Install\n\n```bash\nnpm install @foo-software/lighthouse-persist\n```\n\n## Usage\n\nBelow are a few standard ways of using this module. See [parametes](#parameters) and [response payload](#response-payload) for more details.\n\nNote: to import in an ES Module enabled environment, you'll need to do something like this until we export an ES Module distribution:\n\n```javascript\nimport lighthousePersistPackage from '@foo-software/lighthouse-persist';\nconst { lighthousePersist } = lighthousePersistPackage;\n```\n\n## Save Report to Local Directory.\n\n```javascript\nconst path = require('path');\nconst { lighthousePersist } = require('@foo-software/lighthouse-persist');\n\n(async () =\u003e {\n  const { localReport, result } = await lighthousePersist({\n    url: 'https://www.foo.software',\n\n    // example if you have an \"artifacts\" directory in your root directory\n    outputDirectory: path.resolve('./artifacts')\n  });\n\n  console.log({ localReport, result });\n})();\n```\n\n## Upload Report to S3\n\n```javascript\nconst { lighthousePersist } = require('@foo-software/lighthouse-persist');\n\n(async () =\u003e {\n  const { report, result } = await lighthousePersist({\n    url: 'https://www.foo.software',\n    awsAccessKeyId: 'abc123',\n    awsBucket: 'myBucket',\n    awsRegion: 'us-east-1',\n    awsSecretAccessKey: 'def456'\n  });\n\n  console.log({ report, result });\n})();\n```\n\n## Run Lighthouse with PageSpeed Insights API\n\nThere are a few benefits of running Lighthouse via [PageSpeed Insights API](https://developers.google.com/speed/docs/insights/rest/v5/pagespeedapi/runpagespeed).\n\n1. Offload resource consumption to Google 🙌! If you haven't noticed [Lighthouse memory and CPU consumption is expensive](https://github.com/GoogleChrome/lighthouse/issues/11343).\n2. Get consistent results by running Lighthouse in a stable, consistent environment.\n3. Get additional data like `loadingExperience` and `originLoadingExperience` from the [CrUX API](https://web.dev/chrome-ux-report-api/) (under the hood).\n\nThe 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`.\n\nThis 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`.\n\n```javascript\nconst lighthousePersist = require('@foo-software/lighthouse-persist').default;\n\n(async () =\u003e {\n  const { loadingExperience, report, result } = await lighthousePersist({\n    url: 'https://www.foo.software',\n    awsAccessKeyId: 'abc123',\n    awsBucket: 'myBucket',\n    awsRegion: 'us-east-1',\n    awsSecretAccessKey: 'def456',\n    psiKey: 'ghi789',\n  });\n\n  console.log({ loadingExperience, report, result });\n})();\n```\n\n## Parameters\n\nThere are two different ways to persist reports. Both ways have required params. Using both is also supported. The `url` param is required always.\n\n1. Saving reports in a local directory requires the `outputDirectory` param.\n2. Uploading reports to S3 requires `awsAccessKeyId`, `awsBucket`, `awsRegion`, and `awsSecretAccessKey` params.\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003cth\u003eName\u003c/th\u003e\n    \u003cth\u003eDescription\u003c/th\u003e\n    \u003cth\u003eType\u003c/th\u003e\n    \u003cth\u003eDefault\u003c/th\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eawsAccessKeyId\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eThe AWS \u003ccode\u003eaccessKeyId\u003c/code\u003e for an S3 bucket.\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003eundefined\u003c/code\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eawsBucket\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eThe AWS \u003ccode\u003eBucket\u003c/code\u003e for an S3 bucket.\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003eundefined\u003c/code\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eawsRegion\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eThe AWS \u003ccode\u003eregion\u003c/code\u003e for an S3 bucket.\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003eundefined\u003c/code\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eawsSecretAccessKey\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eThe AWS \u003ccode\u003esecretAccessKey\u003c/code\u003e for an S3 bucket.\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003eundefined\u003c/code\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003econfig\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eThe \u003ca href=\"https://github.com/GoogleChrome/lighthouse/blob/master/docs/configuration.md\"\u003eLighthouse configuration\u003c/a\u003e.\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003eobject\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eThe default config should align with Chrome DevTools. See the \u003ca href=\"src/config.js\"\u003eexact default config here\u003c/a\u003e or \u003ca href=\"src/__snapshots__/config.test.js.snap\"\u003esnapshot here\u003c/a\u003e.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003efinalScreenshotAwsBucket\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eThe AWS \u003ccode\u003eBucket\u003c/code\u003e for an S3 bucket. If this is defined, the final screenshot will be uploaded here\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003eundefined\u003c/code\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eoptions\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eThe \u003ca href=\"https://github.com/GoogleChrome/lighthouse/tree/master/docs#differences-from-cli-flags\"\u003eLighthouse programmatic options\u003c/a\u003e, similar to the CLI.\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003eobject\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eSee the \u003ca href=\"src/options.js\"\u003eexact default options here\u003c/a\u003e or \u003ca href=\"src/__snapshots__/options.test.js.snap\"\u003esnapshot here\u003c/a\u003e.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eoutputDirectory\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eAn absolute directory path to output report. You can do this an an alternative or combined with an S3 upload.\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003eundefined\u003c/code\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003epsiKey\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eTo run Lighthouse via PageSpeed Insights API, provide your API key. \u003cstrong\u003eWARNING\u003c/strong\u003e: some Lighthouse options are not available with PageSpeed Insights (example: \u003ccode\u003eextraHeaders\u003c/code\u003e). \u003ccode\u003estrategy\u003c/code\u003e will be derived from \u003ccode\u003econfig.settings.emulatedFormFactor\u003c/code\u003e and defaults to \u003ccode\u003emobile\u003c/code\u003e.\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003eundefined\u003c/code\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eurl\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eThe URL to run audits against.\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003eundefined\u003c/code\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## Response Payload\n\nThe result of calling the default function with the parameters above is an object with the below properties.\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003cth\u003eName\u003c/th\u003e\n    \u003cth\u003eDescription\u003c/th\u003e\n    \u003cth\u003eType\u003c/th\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003efinalScreenshot\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eA URL to the final screenshot image. This will only be defined if \u003ccode\u003efinalScreenshotAwsBucket\u003c/code\u003e parameter was.\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eloadingExperience\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eIf \u003ccode\u003epsiKey\u003c/code\u003e was specified and the PageSpeed Insights response includes \u003ccode\u003eloadingExperience\u003c/code\u003e as documented, then this will be populated with an object per the shape described in the \u003ca href=\"https://developers.google.com/speed/docs/insights/rest/v5/pagespeedapi/runpagespeed#response-body\"\u003edocumentation\u003c/a\u003e. It's possible this data will not exist for some URLs. Read more about the \u003ca href=\"https://web.dev/chrome-ux-report-api/\"\u003eCrUX API\u003c/a\u003e.\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003eobject\u003c/code\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003elocalReport\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eA local path to the report (if applicable).\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eresult\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eA comprehensive result - the equivalent of what is returned when using the \u003ccode\u003elighthouse\u003c/code\u003e module directly.\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003eobject\u003c/code\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eoriginLoadingExperience\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eIf \u003ccode\u003epsiKey\u003c/code\u003e was specified and the PageSpeed Insights response includes \u003ccode\u003eoriginLoadingExperience\u003c/code\u003e as documented, then this will be populated with an object per the shape described in the \u003ca href=\"https://developers.google.com/speed/docs/insights/rest/v5/pagespeedapi/runpagespeed#response-body\"\u003edocumentation\u003c/a\u003e. It's possible this data will not exist for some URLs. Read more about the \u003ca href=\"https://web.dev/chrome-ux-report-api/\"\u003eCrUX API\u003c/a\u003e.\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003eobject\u003c/code\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003ereport\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003eA URL to the report HTML file.\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## Taking it to Another Level\n\nIf you're interested running Lighthouse audits on your web pages automatically - check out [www.foo.software](https://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).\n\n## Credits\n\n\u003e \u003cimg src=\"https://lighthouse-check.s3.amazonaws.com/images/logo-simple-blue-light-512.png\" width=\"100\" height=\"100\" align=\"left\" /\u003e This package was brought to you by [Foo - a website quality monitoring tool](https://www.foo.software). 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!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoo-software%2Flighthouse-persist","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffoo-software%2Flighthouse-persist","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoo-software%2Flighthouse-persist/lists"}