From 138bf974d92cd83fd43f0f5176a5a8a519393f86 Mon Sep 17 00:00:00 2001 From: Paul Irish Date: Mon, 25 Nov 2019 15:06:19 -0800 Subject: [PATCH 1/2] docs(plugins): update plugin developer docs --- docs/plugins.md | 8 +++-- .../lighthouse-plugin-example/readme.md | 31 ++++++++++++------- lighthouse-core/config/config-helpers.js | 14 +++++---- 3 files changed, 33 insertions(+), 20 deletions(-) diff --git a/docs/plugins.md b/docs/plugins.md index 50408afc7912..cc77b61e19e9 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -51,7 +51,7 @@ To see a fully functioning example, see our [plugin recipe](./recipes/lighthouse #### `package.json` -A Lighthouse plugin is just a node module with a name that starts with `lighthouse-plugin-`. Any dependencies you need are up to you. However, do not depend on Lighthouse directly, use [`peerDependencies`](http://npm.github.io/using-pkgs-docs/package-json/types/peerdependencies.html) to alert dependants, and `devDependencies` for your own local development: +A Lighthouse plugin is just a node module with a name that starts with `lighthouse-plugin-`. Any dependencies you need are up to you. However, do not depend on Lighthouse directly, use [`peerDependencies`](http://npm.github.io/using-pkgs-docs/package-json/types/peerdependencies.html) to alert dependents, and `devDependencies` for your own local development: **Example `package.json`** @@ -136,8 +136,8 @@ module.exports = CatAudit; ```sh # be in your plugin directory, and have lighthouse as a devDependency. -NODE_ENV=.. yarn lighthouse https://example.com --plugins=lighthouse-plugin-example --only-categories=lighthouse-plugin-example --view -# Note: we set NODE_ENV to the parent directory as a hack to allow Lighthouse to find this plugin. +NODE_PATH=.. yarn lighthouse https://example.com --plugins=lighthouse-plugin-example --only-categories=lighthouse-plugin-example --view +# Note: we add the parent directory to NODE_PATH as a hack to allow Lighthouse to find this plugin. # This is useful for local development, but is not necessary when your plugin consuming from NPM as # a node module. ``` @@ -231,6 +231,8 @@ The following artifacts are available for use in the audits of Lighthouse plugin While Lighthouse has more artifacts with information about the page than are in this list, those artifacts are considered experimental and their structure or existence could change at any time. Only use artifacts not on the list above if you are comfortable living on the bleeding edge and can tolerate unannounced breaking changes. +If you're interested in other data not mentioned here, please file an issue. We'd love to help. + #### Using Network Requests You might have noticed that a simple array of network requests is missing from the list above. The source information for network requests made by the page is actually contained in the `devtoolsLogs` artifact, which contains all the of DevTools Protocol traffic recorded during page load. The network request objects are derived from this message log at audit time. diff --git a/docs/recipes/lighthouse-plugin-example/readme.md b/docs/recipes/lighthouse-plugin-example/readme.md index 64dd7869deb1..9bfbef079458 100644 --- a/docs/recipes/lighthouse-plugin-example/readme.md +++ b/docs/recipes/lighthouse-plugin-example/readme.md @@ -5,11 +5,12 @@ - `plugin.js` - instructs Lighthouse to run the plugin's own `preload-as.js` audit; describes the new category and its details for the report - `audits/preload-as.js` - the new audit to run in addition to Lighthouse's default audits -# To develop +## To develop as a plugin developer -Run the following in an empty folder to start of with the code in this recipe: +Run the following to start of with the recipe as a template: ```sh +mkdir lighthouse-plugin-example && cd lighthouse-plugin-example curl -L https://github.com/GoogleChrome/lighthouse/archive/master.zip | tar -xzv mv lighthouse-master/docs/recipes/lighthouse-plugin-example/* ./ rm -rf lighthouse-master @@ -19,25 +20,33 @@ Install and run just your plugin: ```sh yarn -NODE_ENV=.. yarn lighthouse https://example.com --plugins=lighthouse-plugin-example --only-categories=lighthouse-plugin-example --view +NODE_PATH=.. yarn lighthouse https://example.com --plugins=lighthouse-plugin-example --only-categories=lighthouse-plugin-example --view ``` -It may also speed up development if you gather once but iterate in audit mode. +When you rename the plugin, be sure to rename its directory as well. + +### Iterating +To speed up development, you can gather once and iterate by auditing repeatedly. ```sh # Gather artifacts from the browser -yarn lighthouse https://example.com --plugins=lighthouse-plugin-example --only-categories=lighthouse-plugin-example --gather-mode +NODE_PATH=.. yarn lighthouse https://example.com --plugins=lighthouse-plugin-example --only-categories=lighthouse-plugin-example --gather-mode + # and then iterate re-running this: -yarn lighthouse https://example.com --plugins=lighthouse-plugin-example --only-categories=lighthouse-plugin-example --audit-mode --view +NODE_PATH=.. yarn lighthouse https://example.com --plugins=lighthouse-plugin-example --only-categories=lighthouse-plugin-example --audit-mode --view ``` -## To run +Finally, publish to NPM. + +## To run as a plugin user -1. Install `lighthouse` v5 or later. -2. Install the plugin as a (peer) dependency, parallel to `lighthouse`. -3. Run `npx -p lighthouse lighthouse https://example.com --plugins=lighthouse-plugin-example --view` +1. Install `lighthouse` (v5+) and the plugin `lighthouse-plugin-example`, likely as `devDependencies`. + * `npm install -D lighthouse lighthouse-plugin-example` +1. To run your private lighthouse binary, you have three options + 1. `npx --no-install lighthouse https://example.com --plugins=lighthouse-plugin-example --view` + 1. `yarn lighthouse https://example.com --plugins=lighthouse-plugin-example --view` + 1. Add an npm script calling `lighthouse` and run that. -The input to `--plugins` will be loaded from `node_modules/`. ## Result diff --git a/lighthouse-core/config/config-helpers.js b/lighthouse-core/config/config-helpers.js index fdff4420f79c..87f12472a86c 100644 --- a/lighthouse-core/config/config-helpers.js +++ b/lighthouse-core/config/config-helpers.js @@ -183,13 +183,14 @@ function resolveModule(moduleIdentifier, configDir, category) { return require.resolve(cwdPath); } catch (e) {} - const errorString = - 'Unable to locate ' + - (category ? `${category}: ` : '') + - `${moduleIdentifier} (tried to require() from '${__dirname}' and load from '${cwdPath}'`; + let errorString = 'Unable to locate ' + (category ? `${category}: ` : '') + + `\`${moduleIdentifier}\`. + Tried to require() from these locations: + ${__dirname} + ${cwdPath}`; if (!configDir) { - throw new Error(errorString + ')'); + throw new Error(errorString); } // Finally, try looking up relative to the config file path. Just like the @@ -200,7 +201,8 @@ function resolveModule(moduleIdentifier, configDir, category) { return require.resolve(relativePath); } catch (requireError) {} - throw new Error(errorString + ` and '${relativePath}')`); + throw new Error(errorString + ` + ${relativePath}`); } module.exports = { From 26c5a0135a3fc1d3bc125aef19525057c88797c6 Mon Sep 17 00:00:00 2001 From: Paul Irish Date: Tue, 3 Dec 2019 12:35:21 -0800 Subject: [PATCH 2/2] CI and patrick feedback --- docs/plugins.md | 2 +- lighthouse-core/config/config-helpers.js | 2 +- lighthouse-core/test/config/config-test.js | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/plugins.md b/docs/plugins.md index cc77b61e19e9..a8f5eba1868e 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -231,7 +231,7 @@ The following artifacts are available for use in the audits of Lighthouse plugin While Lighthouse has more artifacts with information about the page than are in this list, those artifacts are considered experimental and their structure or existence could change at any time. Only use artifacts not on the list above if you are comfortable living on the bleeding edge and can tolerate unannounced breaking changes. -If you're interested in other data not mentioned here, please file an issue. We'd love to help. +If you're interested in other page information not mentioned here, please file an issue. We'd love to help. #### Using Network Requests diff --git a/lighthouse-core/config/config-helpers.js b/lighthouse-core/config/config-helpers.js index 87f12472a86c..271830916055 100644 --- a/lighthouse-core/config/config-helpers.js +++ b/lighthouse-core/config/config-helpers.js @@ -183,7 +183,7 @@ function resolveModule(moduleIdentifier, configDir, category) { return require.resolve(cwdPath); } catch (e) {} - let errorString = 'Unable to locate ' + (category ? `${category}: ` : '') + + const errorString = 'Unable to locate ' + (category ? `${category}: ` : '') + `\`${moduleIdentifier}\`. Tried to require() from these locations: ${__dirname} diff --git a/lighthouse-core/test/config/config-test.js b/lighthouse-core/test/config/config-test.js index 5b77a44212b5..3cd86c552bbb 100644 --- a/lighthouse-core/test/config/config-test.js +++ b/lighthouse-core/test/config/config-test.js @@ -871,7 +871,7 @@ describe('Config', () => { plugins: ['lighthouse-plugin-not-a-plugin'], }; assert.throws(() => new Config(configJson, {configPath: configFixturePath}), - /^Error: Unable to locate plugin: lighthouse-plugin-not-a-plugin/); + /^Error: Unable to locate plugin: `lighthouse-plugin-not-a-plugin/); }); it('should throw if the plugin name does not begin with "lighthouse-plugin-"', () => {