A step by step tutorial to create a Progressive Web App with Ruby on Rails and Webpacker

If you Google for this topic you will find different tutorials on how to realise a Progressive Web App with Rails. I was really not happy with any of the solutions I found so far: I wanted a solution purely based on Webpack. 

In this article, I will suggest to you how to realise a Progressive Web App (PWA) using the latest Webpacker and the latest Rails release. 

This technique uses just a simple npm package and supports any Modern Rails Application and therefore we will define a new concept: "The Progressive Rails App" (PRA). 
The solution I provide does not perform any workaround by serving the service workers through a controller or by skipping the Webpack pipeline.

If you already know what a PWA is, you can skip directly to Getting Started, otherwise, the next chapter is meant for you.

What is a PWA (for Rails developers)

There are some points that must be fulfilled, in order to consider our application a PWA. Once all these points are respected, the users will be able to install the app on their mobile devices as a standard app. In addition, it will be soon possible to publish your PWA on the Play Store or install it on Desktop.

Let's see these points one by one, from the Rails developer point of view:

It loads instantly, also offline

A service worker must be registered in our application so that it can be loaded also in the absence of an internet connection. This tutorial focuses a lot on how to configure a Service Worker for our Rails app, and we'll do it using Webpacker.

Site is served over HTTPS

For a Rails developer, it simply means to have config.force_ssl = true inside the production.rb configuration. Your website will be served over https, and this requirement will be fulfilled.

Responsive design

Many frontend libraries are available to simplify the design of a responsive application. In a previous article, I explained why you should get rid of Sprockets and use Webpack also for CSS and other static resources. If you did that, you can simply use an npm package to install Bootstrap or Bulma to help you designing your frontend.

manifest.json

This file, that you'll have to place inside the public folder, will contain all the information necessary to install the app on the device of your users.

Getting Started

Start a brand new Rails app (or use you existing one):

rails new progressive-rails-app --skip-sprockets

and enable HTTPS for production in your config/environments/production.rb file.
This is important because one of the requirements for a PWA is that it runs on https.
If you are starting from scratch, here are some commands to create some content. We add a simple CRUD for Posts, to start testing our application:

bundle exec rails g scaffold Post title:string content:text
bundle exec rails db:migrate

And point the root page to hit:

root 'posts#index'

You can also add some seeds:

5.times do |i|
  Post.create(title: "Post #{i}", content: 'A lot of stuff')
end

Now that we have some data and a working application, we can start adding what it takes for it to be considered a PWA.

manifest.json

If you debug your app from the Google Chrome Console you'll see that your app doesn't contain a Manifest

Let's create a Manifest file. This is the starting point of every PWA.

Add the following to your application.html.erb template:

<link rel="manifest" href="/manifest.json">

And create a manifest.json in the public folder of the project. The manifest should contain all the minimal entries to avoid warnings in the browser. Here is an example:

