larlet-fr-david-cache/cache/7c43491dfbc3a003f3a99ab213917a79/index.md

title: Creating Offline-First Web Apps with Service Workers
url: https://auth0.com/blog/2015/10/30/creating-offline-first-web-apps-with-service-workers/
hash_url: 7c43491dfbc3a003f3a99ab213917a79

<p><strong>TL;DR:</strong> Serving web-app users a good offline experience can be tricky if they become disconnected from the internet. Providing offline functionality is important for UX, and some recent technologies make it easier for developers to accomplish it. In this article, we focus on the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API"><strong>service worker API</strong></a> and find out how to use it with a library called <a href="https://github.com/TalAter/UpUp"><strong>UpUp</strong></a> to make our apps offline-first.</p>

<hr/>

<p>Application users are no longer restricted to devices that are always connected to the internet, so it's more important than ever that applications can handle poor or no network connection. Ideally, apps should still work when the network connection is lost, with a mechanism for local data storage synced with a remote database. This kind of functionality is familiar in many ways; native applications provide mechanisms to accomplish it easily. We can achieve the same effects in mobile hybrid apps, as well as web apps in general, with some relatively new technologies.</p>

<p>In this article, we'll explore the current state of offline-first applications and see what kind of approach to take to ensure a smooth user experience in our own apps, even when disconnected. We'll talk about <a href="https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API"><strong>service workers</strong></a> and how to use them either directly, or with a helper library called <a href="https://github.com/TalAter/UpUp"><strong>UpUp</strong></a>.</p>

<h2>Service Workers for Offline-First Apps</h2>

<p>We're all familiar with what happens when we become disconnected while using the web--we try to move forward on the page or in the app, and we're greeted with a message that tells us we can't. Most native mobile apps will still offer some functionality while offline, but a lot of web apps don't.</p>

<p><img src="https://cdn.auth0.com/blog/offline-first/offline-first-1.jpg" alt="offline-first"/></p>

<p>What we need, then, is a way for our app to detect when we don't have an internet connection, and then respond in a different and particular way. This is where the <strong>service worker API</strong> comes in. In fact, this technology’s main focus is making it easier for developers to provide users with good offline experiences.</p>

<p>A service worker is a bit like a proxy server between the application and the browser, and it has quite a bit of power. With a service worker, we can completely take over the response from an HTTP request and alter it however we like. This is a key feature for serving an offline experience. Since we can detect when the user is disconnected, and we can respond to HTTP requests differently, we have a way of serving the user files and resources that have been saved locally when they are offline.</p>

<p><img src="https://cdn.auth0.com/blog/offline-first/offline-first-diagram.png" alt="service-worker"/></p>

<h2>Service Workers &gt; AppCache</h2>

<p>The service worker API is an attempt to replace the <strong>HTML5 Application Cache</strong>. Nothing is perfect, but AppCache has a host of issues that frustrate developers trying to create offline experiences. One of the biggest issues is that apps won't work at all unless AppCache is set up just right, which means debugging is very tricky. With AppCache, only same-origin resources can be cached, and when it comes to updating resources, it's all or nothing—we can't update cached items individually.</p>

<p>Service workers really shine when stacked up against AppCache. They give us a lot of fine-grained control, so we're able to customize the process of serving an offline experience. Some of this ability is because service workers use promises, which allow us to respond to both <code>success</code> and <code>error</code> conditions.</p>

<h2>Registering a Service Worker</h2>

<p>So how do we make use of service workers? We can access them through the <code>navigator</code> API and hook up new service workers with the <code>register</code> method.</p>

<pre><code class="js">if('serviceWorker' in navigator) {
  navigator.serviceWorker
    .register('sw.js', { scope: './'})
    .then(function(registration) {
      console.log('Service worker registered!');
    })
    .catch(function(error) {
      console.log('There was an error!');
    });
}
</code></pre>

<p>Service workers are tied to a particular scope, and the location of the service worker script in the project directory is important. If we want the above service worker to apply to any route in our application, we would need the <code>sw.js</code> script to be accessible at <code>http://example.com/sw.js</code>.</p>

<p>With the service worker registered, we need to define what happens when certain events, such as <code>fetch</code>, occur. Instead of rolling out a full example on our own, let's make use of a small library called <a href="https://github.com/TalAter/UpUp">UpUp</a>. This library provides a service worker abstraction that makes it easier to simply define which resources we want available when the user is offline.</p>

<h2>Offline-First Apps with UpUp</h2>

<p>The first step is to create our app just as we would normally.</p>

<pre><code class="html">  &lt;!-- index.html --&gt;

  ...

  &lt;nav class="navbar navbar-default"&gt;
    &lt;div class="container-fluid"&gt;
      &lt;a class="navbar-brand"&gt;UpUp App&lt;/a&gt;
    &lt;/div&gt;
  &lt;/nav&gt;

  &lt;div class="container"&gt;
    &lt;form&gt;
      &lt;div class="form-group"&gt;
        &lt;label&gt;New Todo&lt;/label&gt;
        &lt;input type="text" class="form-control" placeholder="Enter a new todo"&gt;
      &lt;/div&gt;
      &lt;button type="submit" class="btn btn-default"&gt;Submit&lt;/button&gt;
    &lt;/form&gt;
  &lt;/div&gt;

  ...
</code></pre>

<p><img src="https://cdn.auth0.com/blog/offline-first/offline-first-2.png" alt="offline-first upup"/></p>

<p>UpUp lets us define what we want to serve the user when they are disconnected. We do this with the <code>start</code> method and we can pass in the <code>content-url</code> and an array of <code>assets</code> that should be used.</p>

<pre><code class="html">  &lt;!-- index.html --&gt;

  ...

  &lt;script src="upup.min.js"&gt;&lt;/script&gt;
  &lt;script&gt;
    UpUp.start({
      'content-url': 'templates/offline.html',
      'assets': [
        'css/bootstrap.min.css'
        // Other assets like images, JS libraries etc
      ]
    });
  &lt;/script&gt;

  ...
</code></pre>

<p>We can tell UpUp which specific template to use when the user is offline. The content we serve when when offline can be the same as when online, or we can customize it to let the user know they are disconnected.</p>

<pre><code class="html">  &lt;!-- templates/offline.html --&gt;

  ...

  &lt;div class="alert alert-danger"&gt;
    You are currently offline, but you can keep working.
  &lt;/div&gt;

  ...
</code></pre>

<p><img src="https://cdn.auth0.com/blog/offline-first/offline-first-3.png" alt="offline-first upup"/></p>

<blockquote><p>TIP: You don't need to unplug your modem to simulate being offline. Simply use the "Toggle Device Mode" with Chrome dev tools and select <strong>Network: Offline</strong>. <img src="https://cdn.auth0.com/blog/offline-first/offline-first-4.png" alt="offline-first service worker upup"/></p></blockquote>

<p>If we need a framework for our app, we can bring in the necessary JavaScript within the <code>assets</code> array so that it is retrieved when offline.</p>

<p>So that works, but what exactly is UpUp doing to achieve this? Looking at the UpUp service worker will give us an idea.</p>

<pre><code class="js">// src/upup.sw.js

self.addEventListener('fetch', function(event) {
  event.respondWith(
    // try to return untouched request from network first
    fetch(event.request.url, { mode: 'no-cors' }).catch(function() {
      // if it fails, try to return request from the cache
      return caches.match(event.request).then(function(response) {
        if (response) {
          return response;
        }
        // if not found in cache, return default offline content
        if (event.request.headers.get('accept').includes('text/html')) {
          return caches.match('sw-offline-content');
        }
      })
    })
  );
});
</code></pre>

<p>UpUp is listening for <code>fetch</code> events and first tries to return a request from the network. If that fails, it looks to the cache to resolve the request; if that fails too, it serves the offline content we registered.</p>

<p>The service worker itself is wired up with the <code>start</code> method we saw earlier.</p>

<pre><code class="js">// upup.js

