UpUp: a single JavaScript call for an offline fallback page

What UpUp actually does, and who it is for

A service worker can intercept network requests, but writing one means handling install and activate events, versioning a cache, and deciding what happens when a fetch fails. UpUp collapses that into a configuration call. You name one HTML document to show when the connection is down and a list of assets that document needs, and UpUp registers the service worker and populates the cache for you. The README frames the target audience plainly: sites that want content available "even when they're on a plane, in an elevator, or 20,000 leagues under the sea."

The audience is therefore narrow and specific. It fits a marketing site, a documentation site, a blog, or a small web app whose offline story is "show something useful instead of the browser's error page." It does not fit an application that has to accept writes while offline, queue them, and replay them later. UpUp's documented job is content delivery when the network is gone, not data synchronization. If you are evaluating it for a progressive web app with offline form submission, you are looking at the wrong layer.

The repository itself is small: src and dist directories, a demo folder, docs, a Gruntfile, and a package.json whose main entry points at dist/upup.min.js. There is no server component and no runtime dependency, which is consistent with a library whose whole output is two minified files.

The two-file mechanism behind the offline page

UpUp ships as upup.min.js and upup.sw.min.js. The first is loaded by your page and calls into the second, which is the service worker. That split matters when you deploy: the worker file has to be reachable at a URL that controls the pages you want covered, and the scope determines which requests the worker can intercept. The v1.1.0 release notes describe "support for custom scopes (fully backwards compatible)," so scope is configurable rather than fixed to the directory the worker sits in.

The data flow is short. Your page loads upup.min.js, you call UpUp.start with a content-url and an assets array, and UpUp registers the service worker and caches the named resources. After that, when a request fails because the network is unavailable, the worker answers with the cached offline document instead of letting the browser show its own error. The README's example uses 'content-url': 'offline.html' together with an image, a stylesheet, and a JSON file, which is the shape of a real fallback page: markup plus whatever it needs to render without looking broken.

Because the cache contents are declared up front rather than learned from traffic, the behaviour is predictable. There is no runtime heuristic deciding what to keep. That predictability is the design's main virtue, and also its ceiling: anything you forget to list is not guaranteed to be there when the connection drops.

Installing UpUp and getting a first offline page working

There is no package manager step in the README. It points at two files in dist and tells you to add them to your site, so the shortest path is to download upup.min.js and upup.sw.min.js and serve them from your own origin. The README links the raw GitHub URLs for both. If you prefer to build from source, package.json defines a start script that runs grunt dev, and the devDependencies include grunt, grunt-contrib-uglify, grunt-contrib-connect, grunt-contrib-watch, and grunt-contrib-jshint, so a local Grunt setup is the documented development route.

Once the files are in place, include the library and configure it. The README gives this example:

<script src="/upup.min.js"></script>
<script>
UpUp.start({
  'content-url': 'offline.html',
  'assets': ['/img/logo.png', '/css/style.css', 'headlines.json']
});
</script>

The content-url is the document users see when the network is down, and assets is everything that document needs. Paths are written as you would write them in HTML, so a leading slash means site root and a bare filename means relative to the current page. After adding this, load the page once while online so the worker installs and the cache fills, then reload with the network disabled. If the setup is correct you should see the contents of offline.html rather than the browser's offline error.

One deployment constraint is easy to miss. The README states that UpUp requires a secure connection, because service workers require it, and suggests Let's Encrypt or CloudFlare for a certificate. A local file or a plain HTTP origin will not register the worker, so test on HTTPS or on localhost, which browsers treat as a secure context.

Where UpUp stops: browser support, cache staleness, and no rollback story

The README lists browser support as Chrome 40+, Opera 27+, and Firefox 41+. That list is a snapshot from the project's own documentation and does not mention Safari, Edge, or any mobile browser. The stated fallback behaviour is graceful: in a browser without service worker support, "they will simply be unaffected by UpUp. Nothing will break, and they simply won't notice anything different." That is a reasonable degradation strategy, but it also means your offline page is a progressive enhancement, not a guarantee across your audience.

