How to Add Offline Support to Your Web App (without hand-writing a service worker)

Adding offline support to web applications does not have to be a daunting task. With Swoff, a config-driven generator, you can create a service worker and client runtime without writing any code, and without injecting any runtime libraries into your bundle. This tool works with any stack that has a fetch event.

To get started, run the command `npx @swoff/cli init && npx @swoff/cli generate`. This sets up the scaffold for your service worker and generates the necessary files. The `npx @swoff/cli init` command is an interactive wizard that prompts you for various options such as framework, output directory, navigation mode, caching strategy, and features. Once the wizard is completed, a `swoff.config.json` file is generated.

The generated `swoff.config.json` file contains the configuration for your service worker. It includes the build output directory, the path where the service worker will be generated, and the URL for the service worker file. The navigation mode can be set to a single page app or a regular app, with a fallback page specified for pages that are not cached. Features such as caching strategy, mutation queue, authentication, and push notifications can also be enabled or disabled.

The generator embeds your latest assets into the service worker, so it must run after every build. This is achieved by adding a script step to your build process that invokes the generator. The injector, which integrates the service worker into your project, can be included in your project regardless of whether you use a bundler or not.

For bundler frameworks, you can simply import the `initServiceWorker` function from the generated client injector. For projects without a bundler, you can include the `client-injector.bundle.js` script tag directly.

After running the build step and including the injector, you can verify that your service worker is working correctly by going to the Service Workers section in your browser's developer tools. You should see your Swoff Service Worker activated and running. Cache Storage will also show structured caches such as swoff-precache, swoff-runtime, and swoff-runtime-html.

Finally, switch the Network tab in your developer tools to Offline mode and reload your site. The site should still load from the precache, with navigation falling back to your offline route when necessary.

Swoff's power lies in its configurability and the fact that it dogfoods itself. The Swoff docs site, located at https://swoff.space, is an example of a live offline-first application built using Swoff. Its service worker is generated by the tool and precaches the entire site, including an /offline route. This site remains fully functional even when the network is unavailable.