Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
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])

This comment has been minimized.

Copy link

jpraet commented Feb 3, 2018

Thanks for this! Works perfectly.


This comment has been minimized.

Copy link

satyakresna commented Mar 16, 2018

It works. Thank's a lot Mariko! Anyway, there's a typo:
screen shot 2018-03-16 at 7 33 16 pm


This comment has been minimized.

Copy link
Owner Author

kosamari commented Mar 16, 2018

fixed !


This comment has been minimized.

Copy link

lhuria94 commented Jun 24, 2018

Hey @kosamari, I tried implementing this, but it didnt work on my repo. It just keep on taking my site to 404 not found.

Here is the repo:

Can you suggest?


This comment has been minimized.

Copy link

dabyland commented Feb 17, 2019

This is an awesome tutorial, thank you so much @kosamari!! 🎉 👍


This comment has been minimized.

Copy link

AndreyKondakov commented Mar 15, 2019 What is not wrong, can you check ?(


This comment has been minimized.

Copy link

MatthewRiggott commented May 2, 2019

This was tremendously useful!
Also, $CACHE_NAME = $APP_NAMESPACE + $VERSION never occurred to me as a means of cache busting a service worker.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.