Dynamic Service Worker

DSW allows you to enable and use Service Workers in a much easier way, also helping you to create and maintain your Progressive Web Apps working offline.<br/> You will simply have to set up how your service worker will handle requests in a JSON file. Read the commented JSON example or the documentation and examples below.

If you are starting from scratch and want to see it working right away, you can go to a new directory and run the init command.

Live Demo

You can access this page and see a live demo of DSW working. After loading the page the first time, it will install the service worker. When opening it the second time, it will cache everything according to the defined rules (described in each block and link). You can then go offline and reload the page to validate it. Dynamic Service Worker demo

Advantages

Use of variables to build URLs and redirects
Different strategies (offline-first, online-first or fastest)
Easy-to-set rules for 404 pages, redirects, cache or use indexedDB, or outpus
Trace requests to debug your configuration, rules and filters
Decision over cache naming and versioning for each matching request
Many named rules (for future debugging tooling...I imagine we can have a lighthouse-like page for debugging your service workers and your rules)
Support for indexedDB
Support for messaging and syncing events (under development)
Quite simple JSON configuration and easy to start with the basic, or go further for more complex cases
Client API with many possibilities
API for Web Notifications
Support (and API) for Push Notifications
Support for opaque requests

Learning it

Read the commented json configuration file: https://naschq.github.io/dsw/config-example.html

Installing it

It's a Node.js program that you may install globally:

npm install -g dsw

Or locally:

npm install dsw --save

Init

In case you want to add support for your website or webapp to work offline, you can easily run in your project's directory:

dsw init

It will create the required files (if they don't already exist) or change the ones that exist but still need changes. For example, it may add a couple tags to your index.html file.

Using it

DSW will look for a file called dswfile.json, just like gulp or grunt do.<br/> So:

Go to your project's root directory and create the dswfile.json.

cd path-to-your-project
touch dswfile.json

You will use your prefered editor to make changes to this file later.

Add this to your index.html file, in the head element:

<link rel="manifest" href="/webapp-manifest.json" />
<meta name="theme-color" content="#color">
<script src="dsw.js"></script>
<script>
  DSW.setup()
    .then(() => {
      // inform the user your page works offline, now!
      // maybe, consider reloading the page automaticaly
    })
    .catch(() => {
      // do something if the page will not work offline
      // or if the current browser does not support it
    });
</script>

Now, for any change in your Dynamic Service Worker configuration, just run(in your project's root directory):

dsw

You can also use dsw path-to-your/project.<br/> This will generate the webapp.manifest and dsw.js files in your project's root directory.

For every new change or version, you will have to run dsw again, so it will generate the updated service worker file.<br/> This will create the manifest (if not there, already) and the dsw.js file.

To do so, if you installed it globally:

dsw path-to-your/project

If you installed locally, though:

node node_modules/dsw/bin [path-to-your-project]

This second example is specially useful if you intend to run it in a stand alone project or want to trigger it using a script in your package.json file.

From now on, let's work as if you had installed it globally in our examples.

Now, let's set up your project's offline configuration.

When you change something in your dswfile.json, you shall re-execute the command above.

Configuring it

Open the dswfile.json in the root of your project and let's add some content like this:

{
    "version": 1.0,
    "applyImmediately": true,
    "rules": {
        "yourRuleName": {
            "match": { },
            "apply": { }
        }
    }
}

That's it! You may have many rules. Reminding that applyImmediately is optional. It will replace the previously registered service worker as soon as the new one loads.

AppShell

The AppShell is the basics your WebApp will require to work, even if offline.
Add to your AppShell things like your main .js, .css, .html and images. This way, the user will be able to see the core of your webapp, with its complete structure. And you can then work on loading the content (if user is online) or showing a message (in case the user is not online).

{
    "version": 1.0,
    "applyImmediately": true,
    "appShell": [
        "/statics/some.js",
        "/statics/some.css",
        "/statics/some-images",
        ...
    ],
    "rules": {
        ...
    }
}

Push notifications

If you want to enable and use push notifications, you can set:

{
    "version": 1.0,
    "applyImmediately": true,
    "notification": {
        "auto": false,
        "service": "GCM",
        "senderId": "your-project-id",
        "dataSrc": "http://where.to/get-your/notification-data",
        "dataPath": "notification",
        "target": "/"
    },
    "rules": {
        /* ... */
    }
}

Here, dataSrc is the path or service where dsw will find the structure for your notification. And dataPath is an optional path for it. For example, the dataSrc request could return:

{
    "title": "The title",
    "icon": "path-to-icon",
    "body": "The message itself"
}

In this case, dataPath would not be provided. But:

{
    "notification": {
        "title": "The title",
        "icon": "path-to-icon",
        "body": "The message itself"
    }
}

For this case, you can say that the dataPath is "notification". And target is the path where you want to focus your users once they click the notification.

You can also provide the static information for notifications, like so:

{
    "version": 1.0,
    "applyImmediately": true,
    "notification": {
        "auto": false,
        "service": "GCM",
        "senderId": "your-project-id",
        "title": "IMPORTANT",
        "body": "There is an update in our page",
        "icon": "path-to-icon"
    },
    "rules": {
        /* ... */
    }
}

In this case, you could use a more generic message simply to call your user to your page.

The auto property is false by default, but if true, will ask for the users permission (to trigger notifications) as soon as the service worker gets registered.

NOTE: By now, only Google's GCM service is supported. You can use it with Firebase or Googl

Dsw

Install / Use

README