A set of Polymer elements that simplify service worker registration and caching, powered by the
sw-toolbox library.
Full documentation is available at https://PolymerElements.github.io/platinum-sw/index.html
While <platinum-sw-register> abstracts away many of the details of working with service workers,
there is one specific requirement that developers must fulfill: it needs to register a JavaScript file
located at the top-level of your site's web root. (Details behind this requirement can be found in
the service worker specification issue tracker.)
In order to use <platinum-sw-register>, it's recommended that you create a sw-import.js file in
your site's web root. The file's only contents should be
importScripts('bower_components/platinum-sw/service-worker.js');
You can adjust the path to service-worker.js if your project has its Polymer elements
installed somewhere other than bower_components/.
If you have multiple subdirectories worth of pages on your site, it's recommend that you include the
<platinum-sw-register> element on a top-level entry page that all visitors will access first; once
they visit the top-level page and the service worker is registered, it will automatically apply to
all sub-pages, which will fall under its
scope.
If, as part of your web app's build process, you Vulcanize
the platinum-sw elements, you'll likely run into issues due to relative paths to helper/bootstrap
files being incorrect. For example, a few of the elements attempt to import the
sw-toolbox-setup.js script via a relative path, and that will fail when the elements are moved by
the Vulcanization process. The recommended approach is to explicitly copy the directory containing
those helper files into the same directory as the Vulcanized output, which maintains the relative
paths. The Polymer Starter Kit's gulpfile.js
illustrates one way of doing this. An alternative approach is to use
<platinum-sw-register base-uri="path/to/directory"> and hardcode a base URI to use.
The sw-toolbox library,
which <platinum-sw-cache> is built on, supports a number of
caching strategies.
Two of them, cacheOnly and cacheFirst, are strongly discouraged to be used as the defaultCacheStrategy
for <platinum-sw-cache>. With both of those strategies, all HTTP requests, including requests for
the page which contains the <platinum-sw-cache> element, are served directly from the Cache Storage
API without
first consulting the network for a fresh copy. Once the copy of the host page is cached,
it's extremely difficult to change the configuration of the service worker (since the configuration
depends on the page's contents), and developers could find themselves deploying sites that can never
update.
In a future release of <platinum-sw-cache>, using cacheOnly and cacheFirst as defaultCacheStrategy
may lead to an explicit error condition, but for the meantime, please consider a more reasonable default
(like networkFirst).