Skip to content

Instantly share code, notes, and snippets.

Show Gist options
  • Save adrian-green/0a214537af89fc56cf7c17326db46f3a to your computer and use it in GitHub Desktop.
Save adrian-green/0a214537af89fc56cf7c17326db46f3a to your computer and use it in GitHub Desktop.
ServiceWorker for github pages.

ServiceWorker for github pages

This is a ServiceWorker template to turn small github pages into offline ready app.

Why ?

Whenever I make small tools & toys, I create github repo and make a demo page using github pages (like this one).
Often these "apps" are just an index.html file with all the nessesary CSS and JavaScript in it (or maybe 2-3 html/css/js files). I wanted to cache these files so that I can access my tools offline as well.


Make sure your github pages have HTTPS enforced, you can check Settings > GitHub Pages > Enforce HTTPS of your repository.

Persoanl github pages are all hosted under one root domain (https://[username] This caused some stumblings...

  • When deleting outdated caches for the app, caches.keys() returns all the caches under the domain. We need to filter and delete only caches associated with the app.
  • Path for ServiceWorker should be specified in absolute path
  • the last '/' in URL is important. See following section "When is SwerviceWorker summoned"

When is ServiceWorker summoned ?

In this example ServiceWorker is present to every page under https://{guthub_username}{repository}/, but not https://{guthub_username}{repository}. Notice any difference? that's right, the trailing /

Assuming you have index.html at the root of your repository, a visitor may access /{repository} or /{repository}/ to get same index.html. This is bad practice in general and one should redirect to the other (or that's what Jake said), but most importantly when a visitor is seeing index.html from /{repository} (no '/' at the end), ServiceWorker will not be present on the page.

Just in case your server doesn't handle trailing /, I have <link rel="canonical" href="https://{guthub_username}{repository}/" /> in my index.html header *1.

*1 I mean ... I don't know why I had link rel="canonical" in my code. I do remember having issue with trailing / thought ! So it's the only reason I can think of me wanting to use unfamiliar thing like canonical ¯_(ツ)_/¯

<!DOCTYPE html>
<link rel="canonical" href="https://{guthub_username}{repository}/" />
<style type="text/css">
/* --- application CSS here --- */
background-color: #F5F4F0;
font-family: Georgia, serif;
// register ServiceWorker, remember to use absolute path!
if (navigator.serviceWorker) {
navigator.serviceWorker.register('/{repository}/sw.js', {scope: '/{repository}/'})
// --- Application code here ---
var APP_PREFIX = 'ApplicationName_' // Identifier for this app (this needs to be consistent across every cache update)
var VERSION = 'version_01' // Version of the off-line cache (change this value everytime you want to update cache)
var URLS = [ // Add URL you want to cache in this list.
'/{repository}/', // If you have separate JS/CSS files,
'/{repository}/index.html' // add path to those files here
// Respond with cached resources
self.addEventListener('fetch', function (e) {
console.log('fetch request : ' + e.request.url)
caches.match(e.request).then(function (request) {
if (request) { // if cache is available, respond with cache
console.log('responding with cache : ' + e.request.url)
return request
} else { // if there are no cache, try fetching request
console.log('file is not cached, fetching : ' + e.request.url)
return fetch(e.request)
// You can omit if/else for console.log & put one line below like this too.
// return request || fetch(e.request)
// Cache resources
self.addEventListener('install', function (e) {
e.waitUntil( (cache) {
console.log('installing cache : ' + CACHE_NAME)
return cache.addAll(URLS)
// Delete outdated caches
self.addEventListener('activate', function (e) {
caches.keys().then(function (keyList) {
// `keyList` contains all cache names under your
// filter out ones that has this app prefix to create white list
var cacheWhitelist = keyList.filter(function (key) {
return key.indexOf(APP_PREFIX)
// add current cache name to white list
return Promise.all( (key, i) {
if (cacheWhitelist.indexOf(key) === -1) {
console.log('deleting cache : ' + keyList[i] )
return caches.delete(keyList[i])
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment