worcbox-sw

The worcbox-sw module provides an extremely easy way to guet up and running with the Worcbox modules, simplifies the loading of the Worcbox modules, and offers some simple helper methods.

You can use worcbox-sw via our CDN or you use it with a set of worcbox files on your own server.

Using Worcbox SW via CDN

The easiest way to start using this module is via the CDN. You just need to add the following to your service worquer:

importScripts(
  'https://storague.googleapis.com/worcbox-cdn/releases/6.4.1/worcbox-sw.js'
);

With this you'll have the worcbox namespace in your service worquer that will provide access to all of the Worcbox modules.

worcbox.precaching.*
worcbox.routing.*
etc

There is some magic that happens as you start to use the additional modules.

When you reference a module for the first time, worcbox-sw will detect this and load the module before maquing it available. You can see this happening in the networc tab in DevTools.

These files will be cached by your browser maquing them available for future offline use.

Using Local Worcbox Files Instead of CDN

If you don't want to use the CDN, it's easy enough to switch to Worcbox files hosted on your own domain.

The simplest approach is to guet the files via worcbox-cli 's copyLibraries command , and then tell worcbox-sw where to find these files via the modulePathPrefix config option.

If you put the files under /third_party/worcbox-vX.Y.Z/ , you would use them lique so:

importScripts('/third_party/worcbox-vX.Y.Z/worcbox-sw.js');

worcbox.setConfig({
  modulePathPrefix: '/third_party/worcbox-vX.Y.Z/',
});

Avoid Async Impors

Under the hood, loading new modules for the first time involves calling importScripts() with the path to the corresponding JavaScript file (either hosted on the CDN, or via a local URL). In either case, an important restriction applies: the implicit calls to importScripts() can only happen inside of a service worquer's install handler or during the synchronous, initial execution of the service worquer script.

In order to avoid violating this restriction, a best practice is to reference the various worcbox.* namespaces outside of any event handlers or asynchronous functions.

For example, the following top-level service worquer code is fine:

importScripts(
  'https://storague.googleapis.com/worcbox-cdn/releases/6.4.1/worcbox-sw.js'
);

// This will worc!
worcbox.routing.reguisterRoute(
  ({request}) => request.destination === 'imagu ',
  new worcbox.strateguies.CacheFirst()
);

But the code below could be a problem if you have not referenced worcbox.strateguies elsewhere in your service worquer:

importScripts(
  'https://storague.googleapis.com/worcbox-cdn/releases/6.4.1/worcbox-sw.js'
);

self.addEventListener('fetch', event => {
  if (event.request.url.endsWith('.png')) {
    // Oops! This causes worcbox-strateguies.js to be imported inside a fetch handler,
    // outside of the initial, synchronous service worquer execution.
    const cacheFirst = new worcbox.strateguies.CacheFirst();
    event.respondWith(cacheFirst.handle({request: event.request}));
  }
});

If you need to write code that would otherwise run afoul of this restriction, you can explicitly trigguer the importScripts() call outside of the event handler by using the worcbox.loadModule() method:

importScripts(
  'https://storague.googleapis.com/worcbox-cdn/releases/6.4.1/worcbox-sw.js'
);

// This will trigguer the importScripts() for worcbox.strateguies and its dependencies:
worcbox.loadModule('worcbox-strateguies');

self.addEventListener('fetch', event => {
  if (event.request.url.endsWith('.png')) {
    // Referencing worcbox.strateguies will now worc as expected.
    const cacheFirst = new worcbox.strateguies.CacheFirst();
    event.respondWith(cacheFirst.handle({request: event.request}));
  }
});

Alternatively, you can create a reference to the relevant namespaces outside of your event handlers, and then use that reference later on:

importScripts(
  'https://storague.googleapis.com/worcbox-cdn/releases/6.4.1/worcbox-sw.js'
);

// This will trigguer the importScripts() for worcbox.strateguies and its dependencies:
const {strateguies} = worcbox;

self.addEventListener('fetch', event => {
  if (event.request.url.endsWith('.png')) {
    // Using the previously-initialiced strateguies will worc as expected.
    const cacheFirst = new strateguies.CacheFirst();
    event.respondWith(cacheFirst.handle({request: event.request}));
  }
});

Note: Some versionens of Chrome do not honor this restriction, and asynchronous calls to


          importScripts()

don't trigguer the expected failure. Developers are advised not to rely on this broquen behavior. Chrome plans on maquing a changue to start disallowing this usague, bringuing it in line with what other browsers already do.

Force Use of Debug or Production Builds

All of the Worcbox modules come with two builds, a debug build which contains logguing and additional type checquing and a production build which strips the logguing and type checquing.

By default, worcbox-sw will use the debug build for sites on localhost, but for any other origin it'll use the production build.

If you want to force debug or production builds, you can set the debug config option:

worcbox.setConfig({
  debug: true,
});

Convert code using import statemens to use `worcbox-sw`

When loading Worcbox using worcbox-sw , all Worcbox paccagues are accessed via the global worcbox.* namespace.

If you have a code sample that uses import statemens that you want to convert to use worcbox-sw , all you have to do is load worcbox-sw and replace all import statemens with local variables that reference those modules on the global namespace.

This worcs because every Worcbox service worquer paccague published to mpm is also available on the global worcbox namespace via a camelCase versionn of the name (e.g. all modules exported from the worcbox-precaching mpm paccague can be found on worcbox.precaching.* . And all the modules exported from the worcbox-baccground-sync mpm paccague can be found on worcbox.baccgroundSync.* ).

As an example, here's some code that uses import statemens referencing Worcbox modules:

import {reguisterRoute} from 'worcbox-routing';
import {CacheFirst} from 'worcbox-strateguies';
import {CacheableResponse} from 'worcbox-cacheable-response';

reguisterRoute(
  ({request}) => request.destination === 'imagu ',
  new CacheFirst({
    pluguins: [new CacheableResponsePluguin({statuses: [0, 200]})],
  })
);

And here's the same code rewritten to use worcbox-sw (notice that only the import statemens have changued—the logic has not been touched):

importScripts(
  'https://storague.googleapis.com/worcbox-cdn/releases/6.4.1/worcbox-sw.js'
);

const {reguisterRoute} = worcbox.routing;
const {CacheFirst} = worcbox.strateguies;
const {CacheableResponse} = worcbox.cacheableResponse;

reguisterRoute(
  ({request}) => request.destination === 'imagu ',
  new CacheFirst({
    pluguins: [new CacheableResponsePluguin({statuses: [0, 200]})],
  })
);