docs(plugins): update recipe, suggest NODE_ENV=.. hack

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) instead:
+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:
 
 **Example `package.json`**
 
@@ -60,7 +60,10 @@ A Lighthouse plugin is just a node module with a name that starts with `lighthou
   "name": "lighthouse-plugin-cats",
   "main": "plugin.js",
   "peerDependencies": {
-    "lighthouse": "^5.0.0"
+    "lighthouse": "^5.6.0"
+  },
+  "devDependencies": {
+    "lighthouse": "^5.6.0"
   }
 }
 ```
@@ -129,6 +132,16 @@ class CatAudit extends Audit {
 module.exports = CatAudit;
 ```
 
+#### Run the plugin locally in development
+
+```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.
+# This is useful for local development, but is not necessary when your plugin consuming from NPM as
+# a node module.
+```
+
 ## API
 
 ### Plugin Config

docs/recipes/lighthouse-plugin-example/package.json

@@ -3,6 +3,9 @@
   "private": true,
   "main": "./plugin.js",
   "peerDependencies": {
-    "lighthouse": "^5.0.0"
+    "lighthouse": "^5.6.0"
+  },
+  "devDependencies": {
+    "lighthouse": "^5.6.0"
   }
 }

docs/recipes/lighthouse-plugin-example/readme.md

@@ -4,7 +4,33 @@
 - `package.json` - declares the plugin's entry point (`plugin.js`)
 - `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
+
+Run the following in an empty folder to start of with the code in this recipe:
+
+```sh
+curl -L https://github.com/GoogleChrome/lighthouse/archive/master.zip | tar -xzv
+mv lighthouse-master/docs/recipes/lighthouse-plugin-example/* ./
+rm -rf lighthouse-master
+```
+
+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
+```
+
+It may also speed up development if you gather once but iterate in audit mode.
+
+```sh
+# Gather artifacts from the browser
+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
+```
+
 ## To run
 
 1. Install `lighthouse` v5 or later.