Documentation changes for v5

[philipwalton]

This is a master tracking issue for documentation changes we need to make along with releasing v5. We can update this issue as new breaking changes are introduced.

• The makeRequest method is not longer supported on strategy classes (docs page)
• registerNavigationRoute is gone, and this docs page needs to be updated, along with a new recipe geared to the App Shell use case.
• A ton of changes to the documentation page for the various build tools' options.
• There's a new, optional integrity field in the precache manifest.
• Update the workbox-broadcast-update docs to point out it no longer uses the BroadcastChannel API (and that it works in all browsers).
• Update all Plugin docs to use the renamed names.
• Document a "disable logging" flag [More control over enabling/disabling debug logging #1619]
• Talk about using revision: null and the eventual deprecation of string parameters in the workbox-precaching guide.
• Update Getting Started guide(s) to prefer module imports syntax, with links to workbox-sw module page as an alternative.
• Include a simpler standalone offline HTML fallback recipe that uses workbox-navigation-preload.
• Remove existing include-based build cool config docs on https://developers.google.com/web/tools/workbox/modules/workbox-build and https://developers.google.com/web/tools/workbox/modules/workbox-webpack-plugin, and link directly to the JSDoc-based docs instead.
• Update the Rollup bundling guide to mention https://www.npmjs.com/package/rollup-plugin-workbox and https://www.npmjs.com/package/rollup-plugin-workbox-inject
• Update the code labs to prefer module imports syntax.

[pscheit]

can i see the docs somewhere online?

[jeffposnick]

During the pre-release process, the best way to stay informed is to read each release's notes: https://github.com/GoogleChrome/workbox/releases

We're not going to update the official docs until the final release of v5.

[nhoizey]

@jeffposnick do you plan to work on migration documentation, now that rc0 is out?

I would like to try v5, but I'm not sure to understand what needs to be changed from my v4 code.

[evdama]

Hi Jeff, I'm in the progress of overhauling my service worker setup for a Sapper project (read Svelte) which ships a service worker. Now I've been looking at which ways to go forward and decided I want to give workbox a try.

From the links above I figured that the current docs are all v4 and that a bunch of things will be different in v5, most notably the importScript vs bundler starting point. I'll need that documented in order to understand what to do exactly.

Because of that I'll want to wait until the v5 docs are available. In order plan the next four or so weeks, can you give a rough estimate when this will be the case? one month? six month?

[jeffposnick]

@evdama, if you want a starting point, here's a sample project that uses Svelte and Workbox v5, with Rollup bundling the service worker and then workbox-cli to inject the manifest: https://github.com/GoogleChrome/samples/tree/721722c6044d3e1388e2c317aa4d45a2141f9ca3/web-share

For folks who decide that they want to use v5 early, the main difference when switching from the CDN to consuming the bundles is that anything that used to look like

workbox.packageName.functionName(...);

now looks like

import {functionName} from 'workbox-packageName';

functionName(...);

(This existing guide covers some of that in more detail, but it will also need to be updated for v5.)

There are some renamings that happened between v4 and v5, specifically around the various Plugin classes, which all have their module name prefixed to the class name. So

new workbox.expiration.Plugin(...);

has a v5 equivalent of

import {ExpirationPlugin} from 'workbox-expiration';

new ExpirationPlugin(...);

And there a number of more involved changes to the build tools, especially the webpack plugin.

v5 is currently feature complete, and we've ironed out a couple of bugs since entering the release candidate phase. The last remaining task before making v5 final is doing the documentation overhaul, and as per your question, it's going to be something much closer to 1 month than 6 months for that.

[jeffposnick]

We're going to be checking in changes to the workbox-v5 branch at https://github.com/google/WebFundamentals/tree/workbox-v5

(The handwritten Workbox docs live in a different repo.)

You can follow along there.

[evdama]

Thanks a lot for the pointer...
One particular interest for me regarding v5 is how one would do firebase authentication with workbox v5.
There is a doc page on firebase for how it's done using a normal service worker https://firebase.google.com/docs/auth/web/service-worker-sessions

Maybe either that page could get a little additon for how it's done using workbox, or, as an alternative, there could be a recipe example in the workbox docs about how you'd use workbox with firebase auth?

[jeffposnick]

@evdama That's interesting—I hadn't seen those Firebase docs before.

It sounds like the sort of thing that would be best accomplished via a custom Workbox plugin for Firebase Auth. Let's track this request separately from the main v5 docs issue.

[jeffposnick]

Thanks for everyone's patience as we continue to work on the docs.

The first draft of the v4 to v5 Migration Guide is now checked in. If you've been holding off on trying the v5 pre-releases until that guidance was available, please take a look!

[Stanzilla]

What's the upgrade path for something like

new WorkboxPlugin.InjectManifest({
        swSrc: "src/sw.js",
        globDirectory: "../site/",
        globPatterns: ["404.html", "offline.html", "assets/fonts/**/*", "assets/webfonts/**/*", "assets/icons/*"]
      }),

[jeffposnick]

A couple of options:

1. Use copy-webpack-plugin to ensure that your files on disk are part of the webpack asset pipeline, and then rely on the v5 plugin's ability to precache those known assets. You can customize which webpack assets are cached via include/exclude instead of glob patterns.

2. Use workbox-cli or workbox-build in a separate build step, run after the webpack compilation, with similar glob based options as before.

3. Use manifestTransforms to make whatever changes you want to the manifest that the webpack plugin generates. This includes calling workbox-build's getManifest() mode inside the manifestTransform to construct the manifest via the same options as was previously supported, i.e. glob patterns matching files on disk.

Option 1 is probably the most "webpack-y", and I'd imagine most folks would go with something like that.

Option 2 is fairly easy to implement.

Option 3 is the most involved, but gives you the most control.