Guides - Progressive Web Apps

[addyosmani]

A consistent piece of feedback I hear from teams building PWAs is that Webpack configs are a major pain point. In particular, knowing what Webpack-specific performance best practices (and plugins) to follow are or what to use for patterns like PRPL.

Is there value in us having a dedicated page to this topic in the docs, even if some of it involves linking out to existing docs? 🙃

I might loosely break these up into a few different buckets:

• "Ship the minimal code to make a page useful"
  • Code-splitting (basic, vendor, aggressive, avoiding module duplication)
  • Using webpack-bundle-analyzer to find and fix low hanging fruit in bundles
  • Staying on top of your perf over time with the Webpack 2.x perf budgets feature
• "Prioritize resources you know are important"
  • Preload bundles to improve perf with link rel=preload. How to do this manually or with a webpack plugin
  • HTTP/2 Server Push to fill up server think time. We have the aggressive splitting plugin, but nothing Webpack specific I can think of that helps with Push manifest generation. Maybe just directly use https://github.com/GoogleChrome/http2-push-manifest?
• "Be network resilient!" with Service Workers
  • Offline static asset caching (sw-precache-webpack-plugin, offline-plugin)
• "Don't double up your parse costs with CSS-in-JavaScript"
  • Use the ExtractTextPlugin to extract CSS into separate files. Avoids 2x memory costs, parse costs and invalidating cachability of JS each time your CSS changes. Some projects (e.g styled components) don't tackle this problem well just yet.
• "Effectively use the browser cache"
  • Long-term caching (Working around runtime/chunk lookups being moved into the vendor bundle & losing long-term caching on each build/deploy)

Related

We're working on some related scaffolding + PWA pieces over on webpack-cli

References

Some PWA teams have been documenting their Webpack configs in public, like this one. We've also got quite a few Webpack configs in use for the HN apps over here: https://github.com/tastejs/hacker-news-pwas

Wrote about some of this stuff in the PWAs with React series.

Twitter Lite's isn't too different but they're on WP1. They're using DedupePlugin(), OccurrenceOrderPlugin, BundleAnalyzer, CircularDependencyPlugin, StatsPlugin.

[evenstensberg]

I'd like very much to discuss somewhere how we want to layer the documentation for the CLI. @skipjack. CC-ing @bebraw for input.

Agenda:

• Where to put documentation
• What should be included in respective locations ( for instance, PWA in webpack.js and regular documentation in the github repo)
• What sections to include in the documentation apart from this
• How to promote best practises for an scaffold

[addyosmani]

I think there would be a lot of value in that. I'm less familiar with the information architecture for webpack.js.org, but I see general "here are Webpack patterns, plugins and best practices for building a PWA" being a (maybe) top-level guide on https://webpack.js.org/guides/? Under "Progressive Web Apps".

And then the Webpack CLI docs at https://webpack.js.org/api/cli/ (eventually?) being updated to reference webpack-cli as a default as well and the interaction + scaffolding + migration features it exposes more clearly. Right now it seems to just have a callout pointing to the repository. I think it would be interesting to figure out whether any official add-ons/scaffolds also get documented on there.

I'll defer to @bebraw and @skipjack for more nuanced advice.

[skipjack]

Ok so as for this issue and the PWA content I think that definitely fits in the guides section (as you suggested @addyosmani). If you'd be interested in submitting a PR to start this guide off, that would be awesome.

@ev1stensberg re the cli the current /content set up is still a bit chaotic but I have a rough plan (laid out here as to a more organized setup). I'm currently working on a PR (#1153) to synchronize the content and routing structure which is kind of a "step one" to getting that plan in action.

As you probably already know, we are pulling content dynamically for loaders and plugins. It sounds like this is what you were thinking about doing with the webpack-cli repo as well so we don't have to document things in two places? In this case I'd say we should either create CLI group of pages within the API section or have it live in under Documentation in it's own section.

Let's talk more offline (maybe the documentation-team slack group?) so this issue can stay dedicated to the PWA discussion. Sorry for the delay on this btw, the last couple days have been very chaotic for me.

[skipjack]

@johnnyreilly so actually it probably makes more sense to just discuss here...

So as a quick walkthrough for the existing guides they basically all follow this structure:

• Use a simpler guide as a base so you don't have to re-document a bunch of setup.
• Include full diff blocks in each section so it's crystal clear what is changing.
• Finish up with a simple conclusion that re-iterates what's been done and why.
• Include any suggestion of next steps either in the conclusion or under the related YAML frontmatter.

Other things to keep in mind:

• Keep the guide targeted, i.e. keep the config and examples related to the topic at hand. Don't digress into unnecessary additional configuration if it isn't directly related to what's being discussed.
• Don't duplicate docs. Link to other sections of the documentation instead. Remember that these are guides, not an API/config reference.

That pretty much sums up what we've tried to do with them. There's a few pages at the end of list that still need to be moved or rethought so you should ignore those as you poke around. In terms of your existing content here, the main things I'd say are that we should:

• Continue using NPM instead of Yarn.
• Use vanilla JS vs. TypeScript.
• Exclude the additional HTMLWebpackPlugin minify config unless it's directly related to making the app a PWA.

To that last point, I think stemming from Output Management might make the most sense for your guide as it walks people through the HTMLWebpackPlugin. However, if you feel there's another that would make more sense as a base, that's fine as well.

[johnnyreilly]

Thanks for this @skipjack - I'll try and take a look at this soon. Pointers appreciated - I may well have questions along the way!

[johnnyreilly]

I'm working on this right now @skipjack - (WIP here). I'll send a PR hopefully within the next week or so. I'm following your advice and using Output Management as my starting point.

Feel free to mark this issue as in progress and assign me.

BTW Do you have an idea when you might publish the Medium post I wrote? https://medium.com/@johnny_reilly/148f43e142f9

[skipjack]

I'm working on this right now @skipjack - (WIP here). I'll send a PR hopefully within the next week or so. I'm following your advice and using Output Management as my starting point.

Fantastic, thanks again for your help on this.

Feel free to mark this issue as in progress and assign me.

Just sent you a collaborator invite, once you accept I'd be happy to assign you.

BTW Do you have an idea when you might publish the Medium post I wrote?

Not sure, I don't really manage the Medium content but I'll ping @TheLarkInn and ask him to take a look.