docs: add plugin recipe #6965

brendankenny · 2019-01-09T19:44:31Z

broken out from #6959 ~~since not a whole lot of effort was put into making a nice instructive recipe and it was just making that PR longer :)~~

~~Not really ready for review, but completely open for suggestions to make it better and just for reference.~~

brendankenny · 2019-02-14T19:21:55Z

Updated the recipe to something better. Happy to bikeshed.

Docs will be in a separate PR.

paulirish · 2019-02-15T20:33:09Z

docs/recipes/plugin/lighthouse-plugin-preload-as/plugin-config.js

+    title: 'My Plugin Category',
+    description: 'Results for our new plugin category.',
+    auditRefs: [
+      {id: 'searchable-audit', weight: 1},


change to 'preload-as' now? (or is it preload-as-audit?)

or is it preload-as-audit

technically preload-as since that's what the audit's id is, but that's confusing, so I'll use preload-as-audit as the id :)

paulirish · 2019-02-15T20:34:58Z

docs/recipes/plugin/lighthouse-plugin-preload-as/preload-as-audit.js

+ */
+'use strict';
+
+const Audit = require('../../../../lighthouse-core/index.js').Audit;


a plugin would usually be written outside of our repo.. so wanna put the typical require path here?

a plugin would usually be written outside of our repo.. so wanna put the typical require path here?

yeah, I'll switch it. We do want it runnable (I was thinking about adding a recipes smokehouse target), but we can worry about that later

paulirish · 2019-02-15T20:35:16Z

docs/recipes/plugin/lighthouse-plugin-preload-as/plugin-config.js

+module.exports = {
+  // Additional audit to run on information Lighthouse gathered.
+  audits: [{
+    path: 'lighthouse-plugin-searchable/searchable-audit.js',


paulirish · 2019-02-15T20:35:36Z

docs/recipes/plugin/lighthouse-plugin-preload-as/package.json

+{
+  "name": "lighthouse-plugin-preload-as",
+  "private": true,
+  "main": "./plugin-config.js"


recipe-custom-config.js

recipe-custom-config.js

oh, this one is correct. The custom config is what you'd use with --config-path to run lighthouse with the plugin. The plugin's main is the actual plugin config file.

Hmmm.. weird to have two things that work together both called a config. about how index.js or plugin-index.js? plugin-dfn.js...

Hmmm.. weird to have two things that work together both called a config. about how index.js or plugin-index.js? plugin-dfn.js...

I'd actually rather have it stay as plugin-config.js and (eventually) get rid of the other one in this recipe.

Most of the time you'll either be writing a plugin or using a plugin in your config, not writing both at the same time, so it shouldn't cause confusion, and it makes sense to keep calling it a "plugin config" because it's pretty much identical to the main config except more locked down.

We need to add a --plugin cli flag, but at that point you won't need the recipe-custom-config.js file, which should clear up the confusion here.

a "plugin config" because it's pretty much identical to the main config except more locked down.

ehhh. IMO the Lighthouse concept of 'config' is very defined. And I think it'll be more confusing to use the term for two things that are similar but slightly different. It's not like our docs for plugins should say "go look at Lighthouse config, but only these parts."

Looking over at eslint plugins, they basically just call this a 'plugin'. No 'definition' or 'config' term. That sgtm. I still favor index.js but plugin.js seems ok.

but plugin.js seems ok.

sure

brendankenny · 2019-02-15T20:39:02Z

lol, amateur hour. Thanks.

brendankenny · 2019-02-16T16:57:03Z

paulirish · 2019-02-26T23:59:26Z

docs/recipes/plugin/lighthouse-plugin-preload-as/package.json

+{
+  "name": "lighthouse-plugin-preload-as",
+  "private": true,
+  "main": "./plugin-config.js"


Hmmm.. weird to have two things that work together both called a config. about how index.js or plugin-index.js? plugin-dfn.js...

paulirish · 2019-02-27T00:00:16Z

docs/recipes/plugin/lighthouse-plugin-preload-as/plugin-config.js

+module.exports = {
+  // Additional audit to run on information Lighthouse gathered.
+  audits: [{
+    path: 'lighthouse-plugin-preload-as/preload-as-audit.js',


interesting that the folder is included here even when the file is a sibling to this plugin definition file.

interesting that the folder is included here even when the file is a sibling to this plugin definition file.

yeah, I wasn't sure how much magic to do on path resolution. We could have plugin folders added to the list of places that lighthouse looks for audits, or automatically prepend the plugin name to the path, but that might get messy quickly (e.g. what if the audit file you want to reference isn't in the plugin directory?).

OTOH, yeah, you have to write these paths relative to where Lighthouse looks, which is node_modules/, cwd, and then the path of the config file, which is kind of confusing in the simple case where you want to reference the audit right next to this file

paulirish · 2019-02-27T18:58:28Z

docs/recipes/plugin/lighthouse-plugin-preload-as/preload-as-audit.js

+class LoadAudit extends Audit {
+  static get meta() {
+    return {
+      id: 'preload-as-audit',


seems weird to put 'audit' in the id. how about 'preload-as' as the id and preload-as.audit.js as filename?

seems weird to put 'audit' in the id. how about 'preload-as' as the id and preload-as.audit.js as filename?

I'd agree with you if this was one of our audits, but it's helpful to have it in the filename, and it seems confusing to me to not have it match the id at that point

preload-as.audit.js and id: 'preload-as', ! everybody wins.

or move the audit js file into /audits/preload-as.js.. that seems nice, too.

everybody wins

that's the opposite of what I said :P

or move the audit js file into /audits/preload-as.js

adding a level of indirection seems worse for an example

I'm definitely in the preload-as-audit is gross for including "audit". I personally like having a directory structure, to me it kind of keeps things all in their place. I like audits/preload-as.js, it gives the plugins a more common form of plugin.js & audits/<your-audits>.js being the standard parts.

brendankenny · 2019-03-07T23:59:06Z

updated to use --plugins instead of another confusing config file and added a brief readme

brendankenny · 2019-03-07T23:59:48Z

docs/recipes/plugin/package.json

+  "name": "plugin-lighthouse-recipe",
+  "private": true,
+  "dependencies": {
+    "lighthouse": "^4.3.0"


intentional as --plugins landed after 4.2.0 :)

intentional as --plugins landed after 4.2.0 :)

actually, jk, that's just really broken. Instead, now it just won't run the plugin since --plugins won't be recognized, but it won't throw an error. The release of 4.3.0 and semver (and/or we remember to update the recipe) will make it work when that comes out

paulirish · 2019-03-21T00:23:34Z

docs/recipes/plugin/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "plugin-lighthouse-recipe",


hmm. what does this package.json do? do we need it?

what does this package.json do?

it lets you run the recipe

ah. it's a little confusing to me with two manifests over here. Like.. for a user.. do they need both?

the plugin folder doesnt have a readme, but anyone making a plugin would be placing a readme in there.

so i'm thinking we just move this readme a level deeper and drop this package.json

so i'm thinking we just move this readme a level deeper and drop this package.json

this makes sense, so here it is, but it basically isn't runnable now

docs/recipes/plugin/readme.md

paulirish · 2019-03-21T00:56:25Z

docs/recipes/plugin/readme.md

+# Lighthouse plugin recipe
+
+## Contents
+- `lighthouse-plugin-preload-as` - the plugin module


Another thing I'm noticing... the Plugin is really about describing the category, not one of the two audits within it.

This category is titled 'My Plugin Category'... but let's pretend it was called 'Example Plugin'. I would expect the folder it's in to match the name of the category.. a la lighthouse-plugin-example-plugin

renamed lighthouse-plugin-example

paulirish · 2019-03-21T01:28:17Z

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

+
+## To run
+
+- Install somehow.


we could nuke private and publish this. sets the convention of folks publishing with the lighthouse-plugin- prefix.

or w/e. i'm chill.

brendankenny requested a review from paulirish as a code owner January 9, 2019 19:44

brendankenny mentioned this pull request Jan 9, 2019

core: add Lighthouse plugins #6959

Merged

brendankenny force-pushed the pluginrecipe branch from 818715b to bb25257 Compare February 14, 2019 01:56

brendankenny changed the title ~~WIP: docs: add plugin recipe~~ docs: add plugin recipe Feb 14, 2019

paulirish requested changes Feb 15, 2019

View reviewed changes

brendankenny assigned paulirish Feb 21, 2019

brendankenny added the waiting4reviewer label Feb 21, 2019

paulirish requested changes Feb 27, 2019

View reviewed changes

brendankenny mentioned this pull request Mar 7, 2019

cli: add --plugins flag to load from the command line #7407

Merged

brendankenny force-pushed the pluginrecipe branch from 84d93e7 to de527bc Compare March 7, 2019 23:41

brendankenny commented Mar 7, 2019

View reviewed changes

brendankenny added 7 commits March 20, 2019 17:13

docs: add plugin recipe

ea5a3e1

update plugin focus

d4c285e

feedback

3fe29fb

plugin.js

3e39233

use --plugin

6ec8ca8

readme

4a24628

better screenshot

17f3c4a

brendankenny force-pushed the pluginrecipe branch from d45dd92 to 17f3c4a Compare March 21, 2019 00:13

audits/

78b6bdc

paulirish reviewed Mar 21, 2019

View reviewed changes

GoogleChrome deleted a comment from paulirish Mar 21, 2019

more

5d4ef05

paulirish reviewed Mar 21, 2019

View reviewed changes

brendankenny removed the waiting4reviewer label Mar 21, 2019

asdfasdf

0f24986

paulirish approved these changes Mar 21, 2019

View reviewed changes

actual install instructions

1ee2eb9

paulirish merged commit 0cd2214 into master Mar 21, 2019

paulirish deleted the pluginrecipe branch March 21, 2019 17:14

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add plugin recipe #6965

docs: add plugin recipe #6965

brendankenny commented Jan 9, 2019 •

edited

Loading

brendankenny commented Feb 14, 2019

paulirish Feb 15, 2019

brendankenny Feb 16, 2019

paulirish Feb 15, 2019

brendankenny Feb 16, 2019

paulirish Feb 15, 2019

paulirish Feb 15, 2019

brendankenny Feb 16, 2019

paulirish Feb 26, 2019

brendankenny Mar 1, 2019

paulirish Mar 1, 2019

brendankenny Mar 1, 2019

brendankenny commented Feb 15, 2019

brendankenny commented Feb 16, 2019

paulirish Feb 26, 2019

paulirish Feb 27, 2019

brendankenny Mar 1, 2019

paulirish Feb 27, 2019

brendankenny Mar 1, 2019

paulirish Mar 1, 2019 •

edited

Loading

brendankenny Mar 1, 2019 •

edited

Loading

exterkamp Mar 21, 2019 •

edited

Loading

brendankenny commented Mar 7, 2019

brendankenny Mar 7, 2019

brendankenny Mar 8, 2019

paulirish Mar 21, 2019

brendankenny Mar 21, 2019

paulirish Mar 21, 2019

brendankenny Mar 21, 2019

paulirish Mar 21, 2019

brendankenny Mar 21, 2019

paulirish Mar 21, 2019

docs: add plugin recipe #6965

docs: add plugin recipe #6965

Conversation

brendankenny commented Jan 9, 2019 • edited Loading

brendankenny commented Feb 14, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brendankenny commented Feb 15, 2019

brendankenny commented Feb 16, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

paulirish Mar 1, 2019 • edited Loading

Choose a reason for hiding this comment

brendankenny Mar 1, 2019 • edited Loading

Choose a reason for hiding this comment

exterkamp Mar 21, 2019 • edited Loading

Choose a reason for hiding this comment

brendankenny commented Mar 7, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brendankenny commented Jan 9, 2019 •

edited

Loading

paulirish Mar 1, 2019 •

edited

Loading

brendankenny Mar 1, 2019 •

edited

Loading

exterkamp Mar 21, 2019 •

edited

Loading