Stack Packs

Stack Packs

Stack Packs give us the ability to tailor audits descriptions for specific platforms (e.g. Wordpress). @housseindjirdeh already made a proof of concept in the stacks packs repo. This gives you an idea on how it might look like in lighthouse reports.

This issue is not tackling all questions/issues we will face when implementing stack packs but it should provide us with a solid foundation to serve these packs out of lighthouse core.

Problem

Problem 1: we need a way to detect which frameworks/products are being used so we can connect them to stack packs. For example if we look at a wordpress site we can look at <meta name="generator" content="WordPress 5.3" /> but lots of site remove this tag. So it’s not the best thing to look at. A lot of requests on wordpress sites have wp-content inside or other wp- directives so we could probably use these metrics as a good indication. This example shows that it won’t be possible to have a one way ticket to detect a product/platform so we need some kind of detection mechanism to turn packs on.

Problem 2: replacing or extending audit descriptions is our second problem. It boils down to the question: Where are we setting these strings in the lighthouse process (report or LH result)? Now in lighthouse everything is set inside the result. The report renderer consumes this result to render. Both the ICU identifier and locale descriptions are included in the json output so the renderer can show the text in the correct language. So the best option is to put these platform pack descriptions also in the lhr output This gives us the ability to easily ship it with LH API, if it only lives in the report it won’t be so easy.

Proposed solutions

This is a rough idea on how to get the stack packs integrated.

The idea is to extend the current config with an option called packs or platformpacks: which is an array with the installed stack packs. We populate our default-config with the core packs so they are enabled by default. see plugins as an example. We can also hardcode these values in core if we don’t want people to turn these packs off.

Having an option in the LH config to enable stack packs also gives us the ability to expose some kind of API. An index.js file that exports some functions we want to consume. Top of my head I’m thinking of 2 exports: 1 export is a detect function that is ran inside Lighthouse runner and gets the artifacts as a parameter.

(code is not correct but you get the idea)

export const detect = (artifacts) => {
 return artifacts.networkRecords.find(record=> record.url.includes('wp-content'))
}

The other export is the pack itself (a rough example can be found here)

export const advice = {
  "unused-css-rules": "Consider reducing, or switching, the number of [WordPress plugins](https://wordpress.org/plugins/) loading unused CSS in your page. To identify plugins that are adding extraneous CSS, try running [code coverage](https://developers.google.com/web/updates/2017/04/devtools-release-notes#coverage) in Chrome DevTools. You can identify the theme/plugin responsible from the URL of the stylesheet. Look out for plugins that have many stylesheets in the list which have a lot of red in code coverage. A plugin should only enqueue a stylesheet if it is actually used on the page."
}

We could also add more exports like image or whatever so an icon can be displayed inside the report.

To get this data inside the LHR I propose adding an extra field (stackPacks) to an audit result which hold custom platform pack information. This way we can loop through this array to show extra fields in the report. It’s probably also a good idea to store the information of enabled packs somewhere in LHR so we can display these values somewhere nicely as well.

{
   "id":"unused-css-rules",
   "title":"Defer unused CSS",
   "description":"Remove unused rules from stylesheets to reduce unnecessary bytes consumed by network activity. [Learn more](https://developers.google.com/web/tools/lighthouse/audits/unused-css).",
   "stackPacks": [
         {
            "name": "wordpress"
            "description": "Consider reducing, or switching, the number of [WordPress plugins](https://wordpress.org/plugins/) loading unused CSS in your page. To identify plugins that are adding extraneous CSS, try running [code coverage](https://developers.google.com/web/updates/2017/04/devtools-release-notes#coverage) in Chrome DevTools. You can identify the theme/plugin responsible from the URL of the stylesheet. Look out for plugins that have many stylesheets in the list which have a lot of red in code coverage. A plugin should only enqueue a stylesheet if it is actually used on the page."
         }
    ],
   "score":1,
   "scoreDisplayMode":"numeric",
   "rawValue":0,
   "displayValue":"Potential savings of 8 KB",
   ...
}

I’m hoping this actually make sense and love some feedback on this.

[paulirish]

(Oops.)

detection

We don’t yet know if WordPress can be reliably detected with JS. I filed https://github.com/GoogleChrome/lighthouse-stack-packs/issues/8 to get a more definitive answer on it.

I think it’d be super nice if JS-Lib-Detector was our source of truth for all these, but I’m also a little skeptical that clientside JS will always provide an indication for the stack packs that will be built. Patrick proposes we bind to js-lib-detector for v1, which seems fine enough.

So let’s hope that WordPress is good with a JS detect and our first other customers are, too. 😉

multiple packs

Do we intend to support multiple detected platforms at once?

yes.

Are platform packs always additive? i.e. Do we always keep the original description?

yes. keep orig description and add the packs beneath.

pack definition and LHR

Patrick’s strawman for the plugin export lgtm.

Ward’s proposal of adding them as a toplevel array to the LHR also sgtm. (Seems nicer than trying to smush into LHR.audits) They don’t need the detectedLibraries prop when they’re in the LHR, but the other bits might as well remain.

[wardpeet]

oh yeah I like the idea to have a separate section of stackpacks and than let the renderer to it’s thing. I was on the level of integrating it inside the audit section but this is way better!

{
  "audits": ...,
  "i18n": ...,
  "stackpacks": [
    {
      // seems like they need an ID of somesort 🤷‍♂️ 
      "id": "react",
      // icon as data URI as discussed
      "icon": "data:...",
      // The list of libraries that, if any detected, trigger the display of stack pack advice
      // If things get more complicated this could be a function that accepts all artifacts or something
      "detectedLibraries": ["react", "react-dom"],
      // The advice itself
      "advice": {
        "uses-responsive-images": {...}
      }
    }
  ]
}

I think it’s a good way to start but we have to drop the js-libraries name 😄 Sounds good! I’m not attached to it, let’s make it a first class artifact for plugins and packs!

The reason why I don’t like js-libraries is that it doesn’t fit the purpose anymore, wordpress isn’t a js library so why would it detect it 😄 . Our detector might use js-libraries to handle js libs like react, …