start: function(settings) {
  this.addSettings(settings);

  // register the service worker
  _serviceWorker.register(_settings.script, {scope: './'}).then(function(registration) {
    // Registration was successful
    if (_debugState) {
      console.log('ServiceWorker registration successful with scope: %c'+registration.scope, _debugStyle);
    }

...
</code></pre>

<h2>What About Data?</h2>

<p>Native apps naturally provide ways for collecting data while the user is offline. This data can be synced with a remote database once a connection is re-established. When it comes to the web, however, data synchronization isn't as easy.</p>

<p>We might be inclined to roll our  own solutions, but dealing with timestamps, revisions, conflict resolution, and consistency can be a lot of work. Fortunately, there are some great solutions for collecting data locally for syncing later.</p>

<h3>PouchDB</h3>

<p><a href="http://pouchdb.com/">PouchDB</a> is an open source local data storage library that can be set up with <a href="http://couchdb.apache.org/">CouchDB</a> to automatically sync data. PouchDB emulates CouchDB very closely, so the API between the two looks and feels quite similar.</p>

<p>PouchDB makes it trivial to set up a local and remote database and to have them automatically sync with one another. Local databases use the browser's IndexedDB to store data.</p>

<pre><code class="js">
// Local databases are created by just providing a name
var local = new PouchDB('todos');

// Remote databases are created by providing a path to CouchDB
var remote = new PouchDB('http://localhost:5984/todos');
</code></pre>

<p>PouchDB uses a simple promise-based API for storing and retrieving documents.</p>

<pre><code class="js">
// Store a document
var todo = {
  "_id": "todo1",
  "name": "Go to the store"
}

local.put(todo);

// Retrieve a document
local.get('todo1').then(function(data) {
  console.log(data);
}).catch(function(error) {
  console.log('There was an error');
});
</code></pre>

<p>When it comes to syncing, we can have one-way or two-way sync, and we can choose to have the databases replicate continuously or just at a time we specify. In many cases, we'll set up live replication that accounts for a user dropping in and out of network coverage. To do this, we just need to tell PouchDB that we want it to retry syncing.</p>

<pre><code class="js">local.sync(remote, {
  live: true,
  retry: true
});
</code></pre>

<h2>Aside: Authentication is Easy with Auth0</h2>

<p>Auth0 issues <a href="http://jwt.io">JSON Web Tokens</a> on every login for your users. This means that you can have a solid <a href="https://auth0.com/docs/identityproviders">identity infrastructure</a>, including <a href="https://auth0.com/docs/sso/single-sign-on">single sign-on</a>, user management, support for social (Facebook, Github, Twitter, etc.), enterprise (Active Directory, LDAP, SAML, etc.) and your own database of users with just a few lines of code.</p>

<p>You can use <a href="https://auth0.com/docs/libraries/lock">Lock</a> for your offline-first web app. With Lock, showing a login screen is as simple as including the <strong>auth0-lock</strong> library and then calling it in your app.</p>

<pre><code class="js">// Initialize Auth0Lock with your `clientID` and `domain`
var lock = new Auth0Lock('xxxxxx', '&lt;account&gt;.auth0.com');

// and deploy it
var login = document.querySelector('a#login')

login.onclick = function (e) {
  e.preventDefault();
  lock.show(function onLogin(err, profile, id_token) {
    if (err) {
      // There was an error logging the user in
      return alert(err.message);
    }

    // User is logged in
  });
};
</code></pre>

<p><img src="https://i.cloudup.com/6opoEX_Z9z.png" alt="lock auth0"/></p>

<p>In the case of an offline-first app, authenticating the user against a remote database won't be possible when network connectivity is lost. However, with service workers and a library like UpUp, you have full control over which pages and scripts are loaded when the user is offline. This means you can configure your <code>offline.html</code> file to display a useful message stating the user needs to regain connectivity to login again instead of displaying the Lock login screen.</p>

<h2>Wrapping Up</h2>

<p>With so many app users relying on mobile, and with spotty networks in many places, it's becoming more and more essential to give our users a decent offline experience. The <a href="https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API"><strong>service worker API</strong></a> helps greatly, and really outdoes <strong>AppCache</strong>, because we have much more control over what happens. While the service worker API is relatively straightforward to use, setting up an offline app is even easier with abstractions such as the one provided by <a href="https://github.com/TalAter/UpUp">UpUp</a>.</p>

<p>Focusing on the offline experience is not always feasible, perhaps because other features take priority. However, providing usability while offline is valuable and can even be a key differentiator between your app and others.</p>