The more practical limitation is cache staleness. UpUp caches what you declare when the worker installs. The README does not document a cache-busting convention, a version parameter for the asset list, or a way to force an update from the page. If you change offline.html or a stylesheet and users have an installed worker, how and when the new copy reaches them is not described in the README. Before relying on this in production, read the API docs in the docs directory and confirm the update behaviour yourself, because the top-level README is silent on it.

There is also no documented rollback. The README does not describe how to unregister the worker or clear the cache if you decide to remove UpUp from a site. That is not unusual for a library of this era, but it is a real operational gap: removing the script tag does not, by itself, tell users' browsers to stop serving the cached offline page. Plan for that before you ship, not after.

UpUp against hand-written service worker code and Workbox

The obvious alternative is writing the service worker yourself. You would get full control over fetch strategies, cache versioning, and update logic, at the cost of roughly the code UpUp hides: an install handler that opens a cache and adds your assets, an activate handler that cleans old caches, and a fetch handler that decides when to fall back to the cache. For a one-page offline fallback, that is more machinery than the problem needs, and UpUp's value is precisely that it removes it.

Workbox is the other real comparison, and the difference is philosophical rather than cosmetic. Workbox is a set of libraries and build tooling for composing caching strategies per route: precaching a manifest of build output, runtime caching for API responses, expiration rules, and so on. UpUp has no build step, no manifest, and no per-route strategy. You hand it one document and a list. If your requirement is "cache everything the build produced and keep it fresh on each deploy," Workbox addresses that and UpUp does not. If your requirement is "when the network dies, show this page," UpUp is a smaller answer to a smaller question, and the two are not really competing.

A third option is doing nothing and letting the browser show its offline error. That is a legitimate choice for a site where offline visitors have nothing to do anyway. UpUp only earns its two files when a controlled offline message has value: contact details, a note that the content is unavailable, or a cached landing page for a returning reader.

Maintenance status, licence, and the cost of upgrading

The repository is not archived, but the last push was on 2018-12-21, which is also the date of the v1.1.0 release. That release added custom scope support and was described as fully backwards compatible, as was v1.0.0 before it. The practical reading is that the library is finished rather than abandoned in a broken state: its surface is two files and one configuration call, and the service worker API it depends on has been stable for years. Still, no push since 2018 means no fixes arriving, and any issue you hit is yours to work around.

Upgrade cost between the documented releases is low. Both v1.0.0 and v1.1.0 are marked fully backwards compatible, so moving from an earlier version does not require changes to your UpUp.start call, and the new scope option is additive. The version in package.json is 1.1.0, and main points at dist/upup.min.js, so a consumer pulling the package gets the minified distribution rather than the source in src.

The licence is MIT, stated in the README, in package.json, and in the LICENSE file at the repository root. MIT permits commercial use, modification, and redistribution provided the copyright notice and permission notice are retained. That is a permissive arrangement with few strings, but it is not legal advice: if your organisation has a policy on bundled third-party code, run the LICENSE file past whoever owns that policy, and note that the README's licence link points at a path in the author's annyang repository rather than this one, so read the LICENSE file in this repository to be sure of what you are shipping.

Editorial conclusion

Adopt UpUp if you have a static or server-rendered site on HTTPS and you only need a controlled offline page plus a short asset list; the whole integration is one script tag and one UpUp.start call. Do not adopt it if you need background sync, request queues, fine-grained runtime caching rules, or a build pipeline that is still receiving fixes, because the last push was on 2018-12-21 and the README documents no rollback or unregister path. Before shipping, verify three things on your own domain: that the site is served over HTTPS, that the two dist files are served from your origin rather than a CDN with a different scope, and that your content-url and assets paths resolve when you are offline.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes