docs(plugins): update plugin developer docs wrt NODE_PATH

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 page information 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.

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
 

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}'`;
+  const 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 = {

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-"', () => {