My WB journey so far

[kaycebasques]

I'm integrating WB into my tech writing blog. Here's my thoughts on the first experience, so far.

I started with the code snippet on the Get Started > Gulp page. It took a bit of thinking to figure out how to integrate it with the Jekyll build process. Maybe the Get Started experience needs to go a step further and create a set of recipes for the most common tooling combinations?

Bikeshed: it bugged me quite a bit that the globDirectory flag has to start with ./ and that the staticFileGlobs flag has to escape the forward slash (yet none of the other flags do).

gulp.task('bundle-sw', () => {
   return wbBuild.generateSW({
     globDirectory: './app/',
     ...
     staticFileGlobs: ['**\/*.{html,js,css}'],
     ...

Once I got it set up, I opened up DevTools to confirm that WB was "precaching" all of my files. The Application panel showed about 50 resources cached, which seemed about right. That was a cool experience.

So I went offline, and things weren't working as expected. I eventually realized that the links throughout my page all use "pretty URLs", whereas WB cached the full file names, including the .html extension. Seems like a pretty common scenario, maybe WB should have a flag that handles this?

At this point, I realized that I probably need to my own service worker with a fetch listener that handles the pretty URLs. It was surprisingly hard to find out how to do this on the docs site. This seems like a core user-journey, I think it should have an entry on the "How To" page. I think I need to use the injectManifest() method, but my first attempt hasn't worked yet.

Some general thoughts:

I'd avoid jargon-y terms like "precache" and "inject manifest" and just describe what it's doing in plain English. Or, if you do continue to use these terms, link to definitions.

[kaycebasques]

Got the injectManifest() thing working. Turns out that I had set up my Jekyll config wrong and it was clobbering the generated service worker file.

I think the injectManifest() reference (or a How To guide on using WB alongside a custom SW) should specify that you need to import WB into your custom SW and define it before calling precache([]).

importScripts('workbox-sw.prod.v1.0.1.js');

const workboxSW = new goog.SWLib();

self.addEventListener('fetch', function (event) {
  console.log('requested: ', event.request);
});

workboxSW.precache([]);

I first wrote my custom SW like this, omitting the definition of workboxSW:

self.addEventListener('fetch', function (event) {
  console.log('requested: ', event.request);
});

workboxSW.precache([]);

I thought that workboxSW.precache([]) was just a keyword that would get replaced with all of the code that it would need to cache the files (including all of the other WB library code, in other words). I didn't realize that the SW needs to actually call the WB library at runtime.

[kaycebasques]

The iFixit source declares WB using the old library name. I guess it should be this now:

importScripts('workbox-sw.prod.v1.0.1.js');

--- const workboxSW = new goog.SWLib();
+++ const workboxSW = new WorkboxSW();

self.addEventListener('fetch', function (event) {
  console.log('requested: ', event.request);
});

workboxSW.precache([]);

[addyosmani]

Thanks for documenting your WB journey, @kaycebasques!

I started with the code snippet on the Get Started > Gulp page. It took a bit of thinking to figure out how to integrate it with the Jekyll build process. Maybe the Get Started experience needs to go a step further and create a set of recipes for the most common tooling combinations?

We initially focused on the three most common tooling setups - I like the idea of having more recipes for common tooling combinations however 👍 I could see this list growing to include Jekyll, Hugo, Wordpress etc.

Bikeshed: it bugged me quite a bit that the globDirectory flag has to start with ./ and that the staticFileGlobs flag has to escape the forward slash (yet none of the other flags do).

Could you file this API feedback as a separate bug and we can talk about whether we can improve the ergonomics of how it works there? 🐛

Once I got it set up, I opened up DevTools to confirm that WB was "precaching" all of my files. The Application panel showed about 50 resources cached, which seemed about right. That was a cool experience.

🎉 😎

So I went offline, and things weren't working as expected. I eventually realized that the links throughout my page all use "pretty URLs", whereas WB cached the full file names, including the .html extension. Seems like a pretty common scenario, maybe WB should have a flag that handles this?

@jeffposnick @gauntface When I've run into this in my own projects, I've added runtime routing helpers to handle the "pretty URLs" but this is probably not something that will be obvious to a new user. Is your take that handling this is more something we should ensure is documented or should we expose the flag/option proposed for handling it? (I may be missing a better way we handle this today)

I'd avoid jargon-y terms like "precache" and "inject manifest" and just describe what it's doing in plain English. Or, if you do continue to use these terms, link to definitions.

Workbox/Toolbox/Precache have historically opted to use these more jargon-y terms but if they're impeding new users from using our libraries, we should change that. I'm up for a glossary of terms or trying to stay away from using such jardon where we can.

[addyosmani]

The iFixit source declares WB using the old library name. I guess it should be this now:

@jeffposnick Not urgent, but if we get a chance could we update iFixit to use the latest version of Workbox now that we list it over on the examples page?

[jeffposnick]

Yup—https://github.com/GoogleChrome/application-shell/commit/e4b595e20b9f22c62d4421ce666e982b9bde9765

[gauntface]

Opened two issues pulling out some of the remaining doc issues. I'm hoping the CDN stuff will help with the issue of copying over workbox-sw.