{"id":13513328,"url":"https://github.com/paulirish/pwmetrics","last_synced_at":"2025-05-15T06:07:38.621Z","repository":{"id":10633156,"uuid":"66429461","full_name":"paulirish/pwmetrics","owner":"paulirish","description":"Progressive web metrics at your fingertipz","archived":false,"fork":false,"pushed_at":"2022-12-09T08:05:31.000Z","size":1459,"stargazers_count":1247,"open_issues_count":40,"forks_count":74,"subscribers_count":28,"default_branch":"master","last_synced_at":"2025-04-14T10:42:35.896Z","etag":null,"topics":["lighthouse","metrics","performance","webperf"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paulirish.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-08-24T04:22:43.000Z","updated_at":"2025-02-27T18:24:16.000Z","dependencies_parsed_at":"2023-01-11T17:54:42.764Z","dependency_job_id":null,"html_url":"https://github.com/paulirish/pwmetrics","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulirish%2Fpwmetrics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulirish%2Fpwmetrics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulirish%2Fpwmetrics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulirish%2Fpwmetrics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paulirish","download_url":"https://codeload.github.com/paulirish/pwmetrics/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254283340,"owners_count":22045140,"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":["lighthouse","metrics","performance","webperf"],"created_at":"2024-08-01T04:00:52.360Z","updated_at":"2025-05-15T06:07:38.599Z","avatar_url":"https://github.com/paulirish.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Build Tools to set up performance budget","性能","[Practical Performance (Polymer Summit 2016) - YouTube](https://goo.gl/12yvX7)","How to use?"],"sub_categories":["监控","Performance tools"],"readme":"# Deprecated\n\nIn favour of better support and many cool features of:\n- [Lighthouse CI](https://github.com/GoogleChrome/lighthouse-ci) - is a suite of tools that make continuously running, saving, retrieving, and asserting against Lighthouse results as easy as possible.\n- [Lighthouse CI Action](https://github.com/treosh/lighthouse-ci-action) - action integrates Lighthouse CI with Github Actions environment. Making it simple to see failed tests, upload results, run jobs in parallel, store secrets, and interpolate env variables.\n- [Treo.sh](https://treo.sh) - Page speed monitoring made simple.\n\n\u003ch1 align=\"center\"\u003ePWMetrics\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg title=\"Progressive web metrics\" src='https://cloud.githubusercontent.com/assets/6231516/22849188/6f84c038-f003-11e6-8990-b14f3b916e54.png' /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003eProgressive web metrics at your fingertipz. 💅\u003c/p\u003e\n\u003cp align=\"center\"\u003eCLI tool and lib to gather performance metrics via \u003ca href=\"https://github.com/GoogleChrome/lighthouse/\"\u003eLighthouse\u003c/a\u003e.\n\n![image](https://cloud.githubusercontent.com/assets/39191/19417867/7aead922-93af-11e6-88ec-917dad6e89d2.png)\n\n Documentation on these metrics in the works. If you hit bugs in the metrics collection, report at [Lighthouse issues](https://github.com/GoogleChrome/lighthouse/issues).\n [How to use article](https://medium.com/@denar90/easy-progressive-web-metrics-9afa5ed857c2)\n\n### Install [![NPM pwmetrics package](https://img.shields.io/npm/v/pwmetrics.svg)](https://npmjs.org/package/pwmetrics)\n```sh\n$ yarn global add pwmetrics\n# or\n$ yarn add --dev pwmetrics\n```\n\n\n### CLI Usage\n\n```sh\n$ pwmetrics \u003curl\u003e \u003cflags\u003e\n\npwmetrics http://example.com/\n\n# --runs=n     Does n runs (eg. 3, 5), and reports the median run's numbers.\n#              Median run selected by run with the median TTI.\npwmetrics http://example.com/ --runs=3\n\n# --json       Reports json details to stdout.\npwmetrics http://example.com/ --json\n\n# returns...\n# {runs: [{\n#   \"timings\": [\n#     {\n#       \"name\": \"First Contentful Paint\",\n#       \"value\": 289.642\n#     },\n#     {\n#       \"name\": \"Largest Contentful Paint\",\n#       \"value\": 292\n#     },\n#     ...\n\n# --output-path       File path to save results.\npwmetrics http://example.com/ --output-path='pathToFile/file.json'\n\n# --config        Provide configuration (defaults to `package.json`). See _Defining config_ below.\npwmetrics --config=pwmetrics-config.js\n\n# --submit       Submit results to Google Sheets. See _Defining submit_ below.\npwmetrics --submit\n\n# --upload       Upload Lighthouse traces to Google Drive. See _Defining upload_ below.\npwmetrics --upload\n\n# --view       View Lighthouse traces, which were uploaded to Google Drive, in DevTools. See _Defining view_ below.\npwmetrics --view\n\n##\n## CLI options useful for CI\n##\n\n# --expectations  Assert metrics results against provides values. See _Defining expectations_ below.\npwmetrics --expectations\n\n# --fail-on-error  Exit PWMetrics with an error status code after the first unfilled expectation.\npwmetrics --fail-on-error\n\n\n```\n\n### Defining config\n\n```sh\n# run pwmetrics with config in package.json\npwmetrics --config\n```\n\n`package.json`\n```\n...\n  \"pwmetrics\": {\n    \"url\": \"http://example.com/\",\n    // other configuration options\n  }\n...\n```\n\n```sh\n# run pwmetrics with config in pwmetrics-config.js\npwmetrics --config=pwmetrics-config.js\n```\n\n`pwmetrics-config.js`\n\n```js\nmodule.exports = {\n  url: 'http://example.com/',\n   // other configuration options. Read _All available configuration options_\n}\n```\n\n### All available configuration options\n\n`pwmetrics-config.js`\n\n```js\nconst METRICS = require('pwmetrics/lib/metrics');\n\nmodule.exports = {\n  url: 'http://example.com/',\n  flags: { // AKA feature flags\n    runs: 3, // number or runs\n    submit: true, // turn on submitting to Google Sheets\n    upload: true, // turn on uploading to Google Drive\n    view: true, // open uploaded traces to Google Drive in DevTools\n    expectations: true, // turn on assertion metrics results against provides values\n    json: true, // not required, set to true if you want json output\n    outputPath: 'stdout', // not required, only needed if you have specified json output, can be \"stdout\" or a path\n    chromePath: '/Applications/Google\\ Chrome\\ Canary.app/Contents/MacOS/Google\\ Chrome\\ Canary', //optional path to specific Chrome location\n    chromeFlags: '', // custom flags to pass to Chrome. For a full list of flags, see http://peter.sh/experiments/chromium-command-line-switches/.\n    // Note: pwmetrics supports all flags from Lighthouse\n    showOutput: true, // not required, set to false for pwmetrics not output any console.log messages\n    failOnError: false // not required, set to true if you want to fail the process on expectations errors\n  },\n  expectations: {\n    // these expectations values are examples, for your cases set your own\n    // it's not required to use all metrics, you can use just a few of them\n    // Read _Available metrics_ where all keys are defined\n    [METRICS.TTFCP]: {\n      warn: '\u003e=1500',\n      error: '\u003e=2000'\n    },\n    [METRICS.TTLCP]: {\n      warn: '\u003e=2000',\n      error: '\u003e=3000'\n    },\n    [METRICS.TTI]: {\n      ...\n    },\n    [METRICS.TBT]: {\n      ...\n    },\n    [METRICS.SI]: {\n      ...\n    },\n  },\n  sheets: {\n    type: 'GOOGLE_SHEETS', // sheets service type. Available types: GOOGLE_SHEETS\n    options: {\n      spreadsheetId: 'sheet_id',\n      tableName: 'data',\n      uploadMedian: false // not required, set to true if you want to upload only the median run\n    }\n  },\n  clientSecret: {\n    // Data object. Can be get\n    // either\n    // by (using everything in step 1 here)[https://developers.google.com/sheets/api/quickstart/nodejs#step_1_turn_on_the_api_name]\n    //\n    // example format:\n    //\n    // installed: {\n    //   client_id: \"sample_client_id\",\n    //   project_id: \"sample_project_id\",\n    //   auth_uri: \"https://accounts.google.com/o/oauth2/auth\",\n    //   token_uri: \"https://accounts.google.com/o/oauth2/token\",\n    //   auth_provider_x509_cert_url: \"https://www.googleapis.com/oauth2/v1/certs\",\n    //   client_secret: \"sample_client_secret\",\n    //   redirect_uris: [\n    //     \"url\",\n    //     \"http://localhost\"\n    //   ]\n    // }\n    //\n    // or\n    // by (using everything in step 1 here)[https://developers.google.com/drive/v3/web/quickstart/nodejs]\n  }\n}\n```\n\n### Defining expectations\n\n\u003e [Recipes](/recipes) for using with CI\n\n```sh\n# run pwmetrics with config in package.json\npwmetrics --expectations\n```\n\n`package.json`\n```\n...\n  \"pwmetrics\": {\n    \"url\": \"http://example.com/\",\n    \"expectations\": {\n      ...\n    }\n  }\n...\n```\n\n\n```sh\n# run pwmetrics with config in pwmetrics-config.js\npwmetrics --expectations --config=pwmetrics-config.js\n```\n\n### Defining submit\n\nSubmit results to Google Sheets\n\n*Instructions:*\n\n- Copy [this spreadsheet](https://docs.google.com/spreadsheets/d/17jgt_uKxm4WvROmKMfSDzhdCAstNvyaiDP_k2XqzgD0).\n- Copy the ID of the spreadsheet into the config as value of `sheets.options.spreadsheetId` property.\n- Setup Google Developer project and get credentials. ([everything in step 1 here](https://developers.google.com/sheets/api/quickstart/nodejs#step_1_turn_on_the_api_name))\n- Take a `client_secret` and put it into the config as value of `clientSecret` property.\n\n\n```sh\n# run pwmetrics with config in package.json\npwmetrics --submit\n```\n\n```sh\n# run pwmetrics with config in pwmetrics-config.js\npwmetrics --submit --config=pwmetrics-config.js\n```\n\n`pwmetrics-config.js`\n```js\nmodule.exports = {\n  'url': 'http://example.com/',\n  'sheets': {\n    ...\n  },\n  'clientSecret': {\n    ...\n  }\n}\n```\n\n\n### Defining upload\n\nUpload Lighthouse traces to Google Drive\n\n*Instructions:*\n\n- Setup Google Developer project and get credentials. ([everything in step 1 here](https://developers.google.com/drive/v3/web/quickstart/nodejs))\n- Take a `client_secret` and put it into the config as value of `clientSecret` property.\n\n\n```sh\n# run pwmetrics with config in package.json\npwmetrics --upload\n```\n\n```sh\n# run pwmetrics with config in pwmetrics-config.js\npwmetrics --upload --config=pwmetrics-config.js\n```\n\n`pwmetrics-config.js`\n```js\nmodule.exports = {\n  'url': 'http://example.com/',\n  'clientSecret': {\n    ...\n  }\n}\n```\n\n### View Lighthouse traces in timeline-viewer\n\nShow Lighthouse traces in timeline-viewer.\n\n\u003e Required to use `upload` flag\n\n[timeline-viewer](https://chromedevtools.github.io/timeline-viewer/) - Shareable URLs for your Chrome DevTools Timeline traces.\n\n\n```sh\n# run pwmetrics with config in package.json\npwmetrics --upload --view\n```\n\n\n```sh\n# run pwmetrics with config in your-own-file.js\npwmetrics --upload --view --config=your-own-file.js\n```\n\n`pwmetrics-config.js`\n```js\nmodule.exports = {\n  'url': 'http://example.com/',\n  'clientSecret': {\n    ...\n  }\n}\n```\n\n#### Available metrics:\n\nAll metrics now are stored in separate constant object located in `pwmetrics/lib/metrics/metrics`;\n\n```js\n// lib/metrics/metrics.ts\n{\n  METRICS: {\n    TTFCP: 'firstContentfulPaint',\n    TTLCP: 'largestContentfulPaint',\n    TBT: 'totalBlockingTime',\n    TTI: 'interactive',\n    SI: 'speedIndex'\n  }\n}\n```\n\nRead article [Performance metrics. What’s this all about?](https://medium.com/@denar90/performance-metrics-whats-this-all-about-1128461ad6b) which is decoding this metrics.\n\n### API\n\n```js\nconst PWMetrics = require('pwmetrics');\n\nconst options = {\n  flags: {\n    runs: 3, // number or runs\n    submit: true, // turn on submitting to Google Sheets\n    upload: true, // turn on uploading to Google Drive\n    view: true, // open uploaded traces to Google Drive in DevTools\n    expectations: true, // turn on assertation metrics results against provides values\n    chromeFlags: '--headless' // run in headless Chrome\n  }\n};\n\nconst pwMetrics = new PWMetrics('http://example.com/', options); // _All available configuration options_ can be used as `options`\npwMetrics.start(); // returns Promise\n\n```\n\n#### Options\n\n\u003ctable class=\"table\" width=\"100%\"\u003e\n  \u003cthead\u003e\n    \u003ctr\u003e\n      \u003cth width=\"10%\"\u003eOption\u003c/th\u003e\n      \u003cth width=\"15%\"\u003eType\u003c/th\u003e\n      \u003cth width=\"40%\"\u003eDefault\u003c/th\u003e\n      \u003cth width=\"25%\"\u003eDescription\u003c/th\u003e\n    \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n    \u003ctd style=\"text-align: center;\"\u003eflags\u003csup\u003e\u003cb\u003e*\u003c/b\u003e\u003c/sup\u003e\u003c/td\u003e\n      \u003ctd style=\"text-align: center;\"\u003eObject\u003c/td\u003e\n      \u003ctd\u003e\n        \u003cpre\u003e\n{\n  runs: 1,\n  submit: false,\n  upload: false,\n  view: false,\n  expectations: false,\n  disableCpuThrottling: false,\n  chromeFlags: ''\n}\n        \u003c/pre\u003e\n      \u003c/td\u003e\n      \u003ctd\u003eFeature flags\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd style=\"text-align: center;\"\u003eexpectations\u003c/td\u003e\n      \u003ctd style=\"text-align: center;\"\u003eObject\u003c/td\u003e\n      \u003ctd style=\"text-align: center;\"\u003e{}\u003c/td\u003e\n      \u003ctd\u003eSee \u003ca href=\"#defining-expectations\"\u003eDefining expectations\u003c/a\u003e above.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd style=\"text-align: center;\"\u003esheets\u003c/td\u003e\n      \u003ctd style=\"text-align: center;\"\u003eObject\u003c/td\u003e\n      \u003ctd style=\"text-align: center;\"\u003e{}\u003c/td\u003e\n      \u003ctd\u003eSee \u003ca href=\"#defining-submit\"\u003eDefining submit\u003c/a\u003e above.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd style=\"text-align: center;\"\u003eclientSecret\u003c/td\u003e\n      \u003ctd style=\"text-align: center;\"\u003eObject\u003c/td\u003e\n      \u003ctd style=\"text-align: center;\"\u003e{}\u003c/td\u003e\n      \u003ctd\u003e\n        Client secrete data generated by Google API console.\n        To setup Google Developer project and get credentials apply \u003ca href=\"https://developers.google.com/drive/v3/web/quickstart/nodejs\"\u003eeverything in step 1 here\u003c/a\u003e.\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003csup\u003e*\u003c/sup\u003epwmetrics supports all flags from Lighthouse. See [here](https://github.com/GoogleChrome/lighthouse/#cli-options) for the complete list.\n\n\n### Recipes\n\n- [gulp](/recipes/gulp/gulpfile.js)\n\n\n### License\n\nApache 2.0. Google Inc.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulirish%2Fpwmetrics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaulirish%2Fpwmetrics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulirish%2Fpwmetrics/lists"}