googlechrome / workbox

📦 Workbox: JavaScript libraries for Progressive Web Apps

Welcome to Workbox!

Workbox is a collection of JavaScript libraries for Progressive Web Apps.

Documentation

• Overview (site source)
• Get started
• Contribute

Maintenance update

Workbox is a powerful library originally developed by members of Chrome's developer relations team to facilitate the creation of Progressive Web Apps and to improve the offline experience of web applications. It offers a suite of tools and strategies for efficiently caching and serving web assets, managing service workers, and handling offline scenarios. Workbox simplifies the implementation of common caching patterns and provides developers with a comprehensive toolkit to build robust, resilient web applications. From now on, Chrome's Aurora team will be the new owners of Workbox.

Contributing

Development happens in the open on GitHub. We're thankful to the community for contributing any improvements.

Please read the guide to contributing for information about setting up your environment and other requirements prior to filing any pull requests.

License

MIT. See LICENSE for details.

workbox's Issues

Use idb-helper.js in sw-appcache-behavior

Library Affected:
sw-appcache-behavior

Browser & Platform:
all browsers

Issue or Feature Request Description:
Bother the page and service worker code for sw-appcache-behavior make use of IndexedDB, and it would be good to move that code to use the project-level idb-helper.js library that's being introduced as part of the sw-offline-google-analytics code.

E.g.: https://github.com/GoogleChrome/sw-helpers/blob/master/projects/sw-appcache-behavior/src/client-runtime.js#L44

Repo-level README.md with list of projects

There should be a repo-level README.md that's automatically generated, and which provides a title/description for each project, along with links to the relevant documentation.

It should also have an overview of the goals for the repo and the standard LICENSE boilerplate.

The analytics.js script doesn't load offline

Library Affected:
sw-google-offline-analytics

This library currently stores the analytics.js script in cache, but due to CORS restrictions, the script fails to load for offline requests (except in cases where it's already in the browser's HTTP cache).

A short term fix is to have users host the analytics.js script themselves. In the longer term, it'd be nice to either add CORS support to analytics.js or change the way <script> tags handle opaque responses in service worker cache.

I'm looking into the long-term solutions.

Message handler to trigger replaying queued Google Analytics requests

Library Affected:
sw-google-offline-analytics

Browser & Platform:
all browsers

Issue or Feature Request Description:
It could be useful to define a message event handler in the ServiceWorkerGlobalScope that listened for requests from controlled pages to replay the Google Analytics hits, instead of only replaying them when the service worker starts up. This would allow, e.g., the controlled page to listen to window.online and then tell the service worker to attempt replaying.

(This isn't fool-proof, due to lie-fi, but it's something people could opt-into.)

CC: @igrigorik

Consider --migrate support for the SW-CLI

Library Affected:
sw-cli

Browser & Platform:
All browsers

Issue or Feature Request Description:
We might be able to help move more users over to sw-framework by providing a migration flag/option via the CLI that can help rewrite their existing config to use the higher-level framework.

I'm thinking something that considers their existing config immutable, but can read it and write out new config that works with sw-framework but can be thrown away by the developer once they've confirmed everything works as expected.

Issue and PR templates

We should create some for the repo with sensible defaults: https://github.com/blog/2111-issue-and-pull-request-templates

Cache expiration manager

Library Affected:
sw-cache-expiration-manager

Issue or Feature Request Description:
We can refactor the code that currently lives in sw-toolbox for cache expiration into a stand-alone sw-helpers library. I'd imagine that could be done in a way that would allow the module to be imported into sw-toolbox without any visible changes.

The module's interface might look like:

const cache1Manager = new goog.CacheExpirationManager({
  cacheName: 'cache1',
  policy: 'least-recently-used', // The default and only initial policy supported.
  maxSize: 10,
  maxAge: 24 * 60 * 60
});

// Create additional managers as needed.

// Call this within your `fetch` handler after you've added entries to 'cache1',
// or call it at service worker startup time.
cache1Manager.prune();

Author migration guide for sw-framework/goog

Library Affected:
sw-framework

Browser & Platform:
All browsers

Issue or Feature Request Description:

Let's write a guide for folks already using sw-precache and sw-toolbox to help them transition their existing code to the newer sw-framework work (I imagine this will primarily be through the higher level library @gauntface has been working on).

Cannot find module './lib/constants'

Library Affected:

sw-offline-google-analytics,

Browser & Platform:

Chome 54.0.2840.59 m (64-bit) Windows 10

Issue or Feature Request Description:

Following the instructions, installed from npm and then added to service worker but getting the above error.

Installed from npm using jspm, resulting directory structure is:

importScripts('/static/jspm_packages/npm/[email protected]/offline-google-analytics-import.js');

// Then, call goog.offlineGoogleAnalytics.initialize():
// See https://github.com/GoogleChrome/sw-helpers/tree/master/projects/sw-offline-google-analytics#googofflinegoogleanalyticsinitialize
goog.offlineGoogleAnalytics.initialize();

Consistant naming for build files

cc @jeffposnick @addyosmani

Just tried using routing in higher level library and writing tests for it and one thing I found a little confusing / non-obvious was the naming of sw-routing's output files.

I expected the name to be either 'sw-routing.js' or 'sw-routing.min.js', instead it was 'routing.umd.min.js'.

Would people agree that main build files should share name of package?

Would people agree that we can drop the umd and just have .min.js?

sw-offline-omniture-analytics

Library Affected:
sw-offline-omniture-analytics

Browser & Platform:
all browsers

Issue or Feature Request Description:
There's some interest in replicating the general approach of sw-offline-google-analytics, but making it work with the URLs used by the Omniture/Adobe analytics platform.

Bonus points if this was done in a way that abstracted the idea of queueing/replaying requests in generic core library, and then we can just add in specific logic to match the URL patterns used by each of the platforms we care about, with helper methods to adjust the URL parameters appropriately before the URLs are replayed.

Assertions + Errors

@jeffposnick What would you think of adding the ability to pass in a custom error into the Assertions, this allows errors to customised to the use case and can follow a error.name and error.message pattern from the ErrorFactory.

Automation of project documentation

Library Affected:
All

Browser & Platform:
n/a

Issue or Feature Request Description:
We need to automate generating project documentation from the JSDocs, and publishing demos to gh-pages.

broadcast-cache-changes

