docs: add plugin guide #8728

patrickhulce · 2019-04-30T02:37:20Z

Summary
Well this took much longer than expected :)

In a google doc it turned out to be ~15 pages though so that makes a little more sense and I hope it's fairly comprehensive 😆

Only one functionality change (fairly big): Exposes our NetworkRecords computed artifact on the public Audit interface

docs/plugins.md

paulirish · 2019-04-30T16:40:08Z

docs/plugins.md

+
+Lighthouse plugins are a way to extend the functionality of Lighthouse with insight from domain experts (that's you!) and easily share this extra functionality with other Lighthouse users. At its core, a plugin is a node module that implements a set of checks that will get run by Lighthouse and added to the report as a new category.
+
+### Do You Need a Custom Audit?


i dont really understand this section. mostly it feels kinda unnecessary. i have problems with the content too.. so maybe you'll just agree it's not important and we can ignore all that. :)

haha, fair points! My dangling sentence was going to say "consider the criteria for Lighthouse audits when adding your own" (i.e. it's actionable, it's impactful, etc) but if we feel like this is getting too preachy that plugin devs know what they're doing, I understand.

(removed it already but wanted to leave the point here for thought)

docs/plugins.md

paulirish · 2019-04-30T16:56:14Z

docs/plugins.md

+- `title: string` **REQUIRED** - The display name of the group in the report.
+- `description: string` *OPTIONAL* - A more detailed description of the group's purpose.
+
+### Plugin Audits


i like calling these "plugin audits" rather than custom audits. :) seems good!

docs/plugins.md

patrickhulce · 2019-05-01T00:27:37Z

lighthouse-core/index.js

@@ -73,5 +73,6 @@ lighthouse.getAuditList = Runner.getAuditList;
 lighthouse.traceCategories = require('./gather/driver').traceCategories;
 lighthouse.Audit = require('./audits/audit');
 lighthouse.Gatherer = require('./gather/gatherers/gatherer');
+lighthouse.NetworkRecords = require('./computed/network-records.js');


Wanted to call this change out as the only real functionality change, but fairly large impact on our public API :)

hmm, I don't really have a problem with this one in particular, but this won't work if/when we end up exposing more and more computed artifacts. Do we need a namespace for them? Just point folks at the directory?

yeah at that point I think we should restructure a lot of our exports and expose some aliases so folks can require('lighthouse/types') require('lighthouse/computed') etc and we're free to move around files as we wish

paulirish

lots of ways for these docs to evolve, but i'm happy for this as a start.

docs/plugins.md

brendankenny · 2019-05-01T02:56:27Z

I'll take a stab tonight or in the morning, but looking great so far

brendankenny

this is looking good. Some change suggestions

brendankenny · 2019-05-02T00:59:02Z

lighthouse-core/index.js

@@ -73,5 +73,6 @@ lighthouse.getAuditList = Runner.getAuditList;
 lighthouse.traceCategories = require('./gather/driver').traceCategories;
 lighthouse.Audit = require('./audits/audit');
 lighthouse.Gatherer = require('./gather/gatherers/gatherer');
+lighthouse.NetworkRecords = require('./computed/network-records.js');


hmm, I don't really have a problem with this one in particular, but this won't work if/when we end up exposing more and more computed artifacts. Do we need a namespace for them? Just point folks at the directory?

docs/plugins.md

brendankenny · 2019-05-02T01:04:35Z

docs/plugins.md

+| ------------------------------------ | ------ | ------------- |
+| Add custom audits                    | ✅      | ✅            |
+| Add custom categories                | ✅      | ✅            |
+| Easily sharable via NPM              | ✅      | ❌            |


you'd just need an absolute path to the config in an npm module, but sure :)

yeah sharable via NPM felt slightly off, what I want to get at here is that custom configs aren't sustainably sharable. you can only ever use one, they can't extend each other, etc. plugins are the real sharable way to offer bits of lighthouse logic.

better name/phrase to capture that complex thought? :)

docs/plugins.md

Co-Authored-By: patrickhulce <patrick.hulce@gmail.com>

brendankenny

should we add a section like eslint does with recommended npm keywords? https://eslint.org/docs/developer-guide/working-with-plugins#share-plugins

This is really good :) Added some more suggestions, but I think this is good to go

docs/plugins.md

brendankenny · 2019-05-03T05:41:42Z

docs/plugins.md

+
+- `title: string` **REQUIRED** - The display name of the plugin's category in the report.
+- `description: string` _OPTIONAL_ - A more detailed description of the category's purpose.
+- `manualDescription: string` _OPTIONAL_ - A more detailed description of all of the manual audits in a plugin. Only use this if you've added manual audits.