# manifest.json example
{
  "short_name": "PWA",
  "name": "Progressive Web App",
  "icons": [
    {
      "src": "/icons/android-chrome-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icons/android-chrome-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ],
  "start_url": "/",
  "background_color": "#3367D6",
  "display": "standalone",
  "scope": "/",
  "theme_color": "#3367D6"
}

You can generate all the icons you need from https://www.favicon-generator.org/ and place them in a public/icons folder.

Adapting the Webpacker configuration

At the time of writing this article, the provided, default, configuration of Webpacker doesn't allow us to write a Progressive Web App. 

The main reason is that Service Workers should reside in the public folder, while all the resources are compiled inside the public/packs folder. 

We need to customize the Webpacker configuration in order to:

• keep compiling all resources in the public/packs folder;
• compile Service Workers in the public folder without appending an hash at the end of the name;
• make webpack-dev-server listen to the whole public folder to Hot Reload your content also when Service Workers change.

I adapted the @rails/webpacker configuration and published it as an npm package. This package will allow you to use all the power of Webpack and advanced features like Hot Module Reloading, while developing your Progressive Rails App. It tackles exactly the points listed above.

Install the webpacker-pwa npm package with yarn add webpacker-pwa and change config/webpack/environment.js to the following:

const { resolve } = require('path');
const { config, environment, Environment } = require('@rails/webpacker');
const WebpackerPwa = require('webpacker-pwa');
new WebpackerPwa(config, environment);
module.exports = environment;

and add the following to webpacker.json:

service_workers_entry_path: service_workers

service_workers is the folder where we will write our service worker(s). 
If you configured it correctly, when running bin/webpack you should see:

webpacker-pwa is configured but no service workers are available.

The first Service Worker

Create a service-worker.js in the app/javascript/service_workers folder with the following debug content:

self.addEventListener('install', function(event) {
    console.log('Service Worker installing.');
});

self.addEventListener('activate', function(event) {
    console.log('Service Worker activated.');
});
self.addEventListener('fetch', function(event) {
    console.log('Service Worker fetching.');
});

and register it in application.js with:

window.addEventListener('load', () => {
  navigator.serviceWorker.register('/service-worker.js').then(registration => {
    console.log('ServiceWorker registered: ', registration);

    var serviceWorker;
    if (registration.installing) {
      serviceWorker = registration.installing;
      console.log('Service worker installing.');
    } else if (registration.waiting) {
      serviceWorker = registration.waiting;
      console.log('Service worker installed & waiting.');
    } else if (registration.active) {
      serviceWorker = registration.active;
      console.log('Service worker active.');
    }
  }).catch(registrationError => {
    console.log('Service worker registration failed: ', registrationError);
  });
});

this will allow us to see if the service worker is working correctly.

Note: do not use webpack-dev-server for now. Is not yet working, but we will get there!

Note 2: add public/service-worker.js* to .gitignore. You shouldn't push this file directly. It's compiled by webpack.

If you did everything correctly you will see the following in the Chrome DevTools console:

And on the Chrome console, you should see:

ServiceWorker registered:  
Service Worker installing.
Service worker installing.
Service Worker activating.

Now, when we deploy our application, and SSL is available, you should see the install icon on the browser.

If you want to test this locally, you can use a service like ngrok.com, just run ngrok http 3000 on the root folder of your project.

If you receive a "Blocked host" error, you can disable this check temporarily by setting config.hosts = nil inside config/environments/development.rb.

Your Progressive Rails App

And that's it! You have your first Service Worker running and your app is now officially a Progressive Rails App! 🎉

From now on, you can follow any Progressive Web App tutorial to start implementing your services, and if you are already experienced with Service Workers, you can start coding as you are used to. But here I will give you some more details about how to get the maximum out of your Progressive Rails App and implement a couple of features that you might need most of the times.

Push Notifications

That's why you are here, right? You want to send push notifications to your users as well, right? You also want your app to show the super annoying message "Wants to send you push notifications" and start annoying your customers, right? Let's do it!

Ask for permission

Start by asking for permissions, without this, you cannot send any notification. You should do that after registering your service worker, so change the code we wrote in application.js as follows:

navigator.serviceWorker.register('/service-worker.js').then(registration => {
  console.log('ServiceWorker registered: ', registration);

  // all code from before

  window.Notification.requestPermission().then(permission => {    
    if(permission !== 'granted'){
      throw new Error('Permission not granted for Notification');
    }
  });
});

You should handle all the cases properly, but this is out of scope for this tutorial, please refer to this one for example, to get some more details about how/when to ask for permissions and how to manage all possible responses from the user.

Click "Allow" to give notifications permissions and if you refresh the page, it won't ask you anymore, since it already obtained permission before.

Subscribe to notification service

You need to generate a pair of public/private keys to send notifications. Again follow the article linked above for the details about why.

yarn global add web-push
web-push generate-vapid-keys

Now change our service-worker.js to subscribe to the push manager and react to push notifications:

function urlB64ToUint8Array(base64String) {
  const padding = '='.repeat((4 - base64String.length % 4) % 4);
  const base64 = (base64String + padding)
    .replace(/\-/g, '+')
    .replace(/_/g, '/');

  const rawData = atob(base64);
  const outputArray = new Uint8Array(rawData.length);

  for (var i = 0; i < rawData.length; ++i) {
    outputArray[i] = rawData.charCodeAt(i);
  }
  return outputArray;
}

self.addEventListener('install', function(event) {
  console.log('Service Worker installing.');
});

self.addEventListener('activate', async function(event) {
  console.log('Service Worker activated.');
  try {
    const applicationServerKey = urlB64ToUint8Array('<YOUR_PUBLIC_KEY_HERE>')
    const options = { applicationServerKey, userVisibleOnly: true }
    const subscription = await self.registration.pushManager.subscribe(options)
    console.log(JSON.stringify(subscription))
  } catch (err) {
    console.log('Error', err)
  }
});
self.addEventListener('fetch', function(event) {
  console.log('Service Worker fetching.');
});
self.addEventListener('push', function(event) {
  console.log('[Service Worker] Push Received.');
  console.log(`[Service Worker] Push had this data: "${event.data.text()}"`);

  const title = 'A nice title';
  const options = {
    body: event.data.text(),
    icon: 'images/icon.png',
    badge: 'images/badge.png'
  };

  event.waitUntil(self.registration.showNotification(title, options));
});

Every time you change your service worker you need to manually unregister it from the Chrome Application tab in Developers' tools, and refresh the page.

You should see in the Browser console:

{ "endpoint":"https://fcm.googleapis.com/fcm/send/...",
  "expirationTime":null,
  "keys":{
    "p256dh":"...",
    "auth":"..." }
}

Save them. You'll need them later.

From the DevTools, from the same window where you unregister your service worker, you can now send a test push notification.

Send notifications from ruby

In short, that's easy. Add the webpush gem and use the following:

require 'webpush'

Webpush.payload_send(
    message: 'Hello from ruby',
    endpoint: <ENDPOINT-HERE>,
    p256dh: <P256DH-HERE>,
    auth: <AUTH-HERE>,
    vapid: {
        subject: 'Hello from ruby',
        public_key: <PUBLIC-KEY>,
        private_key: <PRIVATE-KEY>
    }
)

You can simply save this as notifications.rb and run it with ruby notifications.rb to make a test.

This means that when you subscribe on the frontend, you need to save the endpoint and all other information in the backend, and associate them (maybe) with your users.

Offline mode

When internet is not available we want to still display something to the user. Let's see how to do that. I will cover a simple offline page with an image, after that is up to you. This is the article where I took inspiration from.

Start by creating an offline page:

get 'offline', to: 'home#offline', as: :offline

class HomeController < ApplicationController
  def offline
    render 'offline', layout: false
  end
end

we render a very simple view, without using the layout used for the rest of the application.

html
  head    
    css:
      body {
        background-color: #00a4cd;
        color: #ffffff;
        padding: 4rem 2rem;
      }

      .text-center {
        text-align: center;
      }
  body
    .text-center
      = image_pack_tag 'logo_white.svg'
    h1.text-center
      ' You need a working internet connection to use Agreeder
    p.text-center
      ' Offline mode is not supported yet

and edit your service worker as follows:

const OFFLINE_VERSION = 1;
const CACHE_NAME = 'offline';
const OFFLINE_URL = 'offline';

self.addEventListener('install', function (event) {
  event.waitUntil((async () => {
    const cache = await caches.open(CACHE_NAME);
    // Setting {cache: 'reload'} in the new request will ensure that the response
    // isn't fulfilled from the HTTP cache; i.e., it will be from the network.
    await cache.add(new Request(OFFLINE_URL, {cache: 'reload'}));
  })());
});

self.addEventListener('activate', async function (event) {
  event.waitUntil((async () => {
  // Enable navigation preload if it's supported.
  // See https://developers.google.com/web/updates/2017/02/navigation-preload
    if ('navigationPreload' in self.registration) {
      await self.registration.navigationPreload.enable();
    }
  })());

  // Tell the active service worker to take control of the page immediately.
  self.clients.claim();
});

self.addEventListener('fetch', function (event) {
  // We only want to call event.respondWith() if this is a navigation request
  // for an HTML page.
    event.respondWith((async () => {
      try {
        // First, try to use the navigation preload response if it's supported.
        const preloadResponse = await event.preloadResponse;
        if (preloadResponse) {
          return preloadResponse;
        }

        return await caches.match(event.request) || await fetch(event.request);
      } catch (error) {
        // catch is only triggered if an exception is thrown, which is likely
        // due to a network error.
        // If fetch() returns a valid HTTP response with a response code in
        // the 4xx or 5xx range, the catch() will NOT be called.
        console.log('Fetch failed; returning offline page instead.', error);

        const cache = await caches.open(CACHE_NAME);
        const cachedResponse = await cache.match(OFFLINE_URL);
        return cachedResponse;
      }
    })());
});

Reload your Service Worker and refresh the page. Now, you can enable Offline mode in Chrome DevTools and you should have an Offline Page!

To show the image we need, of course, to cache it as well. Adding it to the cache is easy, simply add it where you also add the offline page:

await cache.add(new Request('/packs/media/images/logo_white-a925d045a774f93a59598e709010d411.svg', {cache: 'reload'}));

Reload the service worker, refresh the page in "Online mode" and check if the asset is cached correctly on Chrome DevTools:

This technique works but is not the best out there, since you need to specify the exact name of the asset to cache and, if the asset changes or the offline page changes, you need to remember to also update the Service Worker. I will explain in a different article how to tackle that, but if you are in a hurry and want to find out before, you can look into Google Workbox

Hot Module Reload

webpack-dev-server and hot module reloading will still work, but unfortunately not for our service workers. Webpacker middleware, by default, redirects only requests to /packs to webpack-dev-server, and since our service workers live in the public folder directory, they cannot be served.

I developed a small gem that adds a middleware and allows you to serve also service workers. It's called webpacker-pwa. Add it to your Gemfile, or copy-paste the middleware in your project from the Github project.

This Rack middleware will intercept requests for Service Workers and serve them through webpack-dev-server.

Note that the "refreshed" service worker will be loaded but not activated. This is correct! You can automatically refresh it by adding the following:

self.addEventListener('install', function(event) {
  self.skipWaiting();
});

You can now start coding your service worker and take full advantage of Hot Module Reloading!

The Progressive Rails App

You are ready to start coding your Progressive Rails App. 
I wanted to show you how easy is to start with Service Workers on Rails, and I hope that Webpacker will soon allow that out-of-the-box, maybe taking inspiration from webpacker-pwa.
Now that you know how to write a service worker, send push notification, and implement an offline page, you can start reading specific guides to implement what you need. I hope this Guide could help you start making your Rails app a Progressive Rails App, and you will be more confident from now on, that this is a very easy task.

For other tutorials regarding Webpacker, check my previous blog posts on dev.to and medium.com.

Thanks Renuo AG, as always, for supporting me in writing this article and for all the improvements in the Rails ecosystem.

Take a look into Agreeder, is a very cool app to take decisions by sorting your preferences.

Please also check Gifcoins, out internal reward system at Renuo. It's a free and easy tool to compliment each other at your company, and a different way to say "Thank you!"