(I'm moving this here from GoogleChromeLabs/sw-precache#173)

Library Affected:
broadcast-cache-changes

The Broadcast Channel API ships in Chrome 54, and has already shipped in Firefox. It would be a good mechanism for allowing our service worker libraries to communicate with all of their client pages, without having to loop through them and use postMessage() to each one.

I'd like to see this used for cache updates notifications in sw-precache (see GoogleChromeLabs/sw-precache#47) and potentially other types of events in the future.

It's a good idea to standardize on the message format, and then to use a similar standardized format across our libraries. sw-toolbox recently implemented some one-to-one messaging (not using the Broadcast Channel API) that used messages like:

{
  type: 'cache-updated',
  source: 'sw-toolbox',
  cacheName: <name of cache>,
  url: <url of the updated resource>
}

But now I'm thinking that might be a bit too free-form, and not map well to new types of messages. I'd like to standardize on an implementation that could be shared across libraries, and then migrate sw-toolbox to that.

The FSA message format has its roots in Flux, but at the same time, it's flexible enough just to be used as an all-purpose format, and since it appears to have some traction in the developer community, it might be a good choice.

I'm envisioning broadcasting messages like

{
  type: 'CACHE_UPDATED',
  meta: 'sw-precache', // or 'sw-toolbox', etc.
  payload: {
    cacheName: 'my-cache-name',
    updatedItems: [absoluteUrl1, absoluteUrl2, ...]
  }
}

My thinking is that the library should initially focus on just broadcasting CACHE_UPDATED for modifications made to previously cached entries, but perhaps down the line, it can be extended to broadcasting CACHE_ADDED and CACHE_DELETED messages as well.

As for the actual implementation of the code that would generate these messages, I'm going to prototype some approaches and see how they work out, and will share the results in this issue. My current thinking is that ES2015's Proxy might lead to a clean implementation, but failing that, maybe just wrapping the Cache Storage API operations and exposing the wrapped methods via the new library.

CC: @addyosmani @gauntface @wibblymat @ebidel @NekR (in case this is something that he'd be interested in for https://github.com/NekR/offline-plugin)

SW-Lib and Caching Strategies.

Use Cases to Cover

1. Easily use a caching strategy for a route
2. Customise the behaviors for a caching strategy

Easily Using a Caching Strategy

Options:

goog.swlib.router.registerRoute('/', goog.swlib.fastest);
goog.swlib.router.registerRoute('/', goog.swlib.strategies.fastest);
goog.swlib.router.registerRoute('/', new goog.swlib.Fastest());
goog.swlib.router.registerRoute('/', new goog.swlib.strategies.Fastest());

This would use a default cache for caching and would not use the precached assets.

• Should we make the precached assets available to runtime caches by default?

Customise the Behaviors of Caching Strategy

Options:

const behaviors = [.....];
goog.swlib.router.registerRoute('/', goog.swlib.fastest, behaviors);
goog.swlib.router.registerRoute('/', new goog.swlib.Fastest(behaviors));

Put like this, I'm leaning more toward making developers to instantiate the cache strategies.

Then only question is goog.swlib.strategies.* vs having members directly on goog.swlib.*.

@addyosmani @jeffposnick thoughts? Any other use cases?

sw-appcache-behavior network/fallback tests

The current tests for sw-appcache-behavior cover cache population, but don't test the expected NETWORK/FALLBACK behavior. Those tests need to be written.

offline-google-analytics does not work with sendBeacon

Couple of issues..

1. sendBeacon uses POST to transmit data
2. The URL is not unique (current code assumes that it is) and import needs to store and retransmit the POST payload.

To reproduce, enable sendBeacon transport in your GA config:

ga("set", "transport", "beacon");
ga("send", "pageview");

Impose max cache age of 24 hours for manifest requests

Library Affected:
sw-appcache-behavior

Browser & Platform:
all browsers

Issue or Feature Request Description:
There's an open // TODO: Consider cache-busting if the manifest response > 24 hours old. that needs to be implemented, in order to protect against AppCache manifests that dangerously cache themselves indefinitely.

Explore lernajs suitability

https://github.com/GoogleChrome/sw-helpers/issues

Resolve incompatibility with latest selenium-webdriver

selenium-webdriver v2.52.0 was unable to automatically detect the local ChromeDriver instance I had on the PATH in my development environment. Rather than debug that incompatibility, I locked down the version to v2.52.0 via a npm-shrinkwrap.json.

Given more time, I should get to the root of the issue and file a bug against selenium-webdriver if it turns out to be an issue on their end.

Also cache analytics.js using a network-first strategy

Library Affected:
sw-google-offline-analytics

Browser & Platform:
all browsers

Issue or Feature Request Description:
Offline analytics only really makes sense if the top-level https://www.google-analytics.com/analytics.js library is also available offline, so that should be cached by the library. I think a network-first strategy is most appropriate.

Special care should be taken to handle the situation in which https://www.google-analytics.com/analytics.js results in a HTTP 307 pointing to a data: URI, as described at GoogleChromeLabs/sw-toolbox#153

Helper for responsive images

Could you create helper for responsive images using DPR + WebP?

Check out this resources...

• https://github.com/deanhume/Service-Workers-WebP
• http://deanhume.com/home/blogpost/service-workers--dynamic-responsive-images-using-webp-images/10132
• https://youtu.be/etACK2qbHfc?t=33m47s
• ResponsiveImagesCG/picture-element#252

Normalize ErrorFactory and assertion libraries

Placeholder bug to remind myself that there's work to be done to normalize how we're using Error objects in the assert library and the ErrorFactory stuff.

More details to come.

Improve project health [meta bug]

There are a number of project health improvements we could make to the current setup:

• Make the failing tests pass - it's harder to understand the impact of new changes (and existing issues) with sub-projects when the tests have been failing for a while. Let's see if we can get them passing again before adding in new work. Right now it's hard to understand when the tests last actually went green (maybe 3 months ago? :))
• Consider scoping tests to supported browsers - when running --project=sw-offline-google-analytics I see a lot of tests failing in Safari (which doesn't support Service Worker). Selenium assistant can find any and all browsers available, we just need to check them against a browserId.
• Provide more insight into build health per project - I believe we currently only display a single build status for our CI for the overall repo. I'd like to suggest we also include badges for individual projects in the README so folks can instantly tell what is green and what is not.
• Decide on build artifacts - users have asked for us to consider including minified builds in our npm packages (#31). It would be good to decide on this so we can consistently apply it across the subprojects.
• Get linting to pass - This has just been done as part of the work on docs.

Failing Travis CI builds

See https://travis-ci.org/GoogleChrome/sw-helpers/builds/183653927

The errors include:

  1) sw-lib Tests sw-lib Tests in Google Chrome Dev should pass all browser based unit tests:
     Error: Failing tests
      at assistantDriver.getSeleniumDriver.then.then.then (packages/sw-lib/test/automated-test-suite.js:93:19)
      at ManagedPromise.invokeCallback_ (node_modules/selenium-webdriver/lib/promise.js:1366:14)
      at TaskQueue.execute_ (node_modules/selenium-webdriver/lib/promise.js:2970:14)
      at TaskQueue.executeNext_ (node_modules/selenium-webdriver/lib/promise.js:2953:27)
      at asyncRun (node_modules/selenium-webdriver/lib/promise.js:2813:27)
      at node_modules/selenium-webdriver/lib/promise.js:676:7
      at process._tickCallback (internal/process/next_tick.js:103:7)
{ [Error: Mocha exited with code 1]
  message: 'Mocha exited with code 1',
  showStack: false,
  showProperties: true,
  plugin: 'gulp-spawn-mocha',
  __safety: { toString: [Function: bound ] } }

and

  1) sw-precaching Browser Tests should pass all browser based unit tests in  Google Chrome Dev:
     Error: Issues in Google Chrome Dev.
Google Chrome Dev had 1 test failures.
------------------------------------------------
[Failed Test 1]
    - sw-precaching Test Revisioned Caching > should cache and fetch files
        Cannot read property 'should' of undefined
------------------------------------------------
      at assistantDriver.getSeleniumDriver.then.then.then (packages/sw-precaching/test/automated-test-suite.js:74:17)
      at ManagedPromise.invokeCallback_ (node_modules/selenium-webdriver/lib/promise.js:1366:14)
      at TaskQueue.execute_ (node_modules/selenium-webdriver/lib/promise.js:2970:14)
      at TaskQueue.executeNext_ (node_modules/selenium-webdriver/lib/promise.js:2953:27)
      at asyncRun (node_modules/selenium-webdriver/lib/promise.js:2813:27)
      at node_modules/selenium-webdriver/lib/promise.js:676:7
      at process._tickCallback (internal/process/next_tick.js:103:7)
{ [Error: Mocha exited with code 1]
  message: 'Mocha exited with code 1',
  showStack: false,
  showProperties: true,
  plugin: 'gulp-spawn-mocha',
  __safety: { toString: [Function: bound ] } }

Future of Service Worker Tooling [Updated]

This is a continuation of the discussion from #44, moved into a new issue with some concrete goals, plans, and samples.

Here are some of the high-level goals for the new libraries:

• Produce libraries that fit together as a "framework", but also expose interfaces that would allow third-party developers to pick and choose useful bits, e.g. just the cache expiration or runtime caching strategies.
• Design with the future in mind, to account for use cases and enhancements that we don't initially envision. Focus on a flexible set of "behaviors" that provide generic hooks into the framework via cache/request lifecycle events, e.g. cacheDidUpdate or requestDidFail.
• Avoid global state for cleaner, easier-to-test, easier-to-repurpose code.
• Provide a great developer experience. Take steps to avoid silent failures due to misconfiguration. Validate all parameters and opt for using classes rather than anonymous objects for configuration.

The following is an low-level example of how we see the pieces—"behaviors", routing, and runtime caching strategies—fitting together, for those who want to use the full framework.

Not covered in this example, but something that's planned, are helpers for smart precaching based on an asset manifest. It will be covered by new build time tooling, equivalent to the current sw-precache.

This code will result in a service worker that will use a stale-while-revalidate strategy for any requests for URLs ending in .txt, and automatically post a message using the Broadcast Channel API whenever the previously cached entry is updated. It uses a default strategy of network-first for all other URLs.

import {Router, RegExpRoute} from 'routing';
import {RequestWrapper, NetworkFirst, StaleWhileRevalidate} from 'runtime-caching';
import {Behavior as BroadcastCacheUpdateBehavior} from 'broadcast-cache-update';

const requestWrapper = new RequestWrapper({
  cacheName: 'text-files',
  behaviors: [
    new BroadcastCacheUpdateBehavior({channelName: 'cache-updates'})
  ]
});

const route = new RegExpRoute({
  regExp: /\.txt$/,
  handler: new StaleWhileRevalidate({requestWrapper})
});

const router = new Router();
router.registerRoute({route});
router.setDefaultHandler({handler: new NetworkFirst()});

RegexpRoute and ExpressRoute Improving Params Output.

Library Affected: sw-routing

Browser & Platform: All

Issue or Feature Request Description:
At the moment the express and regex routes will pass in an object into the handle method with a 'params' value.

With a regex route of const regexRoute = /\/1234567890\/(\w+)\//; I'd expect to be able to access the capturing group via params, which we can do, but it's not labelled clearly.

The above would result in:

(args) => {
  args.params[0] -----> "/1234567890/test/"
  args.params[1] -----> "test"
  args.params.index -----> 21
  args.params.input -----> "http://localhost:3000/1234567890/test/"
}

Given that the args variable also includes args.url, the params.input value is not useful and params[0] is not exactly useful either.

With express, this follows the same pattern.

For express route of /:date/:id/test/I would expect params to have a data and id value, but it's just index values with '0' being route and 1 being the date value and 2 being the id value.

(args) => {
  args.params[0] -----> "/1234567890/some-id/test/"
  args.params[1] -----> 1234567890
  args.params[2] -----> "some-id"
  args.params.index -----> XX
  args.params.input -----> "/1234567890/some-id/test/"
}

I'd expect:

(args) => {
  args.params['date'] -----> "1234567890"
  args.params['id'] -----> "some-id"
}

Also worth nothing that the 'date' value in this example is parsed as a number rather than a string. Not sure if we should be consistent with that or not.

sw-cache-video-playback

Library Affected:
sw-cache-video-playback

Browser & Platform:
all browsers

Issue or Feature Request Description:
Video streaming from a service worker querying the Cache Storage API has some pain points at the moment—e.g., your service worker needs to understand the Range: request header in order to support seeking/scrubbing. There's a good opportunity to provide a helper that handles that complexity.

(CC: @adrianholovaty)

Broken test of qt= parameter

Library Affected:
sw-google-offline-analytics, etc.

Browser & Platform:
all browsers

Issue or Feature Request Description:
https://github.com/philipwalton/sw-helpers/pull/34 fixed the qt= parameter behavior, but one of the tests needs to be updated to account for it.

getting errors while browser offline and nothing is added to browser indexedDB

Library Affected:
sw-appcache-behavior, sw-offline-google-analytics, etc.

Browser & Platform:
OS: ubuntu 16.04
Firefox 48.0, Opera 39.0, Chorme 52.0.2743.116.

Issue or Feature Request Description:
www.google-analytics.com/collect?v=1&_v=j46&a=1280966206&t=event&_s=24&dl=h…AAAEABI~&jid=&cid=1641706882.1472546722&tid=UA-REPLACE_ME-1&z=1591942474:1 GET https://www.google-analytics.com/collect?v=1&_v=j46&a=1280966206&t=event&_s…CEAAAEABI~&jid=&cid=1641706882.1472546722&tid=UA-REPLACE_ME-1&z=1591942474 net::ERR_INTERNET_DISCONNECTED

The FetchEvent for "https://www.google-analytics.com/collect?v=1&_v=j46&a=1280966206&t=event&_s…CEAAAEABI~&jid=&cid=1641706882.1472546722&tid=UA-REPLACE_ME-1&z=1591942474" resulted in a network error response: the promise was resolved with an error response object.
www.google-analytics.com/collect?v=1&_v=j46&a=1280966206&t=event&_s=24&dl=h…AAAEABI~&jid=&cid=1641706882.1472546722&tid=UA-REPLACE_ME-1&z=1591942474:1 GET https://www.google-analytics.com/collect?v=1&_v=j46&a=1280966206&t=event&_s…CEAAAEABI~&jid=&cid=1641706882.1472546722&tid=UA-REPLACE_ME-1&z=1591942474 net::ERR_FAILED

*When reporting bugs, please include relevant JavaScript Console logs and links to public URLs at I have tried the demo, I was getting the above errors. nothing was appended to the indexedDB

Feature Request: Include minified offline-google-analytics.js in npm install

Library Affected:
sw-google-offline-analytics

Browser & Platform:
All browsers

Feature Request Description:
It would be great if the npm install also included a minified version of the offline-google-analytics.js file 👍

sw-offline-google-analytics: console filled with error messages when browsing offline

Library Affected: sw-offline-google-analytics

Browser & Platform: all browsers

Issue or Feature Request Description:

The helper works like it should. Except each event recorded by google analytics while browsing offline returns 3 errors:

Failed to load resource: net::ERR_INTERNET_DISCONNECTED: https://www.google-analytics.com/collect?v=1&_v=j47&a=2067088040&t=pageview...

The FetchEvent for "https://www.google-analytics.com/collect?v=1&_v=j47&a=2067088040&t=pageview..." resulted in a network error response: the promise was resolved with an error response object.

GET https://www.google-analytics.com/collect?v=1&_v=j47&a=2067088040&t=pageview... net::ERR_FAILED

Which results in a dirty console after a while. I know it's not that much of a problem, but is it possible to "catch" those errors and swallow them into the fetch event?

Decide on build artifacts per npm package

Library Affected:
All

Browser & Platform:
All

Users have asked for us to consider including minified builds in our npm packages (#31). It might be nice to make a call on this so we can consistently apply it across the subprojects.

Fwiw, popular libraries like Lodash include both unminified and minified versions in their npm package.

Revamp the defaults around opaque responses

cc @addyosmani @jeffposnick

Library Affected: sw-precache (Possibly some of the behavior modules as well)

Browser & Platform: All

Issue or Feature Request Description: How should we handle CORs / Bad requests?

This has been a common request / issue with developers using sw-toolbox (perhaps sw-precache as well). Arguments for and against which requests are cached and which aren't. Previously there was an option / config to define which status codes would be treated as valid status codes.

// A regular expression to apply to HTTP response codes. Codes that match
// will be considered successes, while others will not, and will not be
// cached.
successResponses: /^0|([123]\d\d)|(40[14567])|410$/

This breaks down to:

0 Opaque responses

Good: Works with CDN content from other domains.
Bad: Response may be bad and this means we could be serving up bad responses when a network
response is available.

1XX Informational

This class of status code indicates a provisional response, consisting only of the Status-Line and optional headers, and is terminated by an empty line. Since HTTP/1.0 did not define any 1xx status codes, servers must not send a 1xx response to an HTTP/1.0 client except under experimental conditions.

Good: ...
Bad: ...

Is this a common status code to use? When is this useful to cache?

2XX Success

This class of status codes indicates the action requested by the client was received, understood, accepted and processed successfully.

Good: Extremely common and expected to be cached.
Bad: ...

3XX Redirection

This class of status code indicates that further action needs to be taken by the user agent in order to fulfil the request. The action required may be carried out by the user agent without interaction with the user if and only if the method used in the second request is GET or HEAD. A user agent should not automatically redirect a request more than five times, since such redirections usually indicate an infinite loop.

Good: Can save a network trip from the server.
Bad: Redirect for auth may cause issues if cached and returned. Doesn't the fetch API handle redirects? Meaning that this should cache the final response rather than a 3XX redirect response?

401, 404, 405, 406, 407, 410 Client Error

The 4xx class of status code is intended for cases in which the client seems to have erred. Except when responding to a HEAD request, the server should include an entity containing an explanation of the error situation, and whether it is a temporary or permanent condition. These status codes are applicable to any request method. User agents should display any included entity to the user.

401: Unauthorizaed
404: Not found
405: Method Not Allowed
406: Not Acceptable
407: Proxy Auth Required
410: Gone

Good: Handy if you want to cache a 404 page
Bad: If there is a server error and a 40X page is returned when it's not intended, this could lead to caching a bad response (bad in the eyes of the consumer of this library).

Thoughts?

For default settings, my gut says that 2XX request should be cached, this is used for Response.ok and I believe is what the cache.addAll does use this or is being changed to do this.

For Opaque responses, I think it makes sense to cache them as well. Question is whether there are any negatives for caching this by default?

For 3XX and 4XX response I don't see the benefit of caching these.

Final comment: How should these be configured? Part of the options object for each module constructor that needs to cache requests? Should we stick to a regex?

Update sw-testing-helpers dependency

Library Affected:
all

Browser & Platform:
all browsers

Issue or Feature Request Description:
Firefox is currently unhappy with the test harness provided by sw-testing-helpers 0.0.14: https://travis-ci.org/GoogleChrome/sw-helpers/builds/140836077

sw-testing-helpers is currently up to release 0.1.1.

Add sw-offline-google-analytics

@addyosmani has some work at https://github.com/GoogleChrome/sw-helpers/tree/offline-analytics but that doesn't use the current monorepo setup. I also have a slightly tweaked version of the original code, and we need things like JSDoc comments.

I'll put together a PR with all that.

New lifecycle event for request failures in RequestWrapper

Note to self: I need to add in a new lifecycle event to handle network request failures and feed into the offline queueing library work that @prateekbh is working on.

Use Google Analytics' /batch endpoint for replaying

Library Affected:
sw-google-offline-analytics

Browser & Platform:
all browsers

Issue or Feature Request Description:
The Google Analytics API supports a /batch endpoint, allowing you to send up to 20 payloads at once in a single HTTP POST. It would be more efficient to use that for replaying failed requests than just sending individual HTTP GETs.

SW-CLI Usage

@jeffposnick @addyosmani

Sorry I haven't covered this topic sooner - it's only lightly covered in the sw-goog doc.

I've started to consider the scenarios of the CLI usage. If we can cover the primary use cases in the CLI, I'm confident the right API can be exposed as a module for gulp and grunt etc.

In the doc we outline the main use cases as generating a service worker and building a file manifest.

Generating a Service Worker

The user journeys of this are likely to be:

1. First time use of the CLI (either first use by the user or first time using for a new project).
2. Repeat use of the CLI (manually running to fix or make changes).
3. Automated running of CLI on a CI like Travis.

First Use - sw-cli generate-sw

For the first use we can use an interactive CLI that guides the developer somewhat, asking them for:

1. Ask for the root directory.
2. Ask them to confirm the types of files they wish to cache (i.e. *.html, *.png, *.jpg) etc - this will be based on the files found in the directory.
3. Ask them what the manifest file should be called (default: precache-manifest.json).
4. Ask them what the service worker file should be called (default: sw.js).
5. Ask if we should save this to a config file sw-cli-config.json (Y / n).

The result of this is a service worker and file manifest. If the user selects to generate a config file, it'll also be generated and the config will include a more extensive set of config options (i.e. options that are excluded from the interactive CLI)..

Second Use - sw-cli generate-sw

The second flow would go through the same flow:

1.) If a config file is found with name sw-cli-config.json then we'll ask the developer if they wish to use it.
2.) If not found or used, the above flow will be taken
3.) We will ask the developer if they wish to override the service worker file and / or config file if required.

CI Use - sw-cli generate-sw --non-interactive

This mode will require the default config file to exist on the current working directory OR expect the '--config' flag to be set. Overwriting tan existing service worker file will be blocked by default but --force can be used to force it (I'd expect developers to clean the directory before overwriting).

Build File Manifest

The manifest can use the same config file from the previous step and could follow the same interactive flow:

1. Ask for the root directory.
2. Ask them to confirm the types of files they wish to cache (i.e. *.html, *.png, *.jpg) etc - this will be based on the files found in the directory.
3. Ask them what the manifest file should be called (default: precache-manifest.json).
4. Ask if we should save this to a config file sw-cli-config.json (Y / n).

The second use and CI use would follow the same pattern as above. The only difference is any questions regarding SW are skipped.

Does this seem like a reasonable first approach?

Naming conventions

I think we need to come up with naming conventions that our whole team can agree on. I personally dislike the practice of adding 'Promise' to the name of functions that return promises, especially as it becomes the norm for functions to return promises. I certainly wouldn't see us do this for other return types.

I don't really think it adds anything, and in many cases can be more confusing - I would expect globPromise to be a Promise rather than a function that returns one, for example. And I would expect processPromiseWrapper to be a method that takes a 'processPromise' (whatever that might be) and wraps it, whereas it is actually something that promisifies process.

On the flip side, I know that my natural style is at the minimal end of the spectrum, and I'm sure plenty of people feel that my names are not descriptive enough.

This is totally a discussion for after I/O though!

Consider scoping tests to supported browsers

When running --project=sw-offline-google-analytics I see a lot of tests failing in Safari (which doesn't support Service Worker). Selenium assistant can find any and all browsers available, we just need to check them against a browserId.

Improve documentation

As described in https://www.scirra.com/blog/ashley/27/service-workers-are-a-pain-in-the-ass, the difficult points of using SW to replicate appcache are:

• implicit caching of the index page (regardless of its precise name) including when just /
• reload-to-update (with the same browser window)
• atomic swaps (never mixes versions)

The documentation for sw-appcache-behavior does not seem to specifically address this. It would be reassuring to see it more comprehensively documented that it covers this, and if not, to have any exceptions listed.

Add a flag to RequestWrapper to wait on cache operations

This would make it possible for @gauntface to use RequestWrapper inside of the precaching code, as well as make it easier to write tests that depend on entries being written to the cache.

Toggle assertions/debug logging via environment setting

We should come up with a standard toggle for enabling/disabling assertions and additional logging via a central framework-level environment value ('production' or 'development').

The default value for that value, when not explicitly set, could be 'development' if we detect that we're being served from localhost, and 'production' otherwise.

Open infra Questions

Library Affected: All

Browser & Platform: All

Issue or Feature Request Description:
At the moment tests are managed by the gulp build process which runs all tests for all projects. This raised a few questions in my head (Sorry I didn't communicate any of this in the early docs we had on this repo)

Releasing

• Is the intention that all projects are released under sw-helpers on NPM or release as individual projects?
• What is the release process for sw-helpers or the individual projects?

Testing

• At the moment the idea is all projects should share the same infra. This is a good idea, but doesn't feel like it scales too well. One project may use Mocha, while another uses Ava, should this be allowed / supported?
  • If we have separate infra for each project, it should allow us to pull projects out into seperate repo's if we ever wanted to.
• I've found using Gulp to orchestrate the running of tests often causes odd side effects / becomes more trouble than just using mocha via npm scripts, could we change to that? (Main side affect being that Mocha could fail, but gulp swallows the error code)
• I'd love to see the sw-helpers test basically be a mocha test in it's own write that looks for all project directories and call npm test in that projects directory, this then allows that project to do anything (or nothing) that it wants.

Documentation

• How is the library going to produce and distribute docs?

Launch-plan for sw-framework & sw-cli

Library Affected:
All new libraries

Browser & Platform:
All browsers

Issue or Feature Request Description:

While we can't publicly comment on I/O dates just yet, I think these are good top-level goals:

• Launch a stable version of sw-framework and the CLI
• Publish stable API documentation for both these pieces in the repo
• Publish developer guides (getting started, migrating from sw-toolbox/precache) on /web
• Prepare working demo app (could be iFixit or one of the HackerNews apps) using sw-framework

Nice-to-haves:

• Launch a stable version of the Background Sync library with docs + example
• Migrate sw-offline-google-analytics to the new Background Sync library

Stretch:

• Update existing toolbox/precache codelab to use sw-framework

This is dependent on #110, #109, #134, #169, #198, #202, #206, #205, #173, #164, #135, #195 landing.

sw-background-sync-queue

Library Affected:
sw-background-sync-queue

Browser & Platform:
all browsers

Issue or Feature Request Description:
"One-shot" background sync has some common usage patterns that we might be able to automate—e.g., provide a method to coordinate passing data between the controlled page and the service worker (via postMessage() or IndexedDB) and a helper to automate the sync event handling in the service worker to consume that data from the queue of pending requests.

Future of Service Worker Tooling

cc @addyosmani, @jeffposnick

We've chatted a little bit about future of tooling, but it would good to move the discussion a little further forward and agree of a rough plan and then move into some more technical detail and strategy.

This is a bit of a brain dump as to audience we might want to target, followed by general requests / approaches people have hinted at wanting and finally a super vague idea of what we can do.

Audience

• Developer who wants a build time solution for each release. Run '*-cli' and generate my service worker.
• Developer who wants a high level library to simplify writing a service worker.
• Developer who has written their own service worker but wants specific feature from the high level library (i.e. cache expiration, Analytics cachings).

Possible audience based on some developers editing a generated SW?

• Developer who wants to a generic service worker to generate once and use.

Requests / Approaches

• CLI that builds a complete service worker for you
• A library that offers high level helpers to create a service worker by hand
• Individual modules that can be pulled in and used for small pieces of logic

General Architecture

• Small modules like we have in sw-helpers. Self contained pieces of logic with clearly defined API's.
• High Level Library consisting of the smaller modules, nothing more than a sanitised wrapper around the smaller modules (i.e. very little to know logic).
• CLI tool that generates a service worker using the high level library.

What are the thoughts of these vague topics, is this the general approach people have in their heads? Is a target audience missing? General architecture seem wonk / destined to fail?

Set up Travis CI

It should run gulp test and gulp lint for incoming PRs.

Make the failing tests pass

It's harder to understand the impact of new changes (and existing issues) with sub-projects when the tests have been failing for a while. Let's see if we can get them passing again before adding in new work. Right now it's hard to understand when the tests last actually went green (maybe 3 months ago? :))

Matt was up for trying to get the tests passing. Locally we're all green now on the appcache behavior. Just need to go green on offline analytics before that work lands.