ha, I half feel like we shouldn't even mention this... ("what's a manual audit?")

Heh, yeah I don't think we should encourage them for sure :) but feels like we should at least document what it is

docs/plugins.md

brendankenny · 2019-05-03T05:44:28Z

docs/plugins.md

+
+It is an object whose keys are the group IDs and whose values are objects with the following properties:
+
+- `title: string` **REQUIRED** - The display name of the group in the report.


maybe put these above the screenshots? I forgot we were still talking about groups by the time I passed the images :)

brendankenny · 2019-05-03T05:51:29Z

docs/plugins.md

+> Images need alt attributes.
+
+> 4.8.4.4 Requirements for providing text to act as an alternative for images
+> Except where otherwise specified, the alt attribute.... 10,000 words later... and that is everything you need to know about the `alt` attribute!


docs/plugins.md

Co-Authored-By: patrickhulce <patrick.hulce@gmail.com>

docs: add plugin guide

a141f3c

patrickhulce requested a review from paulirish as a code owner April 30, 2019 02:37

paulirish requested changes Apr 30, 2019

View reviewed changes

paulirish mentioned this pull request Apr 30, 2019

[meta] 2019 I/O Burndown #8331

Closed

67 tasks

feedback

0fef350

vercel bot deployed to staging May 1, 2019 00:26 View deployment

patrickhulce commented May 1, 2019

View reviewed changes

paulirish approved these changes May 1, 2019

View reviewed changes

brendankenny reviewed May 2, 2019

View reviewed changes

Update docs/plugins.md

6e59e4d

Co-Authored-By: patrickhulce <patrick.hulce@gmail.com>

vercel bot deployed to staging May 2, 2019 02:05 View deployment

Apply suggestions from code review

6c86090

Co-Authored-By: patrickhulce <patrick.hulce@gmail.com>

vercel bot deployed to staging May 2, 2019 02:11 View deployment

patrickhulce added 5 commits May 1, 2019 21:14

extra feedback

cedf64f

markdown format

0e55e4c

tweak shareable line

975d060

broken toc

5fd10ce

update screenshot

2fd6a2f

vercel bot deployed to staging May 2, 2019 02:24 View deployment

brendankenny approved these changes May 3, 2019

View reviewed changes

patrickhulce commented May 3, 2019

View reviewed changes

docs/plugins.md Show resolved Hide resolved

Apply suggestions from code review

a19609b

Co-Authored-By: patrickhulce <patrick.hulce@gmail.com>

vercel bot deployed to staging May 3, 2019 15:13 View deployment

move text above screenshots

7eb15a6

vercel bot deployed to staging May 3, 2019 15:15 View deployment

paulirish merged commit 03e6566 into master May 3, 2019

paulirish deleted the plugin_docs branch May 3, 2019 19:39

brendankenny mentioned this pull request Jun 25, 2019

Create more useful examples/guides #3877

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add plugin guide #8728

docs: add plugin guide #8728

patrickhulce commented Apr 30, 2019 •

edited

Loading

paulirish Apr 30, 2019

patrickhulce Apr 30, 2019

patrickhulce May 1, 2019

paulirish Apr 30, 2019

patrickhulce May 1, 2019

brendankenny May 2, 2019

patrickhulce May 2, 2019

paulirish left a comment

brendankenny commented May 1, 2019

brendankenny left a comment

brendankenny May 2, 2019

brendankenny May 2, 2019

patrickhulce May 2, 2019

brendankenny left a comment

brendankenny May 3, 2019

patrickhulce May 3, 2019

brendankenny May 3, 2019

brendankenny May 3, 2019


		Lighthouse plugins are a way to extend the functionality of Lighthouse with insight from domain experts (that's you!) and easily share this extra functionality with other Lighthouse users. At its core, a plugin is a node module that implements a set of checks that will get run by Lighthouse and added to the report as a new category.

		### Do You Need a Custom Audit?


		It is an object whose keys are the group IDs and whose values are objects with the following properties:

		- `title: string` REQUIRED - The display name of the group in the report.

docs: add plugin guide #8728

docs: add plugin guide #8728

Conversation

patrickhulce commented Apr 30, 2019 • edited Loading

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

paulirish left a comment

Choose a reason for hiding this comment

brendankenny commented May 1, 2019

brendankenny left a 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 left a 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

patrickhulce commented Apr 30, 2019 •

edited

Loading