Making your web app work offline, Part 1: The Setup

Original Source: https://css-tricks.com/making-your-web-app-work-offline-part-1/

This two-part series is a gentle introduction to offline web development. Getting a web application to do something while offline is surprisingly tricky, requiring a lot of things to be in place and functioning correctly. We’re going to cover all of these pieces from a high level, with working examples. This post is an overview, but there are plenty of more-detailed resources listed throughout.

Article Series:

The Setup (you are here!)
The Implementation (posts tomorrow, stay tuned)

Basic approach

I’ll be making heavy use of JavaScript’s async/await syntax. It’s supported in all major browsers and Node, and greatly simplifies Promise-based code. The link above explains async well, but in a nutshell they allow you to resolve a promise, and access its value directly in code with await, rather than calling .then and accessing the value in the callback, which often leads to the dreaded “rightward drift.”

What are we building?

We’ll be extending an existing booklist project to sync the current user’s books to IndexedDB, and create a simplified offline page that’ll show even when the user has no network connectivity.

Starting with a service worker

The one non-negotiable thing you need for offline development is a service worker. A service worker is a background process that can, among other things, intercept network requests; redirect them; short circuit them by returning cached responses; or execute them as normal and do custom things with the response, like caching.

Basic caching

Probably the first, most basic, yet high impact thing you’ll do with a service worker is have it cache your application’s resources. Service worker and the cache it uses are extremely low-level primitives; everything is manual. In order to properly cache your resources you’ll need to fetch and add them to a cache, but then you’ll also need to track changes to these resources. You’ll track when they change, remove the prior version, and fetch and update the new one.

In practice, this means your service worker code will need to be generated as part of a build step, which hashes your files, and generates a file that’s smart enough to record these changes between versions, and update caches as needed.

Abstractions to the rescue

This is extremely tedious and error-prone code that you’d likely never want to write yourself. Luckily some smart people have written abstractions to help, namely sw-precache, and sw-toolbox by the great people at Google. Note, Google has since deprecated these tools in favor of the newer Workbox. I’ve yet to move my code over since sw-* works so well, but in any event the ideas are the same, and I’m told the conversion is easy. And it’s worth mentioning that sw-precache currently has about 30,000 downloads per day, so it’s still widely used.

Hello World, sw-precache

Let’s jump right in. We’re using webpack, and as webpack goes, there’s a plugin, so let’s check that out first.

// inside your webpack config
new SWPrecacheWebpackPlugin({
mergeStaticsConfig: true,
filename: “service-worker.js”,
staticFileGlobs: [ //static resources to cache
“static/bootstrap/css/bootstrap-booklist-build.css”,
…
],
ignoreUrlParametersMatching: /./,
stripPrefixMulti: { //any paths that need adjusting
“static/”: “react-redux/static/”,
…
},
…
})

By default ALL of the bundles webpack makes will be precached. We’re also manually providing some paths to static resources I want cached in the staticFileGlobs property, and I’m adjusting some paths in stripPrefixMulti.

// inside your webpack config
const getCache = ({ name, pattern, expires, maxEntries }) => ({
urlPattern: pattern,
handler: “cacheFirst”,
options: {
cache: {
maxEntries: maxEntries || 500,
name: name,
maxAgeSeconds: expires || 60 * 60 * 24 * 365 * 2 //2 years
},
successResponses: /0|[123].*/
}
});

new SWPrecacheWebpackPlugin({
…
runtimeCaching: [ //pulls in sw-toolbox and caches dynamically based on a pattern
getCache({ pattern: /^https://images-na.ssl-images-amazon.com/, name: “amazon-images1” }),
getCache({ pattern: /book/searchBooks/, name: “book-search”, expires: 60 * 7 }), //7 minutes
…
]
})

Adding the runtimeCaching section to our SWPrecacheWebpackPlugin pulls in sw-toolbox and lets us cache urls matching a certain pattern, dynamically, as needed—with getCache helping keep the boilerplate to a minimum.

Hello World, sw-toolbox

The entire service worker file that’s generated is pretty big, but let’s just look at a small piece, namely one of the dynamic caches from above:

toolbox.router.get(/^https://images-na.ssl-images-amazon.com/, toolbox.cacheFirst, {
cache: { maxEntries: 500, name: “amazon-images1”, maxAgeSeconds: 63072000 },
successResponses: /0|[123].*/
});

sw-toolbox has provided us with a nice, high-level router object we can use to hook into various URL requests, MVC-style. We’ll use this to setup offline shortly.

Don’t forget to register the service worker

And, of course, the existence of the service worker file that’s generated above is of no use by itself; it needs to be registered. The code looks like this, but be sure to either have it inside an onload listener, or some other place that’ll be guaranteed to run after the page has loaded.

if (“serviceWorker” in navigator) {
navigator.serviceWorker.register(“https://cdn.css-tricks.com/service-worker.js”);
}

There we have it! We got a basic service worker running, which caches our application resources. Tune in tomorrow when we extend it to support offline.

Article Series:

The Setup (you are here!)
The Implementation (posts tomorrow, stay tuned)

Making your web app work offline, Part 1: The Setup is a post from CSS-Tricks