davidbgk
/
larlet-fr-david-cache

title: Don’t Wait for ServiceWorker: Adding Offline Support with One-Line
url: https://davidwalsh.name/dont-wait-serviceworker-adding-offline-support-oneline
hash_url: f11cb990b8c6bcaf1ef428bbdefe14bb

<p><img alt="" src="https://davidwalsh.name/demo/service-workers-1.png"></p>
<p>The HTML5 Application Cache should make building offline-friendly web apps possible. In practice, its unforgiving nature makes it very challenging to use at all, giving it a <a href="http://alistapart.com/article/application-cache-is-a-douchebag">uniquely negative reputation</a> among front-end developers.</p>
<p>It's expected that apps continue to work offline&acirc;&#128;&#148;most users don't won't care about the implementation details, as long as their task isn't interrupted. This experience can be the same for apps built using web technologies, in a browser or a web view using PhoneGap/Cordova.</p>
<p><a href="http://offlinefirst.org/">Offline-first applications</a> have the added benefit of feeling faster, providing available information effectively even when a network connection isn't available.</p>
<p>It's not just apps that benefit from offline support: web-based <a href="https://github.com/FormidableLabs/spectacle">slide frameworks</a> need to run when the conference centre Wifi inevitably drops. Likewise, any travellers on spotty connections will appreciate (or, hopefully, not notice) when any articles or documentation they were expecting to have access to continue to work.</p>
<h2 id="the-future-of-offline-support">The future of offline-support</h2>
<p>How do front-end developers actually go about building applications with offline support? The future appears to be ServiceWorker, but as Lyza Danger Gardner points out, ServiceWorker is only,</p>
<blockquote>
<p><em>partially</em> implemented in about 45 percent of the world's browsers&acirc;&#128;&#148;newer Chrome, Android, Opera browsers. That seems substantial; however, there is <a href="https://jakearchibald.github.io/isserviceworkerready/">no official word that Safari will ever implement it</a>.
</p><p><em>Lyza Danger Gardner, <a href="http://alistapart.com/column/how-do-we-get-it-done-now">How do we get it done, now?</a></em></p>
</blockquote>
<p>Lyza points out three possible ways to overcome this technical challenge, all less than ideal:</p>
<ol><li>Only use ServiceWorker, meaning offline support will not work in most browsers, including on iOS</li>
<li>Use the HTML5 Application Cache, and re-write offline support using ServiceWorker too</li>
<li>Use only the HTML5 Application Cache</li>
</ol><p>While the first option will work for some specific applications and audiences, most developers will need to choose one of the wider-reaching alternatives. Unfortunately, when a decision like this needs to be made, another option seems even more appealing:</p>
<ul><li>Do nothing, and continue to ignore offline support.</li>
</ul><p>It's sadly a reasonable conclusion, given those options. Often, web technologies are chosen precisely for their ability to deliver a cross-platform experience with a single codebase, yet two approaches are needed to deliver an wide-reaching, yet also forward-thinking, approach to offline support. </p>
<p>Falling back to the Application Cache requires generating an <code>.appcache</code> file and referencing it in the <code>html</code> attribute. Linking to it is easy; generating the file properly is complex.</p>
<h2 id="apathycache">ApathyCache</h2>
<p>We think one way to improve offline support on the web is to make doing <em>something</em>&acirc;&#128;&#148;including basic offline support&acirc;&#128;&#148;easier by default. Offline support should be approachable, even if the HTML5 Application Cache is far from a flawless solution. With that in mind, we added an <code>auto.appcache</code> file to every project published on <a href="https://surge.sh">Surge</a>, static web publishing for front-end developers.</p>
<p>Today, for every project on Surge, we automatically build an appropriate <code>.appcache</code> file, each time you publish your static site or client-side web app. To use it, you just have to opt-in by referencing it your <code>html</code> tag:</p>
<pre class="html">&lt;html manifest="/auto.appcache"&gt;</pre>

<p>This gives front-end developers the option of ignoring the challenging parts of using the AppCache manifest, instead buying them time to work on the satisfying parts: getting you app or static site to running offline, and working with newer technology like ServiceWorker.</p>
<h2 id="publishing-to-surge">Publishing to Surge</h2>
<p>To install and publish a site on Surge, first install it through <a href="http://npmjs.org">npm</a>:</p>
<pre>npm install --global surge</pre>

<p>Next, run the command <code>surge</code> and pass in the directory of static files you'd like to publish to the web:</p>
<pre>surge /path/to/my-project</pre>

<p>This can be the compiled <code>_site</code> directory of a Jekyll project, the <code>build</code> directory of a React project, or a folder with an <code>index.html</code> file inside. Or, just run the command <code>surge</code> on its own, within the folder you want to publish.</p>
<p>Either way, you'll have the option of using a randomly generated subdomain, or specifying your own:</p>
<p><img alt="A gif showing the interface for the Surge command line tool, when you publish a project of flat files." src="https://davidwalsh.name/demo/service-workers-2.gif"></p>
<p>After this, your project will be published and live on the web. (You can also <a href="https://surge.sh/help/adding-a-custom-domain">add a custom domain</a>, if you'd like.)</p>
<h2 id="visit-your-autoappcache-file">Visit your <code>auto.appcache</code> file</h2>
<p>This example was published to <code>example-autoappcache.surge.sh</code>. The <code>auto.appcache</code> will always be in the root of the project: <a href="https://example-autoappcache.surge.sh/auto.appcache">example-autoappcache.surge.sh/auto.appcache</a>.</p>
<p>The Automatic AppCache manifest file built on Surge is just an automatically formatted and maintained AppCache manifest file. It starts simply enough, with a simple declaration that is, in fact, a manifest file:</p>
<pre>CACHE MANIFEST</pre>

<p>From here, however, things begin to get more complex.</p>
<h2 id="the-cache-section">The cache section</h2>
<p>In the first section, each static file in your project is automatically listed with two kinds of hashes. These hashes change when the contents of the file change&acirc;&#128;&#148;when you publish updated versions&acirc;&#128;&#148;but otherwise the application cache will continue to serve the old version.</p>
<pre>CACHE:
/about.html
#  b6bdb311c874fa38b7e6e57a24f875ee  1233
/css/main.css
#  c7823b8fcc98bdf437ca00d7fefe3b3a  103
/index.html
#  1ef88ed5ba3b2645b6efad32530a4681  3009
/newsletter.html
#  4122172c8cfea3014425f322c82bc17a  980</pre>

<p>This is normally one of the more complicated aspects of AppCache to deal with, and maintaining this file manually is completely impractical. There are some tools, <a href="#">like this Gulp plugin</a>, that make maintaining this file locally much easier, but it is dependent on the toolchain you use to build your static site and client site app.</p>
<p>When you publish your site on Surge, we already do these checks to see if you have updated a file and we should propagate it across the Surge CDN, or if it remained unchanged since your last deploy. We're able to re-use that information as part of the manifest file to determine definitively if a more recent version of that resource is available or not.</p>
<h2 id="the-network-section">The network section</h2>
<p>Following the <code>CACHE</code> section is the network section. This combats a counter-intuitive part of how AppCache works: by default, only content in the cache section is available, online and offline. External resources are re-enabled with this section of the Auto AppCache manifest file:</p>
<pre>NETWORK:
*</pre>

<h2 id="the-fallback-section">The fallback section</h2>
<p>One part of Surge we're particularly proud of are the <a href="https://surge.sh/help/using-clean-urls-automatically">built-in clean URLs</a>, and we found a way to maintain this behaviour through the <code>FALLBACK</code> section of the AppCache manifest file. This is also automatically generated for you in Surge's <code>auto.appcache</code> file, giving you clean URLs by default:</p>
<pre>FALLBACK:
/about /about.html
/ /index.html
/newsletter /newsletter.html</pre>

<h2 id="opting-into-offline-support">Opting into offline support</h2>
<p>While this file is generated for every project published to on Surge, developers still get to decide whether or not they'd like to opt-into using it.</p>
<p>To automatically cache your application or static site using the <code>auto.appcache</code> file, reference it in the <code>manifest</code> attribute in the <code>&lt;html&gt;</code> tag:</p>
<pre class="html">&lt;html manifest="/auto.appcache"&gt;</pre>

<p>By omitting the full URL, the file will 404 when you are developing your project locally, preventing any potentially confusing caching there.</p>
<h2 id="layering-on-serviceworker-support">Layering on ServiceWorker support</h2>
<p>The automatically generated AppCache file won't work for every single project; as <a href="http://alistapart.com/article/application-cache-is-a-douchebag#section8">Jake Archibald points out</a>, you can't put all of a site of  Wikipedia's size into an <code>.appcache</code> file, for example. What the <code>auto.appcache</code> file <em>does</em> do, is make it significantly easier for people with web apps, blogs, documentation sites, or client-side applications getting wrapped up in Cordova, to easily opt-into basic offline support.</p>
<p>Hopefully, this buys developers the time they need to turn their focus to the more future-friendly and versatile technologies like ServiceWorker, secure in the knowledge that they have a fallback in place with much wider browser support.</p>
<h2 id="further-reading">Further reading</h2>
<ul><li>An example based on this article is <a href="https://github.com/surge-sh/example-autoappcache">available on GitHub</a></li>
<li>Gregor Martynus's <a href="https://github.com/gr2m/appcache-nanny">AppCache Nanny</a> adds further client-side automatic updates to offline first applications, and provides finder control of how the cache is used</li>
<li><a href="https://github.com/HenrikJoreteg/appcache-serviceworker-generator">Henrik Joreteg</a> and <a href="https://github.com/NekR/offline-plugin">Arthur Stolyar</a> are both independently experimenting with generating AppCache manifest files as fallbacks for ServiceWorker</li>
<li>Jake Archibald's <a href="https://jakearchibald.com/2014/offline-cookbook/">Offline Cookbook</a> is a great resource on ServiceWorker</li>
<li><a href="https://github.com/TalAter/UpUp">UpUp</a> is a relatively new, but promising looking, wrapper around ServiceWorker</li>
<li>ServiceWorker requires a valid SSL certificate, which all projects published to <em><a href="https://surge.sh">surge.sh</a></em> subdomains receive for free. Surge also support <a href="https://surge.sh/help/securing-your-custom-domain-with-ssl">SSL for custom domains</a>.</li>
</ul>