workbox-routing code samples should be complete

[kaycebasques]

Current sample for RegExpRoute is:

const route = new workbox.routing.RegExpRoute({
  regExp: new RegExp('^https://example.com/path/to/(\\w+)'),
  handler: {
    handle: ({event, params}) => {
      // params[0], etc. will be set based on the regexp capture groups.
      // Do something that returns a Promise.<Response>, like:
      return caches.match(event.request);
    },
  },
});

const router = new workbox.routing.Router();
router.registerRoute({route});

• Doc should mention that this code goes in the custom service worker
• Code sample should be fully executable. E.g. this sample is missing the importScript() call that imports the Workbox library (is that all that's needed? Or do I need to import some special script for the routing library?), and it's missing the definition for workbox (something like const workbox = new WorkboxSW()... I'm assuming). When you omit the definition, it makes it seem like workbox is a definitive name, when in reality it's just an arbitrary variable name

[kaycebasques]

I'm using workbox-build. Does that include the lib stuff I need to use routing? Or do I also need to include workbox-sw into my project?

[kaycebasques]

This const route = new workbox.routing.RegExpRoute() stuff seems way off... I'm paused in my service worker script, investigating my workbox instance, and I'm not seeing anything close to workbox.routing.RegExpRoute()... I think I may just need to call workbox.router.registerRoute() directly?

Hooking all of these code samples up to a CI is a good way to keep the docs up-to-date

[kaycebasques]

Looks like I need to install some other workbox-routing library and include that in my service worker as well? Not at all clear from the docs

[gauntface]

So the example you are referring to is using the lower level module (RegExpRoute can be found in the reference-docs somewhere)

Workbox-sw actually abstracts / simplifies this so that you can just call registerRoute with a regex and it'll generate it under the hood.

We had an open issue about how we should indicate higher level from lower level modules but it never really got addressed.

[samthor]

The docs talk about RegExpRoute, ExpressRoute etc and use them constantly in samples. It's very frustrating to read the docs and then discover that these objects are hidden. Why publicly document your internals?

Additionally, you don't allow the same functionality. I cannot pass a custom method, e.g., POST, to registerRoute. That's why you had these classes, so we don't have argument hell on registerRoute.

[samthor]

Looks like my grumpiness is because #644 isn't part of a released build yet. That adds method as an argument to registerRoute.

[gauntface]

I'm going to close this as the demos for V3 that are in / landing should cover this (and it simplifies things greatly with the CDN).

https://workbox-demos.firebaseapp.com/demo/workbox-routing/

#962