dsw

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.
You will simply have to create setup in a JSON file how your service worker is supposed to deal with requests. Read the commented JSON example or the documentation and examples below.

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 following its 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
• 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 (under development)
• 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 (kinda connecting the browser and sw scopes via events)

Installing it

It's node program which you may install globally:

npm install -g dsw

Or locally:

npm install dsw --save-dev

TL;DL

Want simply to see it working as fast as possible?
Clone the project, go to its directory, install it and run npm run try

Using it

DSW will look for a file called dswfile.json. So:

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

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

And now, you will add this to your index.html file, like so, 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(function(){
                // inform the user your page works offline, now!
            })
            .catch(function(){
                // do something if the page will not work offline
                // or if the current browser does not support it
            });
    </script>

Done! Now, for any change in your Dynamic Service Worker configuration, just run again the dsw command line on your project.
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/ 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.

You will notice a dsw.js file that has been created in your project's root path.

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:

{
    "dswVersion": 2.2,
    "applyImmediately": true,
    "dswRules": {
        "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.

Matching

The match property accepts an Object or an Array or objects with the following configuration:

• status: An array with the matching statuses (eg.: [404, 500])
• extension: A string or an array of matching extensions (eg.: ["html", "htm", "php"])
• path: A regular expression (cast in a string, so JSON can treat it)

When used as an object, multiple properties are used as "AND". For exampe:

match: {
    extension: ['html', 'htm'],
    status: [404, 500]
}

Will match requests with a status equals to 404 or 500, AND with an extension of html or htm.
While:

match: [
    { extension: ['html', 'htm'] },
    { patch: 'some-dir\/' }
]

Will match all requests with an extension of html or htm, OR in the some-dir/ path (no matter the extension, then).

Strategy

The strategy tells DSW how to deal with different situations for a request lifecycle. It may be:

• offline-first [default]: Will look first for the content in cache and retrieve it. If it is not there, will try and fetch it. Then, stores it in the cache.
• online-first: Will ALWAYS go for the network and see it can load the content. If so, adds(or updates) it into cache(if cache is meant to be applied). If it fails fetching it, only then it will look for it in the cache.

Applying

The apply property for each rule is used when a request matches the match requirements. It may be:

• fetch: The (string)path to be loaded instead of the original request
• redirect: same as fetch, but setting the header status to 302
• cache: An object containing cache information for the request

Cache

DSW will treat the cache layer for you.

Pass to the cache object in your apply definition, an object containing:

• name (mandatory, although a default name will be used if this is not passed)
• version (optional)

You can also define cache: false. This will force the request not to be cached. Seens silly, but is useful when you want an exception for your cached data.

IndexedDB

Some times, you will request a JSON and IndexedDB is the best way to store it.

To do so, you will use the indexedDB action in your apply rule. Pass an object containing the following:

• name: The name of your IndexedDB
• version(optional): The version of your IndexedDB structure
• key: The name of the key, for the indexed data
• indexes: An array with everything you want to use as index.

Indexes may be a String or an object containing:

• path: The path where to find the index in your object
• name(optional): The name of the index (if not sent, path will be used as the name)
• options(optional): Any options you want to set to your index (like unique or multiEntry)

For example:

"apply": {
    "indexedDB": {
        "name": "userData",
        "version": "3",
        "key": "id",
        "indexes": [
            "age",
            {
                "name": "twitter",
                "path": "twitter",
                "options": {
                    "unique": true
                }
            }
        ]
    }
}

In this example, we will have three indexes: age, twitter and id (created automatically as it is the key).

If you DO NOT want to cache your json stored in IndexedDB, set cache: false in your rule/apply configuration.

How it works

You may be wondering how it caches your data. Well, it uses the cacheApi to store as requests, only your keys. When you try to use it, it will use these ids to find the stored data you want, in your indexedDB.

This way, you can access the information in your IndexedDB by yourself, while your requests will automatically deal with it, too.

Examples

Using both match and apply, we can do a lot of things.
Don't forget to re-run dsw path-to-project whenever you made a change to your dswfile.js file.

Treating not found pages (404)

Add this to your dswfile.js:

{
    "dswVersion": 2.2,
    "dswRules": {
        "notFoundPages": {
            "match": {
                "status": [404],
                "extension": ["html"]
            },
            "apply": {
            	"fetch": "/my-404-page.html"
            }
        }
    }
}

Create a my-404-page.html with any content.

Now, access in your browser, first, the index.html file(so the service worker will be installed), then any url replacing the index.html string, and you will see your my-404-page.html instead.

Caching data

Let's see an example of requests being cached:

{
    "dswVersion": 2.2,
    "dswRules": {
        "myCachedImages": {
            "match": {
                "extension": ["png", "jpg", "gif"]
            },
            "apply": {
            	"cache": {
            		"name": "my-cached-images",
            		"version": 1
            	}
            }
        }
    }
}

Dealing with cache exceptions(cache: false)

Let's see an example of requests being cached for all images except one specific image:

{
    "dswVersion": 2.2,
    "dswRules": {
        "myNotCachedImage": {
            "match": {
                "path": "\/images\/some-specific-image"
            },
            "apply": {
            	"cache": false
            }
        },
        "myCachedImages": {
            "match": {
                "extension": ["png", "jpg", "gif"]
            },
            "apply": {
            	"cache": {
            		"name": "my-cached-images",
            		"version": 1
            	}
            }
        }
    }
}

Redirecting an URL

You may want to redirect requests some times, like so:

{
    "dswVersion": 2.2,
    "dswRules": {
        "secretPath": {
            "match": {
                "path": "\/private\/"
            },
            "apply": {
            	"redirect": "/not-allowed.html"
            }
        }
    }
}

Using variables

You can apply actions using variables from your regular expression, like this:

{
    "dswVersion": 2.2,
    "dswRules": {
        "redirectWithVar": {
            "match": {
                "path": "\/old-site\/(.*)"
            },
            "apply": {
                "redirect": "/redirected.html?from=$1"
            }
        }
    }
}

Caching EVERYTHING

Maybe you want to cache everything. Every single request (that is successful) will be cached as soon as it is loaded the first time:

{
    "dswVersion": 2.2,
    "dswRules": {
        "cacheAll": {
            "match": {
                "path": "\/.*"
            },
            "apply": {
            	"cache": {
            	    "name": "cached-files"
            	    "version": 1
            	}
            }
        }
    }
}

Caching your static files

Most of times you will want to cache all your static files, like javascript files or css:

{
    "dswVersion": 2.2,
    "dswRules": {
        "statics": {
            "match": {
                "extension": ["js", "css"]
            },
            "apply": {
            	"cache": {
            	    "name": "page-static-files"
            	    "version": 1
            	}
            }
        }
    }
}

Sending credentials

In case you want to send credentials or other settings to fetch, you can use the options property.

{
    "dswVersion": 2.2,
    "dswRules": {
	"userData": {
        "match": { "path": "\/api\/user\/.*" },
        "options": { "credentials": "same-origin"},
        "apply": {
            // apply somethig
        }
    }
}

Sending credentials

In case you want to send credentials or other settings to fetch, you can use the options property.

{
    "dswVersion": 2.2,
    "dswRules": {
	"userData": {
        "match": { "path": "\/api\/user\/.*" },
        "options": { "credentials": "same-origin"},
        "strategy": "online-first",
        "apply": {
            "indexedDB": {
                "name": "userData",
                "version": "3",
                "key": "id",
                "indexes": [
                    "name",
                    {
                        "name": "twitter",
                        "path": "twitter",
                        "options": {
                            "unique": true
                        }
                    }
                ]
            }
        }
    }
}

Use it programatically

You can also use it programatically, specially if you intend to use or create a tool to build, like grunt or gulp.

const options = {};
let dsw = requier('dsw');
dsw.generate('./path-to-project', options);

Contributing

So, you want to contribute? Cool! We need it! :)

Here is how...and yep, as Service workers are still a little too new, it is a little bit weird! Here is how I've been doing this, and if you have any better suggestion, please let me know :)

1 - Clone the project

git clone https://github.com/NascHQ/dsw

2 - Enter the project directory

cd dsw

3 - Start watching it

npm run watch

4 - Use the sandbox to test it (run this command in another terminal window or tab, so the watch command can continue running)

npm run try

5 - Access in the browser, the address in the right port, as provided by the previous command, something like:

http://localhost:8888/

Please notice we use eslint to validate the code styles. You can see the rules in the .eslintrc.js file.

Testing your changes

Whenever you change any files inside the src directory, the watch will re-build it for you (wait until you see the "DONE" output).

This is automatic, but you stillneed to reload the try command in the other tab:

^C # ctrl+C to stop the previous try, and then...
npm run try

Tips

In the browser, though, you may face some boring situations, so, to make sure you will not fall into a trap debugging unchanged things, here goes some tips:

• Go to the settings of your browser console and enable the "disable cache(when console is open)". This way, you will not be tricked by some unwanted caches.

• Go to the "Application" tab in your console (in chrome, it is in canary by now) and:

1 - Click in "Service workers"

2 - Mark the box "Show All" (and when there is more than one, you may click in "Unregister")

3 - You can also check the box "Update on reload" to keep the latest service worker in command.

4 - When you want to test how things are working offline, simply check the "Offline" box.

5 - You can use the "Cache Storage" in the left panel to verify everything that has been cached.

6 - You can use the Lighthouse to validate the service worker situation: Lighthouse

Help by commenting(or reporting on issues)

If you have an idea or suggestion, please let us know by creating an issue at DSW Github Project page.

Related projects

Some other projects that might help you too.

• Lighthouse - Validates your service worker and manifest for Progressive Web App
• SW-Toolbox - A collection of tools for service workers
• SW-Precache - Precaches specific resources