A Step by Step Jekyll Blog to Progressive Web App Guide

In recent years, web technologies have started to catch up to mobile devices in terms of offering a first-class mobile experience. Here’s a step by step guide in the effort required to migrate my personal website to a progressive web application (PWA).

Before Getting Started

In order to track my progress, I made extensive use of the open-source project, Lighthouse. There’s a handy chrome extension available here.

For those unfamiliar, Lighthouse will audit your site and give you a score over five categories:

Scores range from 0 (worst) to 100 (best) and very often it will report tips or suggestions on improving your score.

Establish a Baseline

At the start of this project, this site is:

Here’s that baseline score:

GitHub Pages

I’m immediately docked points for not using HTTPS. As of this blog post, GitHub does not offer HTTPS for static sites that use custom domains (they do offer HTTPS for non-custom domains, for free). There’s an open issue around supporting it; but rather than wait for GitHub to maybe support this feature, I decided to migrate my site to Netlify, which offers SSL for custom domains.

I was initially worried I might have some performance degredation with Netlify over GitHub. I connected my repository and built my site. Here are the results:


My scores increased with no effort and I saw comparable performance to GitHub pages. For example, I was seeing ~1 second to first meaningful paint on GitHub pages and ~1.3 seconds on Netlify. That was close enough without any optimization to move forward.

Netlify + HTTPS

Migrating my site to Netlify was a snap, so I won’t dive in to it. There is good documentation here and here.

After getting my repository connected:

Here are the results:

Hosted with Netlify

Asset Optimization

This can be a complicated topic in web development, luckily this is literally a checkbox in Netlify (here is an overview).

Without asset optimization enabled, here are the asset requests:

No asset optimization

And the lighthouse score:

performance lighthouse - no asset optimization

After enabling the asset optimization feature:

with asset optimization

And the lighthouse score:

performance lighthouse - asset optimization

Now we’re back to GitHub levels of performance.

Service Worker and Manifest

Service worker is a recent web technology which enables things like push notifications, background sync, caching, etc. There’s a good overview here. I found a great tutorial on service worker with Jekyll here.

Web App Manifest is another best practice for progressive web applications. In general, they provide metadata and allows users to “install” your site, similar to a native mobile application.

Here is the lighthouse score before having a service worker and a robust manifest:

before service worker and manifest

Here are the results after:

after service worker and manifest



Most of my room for improvement here had to do with:

I’m not a designer, so I found a couple great tools to help in this area. I installed a the aXe chrome extension. It adds a new tab to DevTools and will point out accessibility issues. I also used this online tool to help compare color contrast.

Here are the results after:

after contrast

Room for Improvement

My best practices score seems to be out of my control:

'window.webkitStorageInfo' is deprecated. Please use 'navigator.webkitTemporaryStorage' or 'navigator.webkitPersistentStorage' instead.

TypeError: Math.max is not a function at PerformanceObserver.window.PerformanceObserver.entryList (<anonymous>:8:30)

I couldn’t track down the culprit, but I suspect it’s Chrome or some extension.

My performance score is almost 100, but is currently docked for CSS blocking paint by 250 milliseconds. I’m pretty happy with this score as is, but perhaps in the future I’ll optimize this further.

It would also be great to integrate lighthouse into CI, also for another time.

Wrapping Up

I know this is a pretty trivial web site, but making it progressive was pretty simple. I’d love to hear about more complicated web applications, or single page web applications and how easy or difficult it is to build and maintain them as progressive web apps.

If you are a Jekyll user and like the Hyde theme, I made a progressive variant that you can use to get started with your site.