Making Gatsby a PWA: Service Worker and Web App Manifest

Progressive Web Apps (PWAs) allow developers to deliver an app-like experience to the user. Paired with the top-notch performance of Gatsby.js, and you get a blazing fast website.

The steps in this guide assume you have a working Gatsby project. So if you haven’t already, you can get started with Gatsby by following along the Gatsby First Steps article. You’ll be diving right into the site configuration.

The Web App Manifest

The Web App Manifest is a brief JSON file with metadata about your web app. It provides some instructions for the browser on how to behave when installed on the user’s device.

Adding a web app manifest to Gatsby can be done by installing the gatsby-plugin-manifest:

$ npm install --save gatsby-plugin-manifest

Then, we can add the plugin to our Gatsby configuration:

module.exports = {
  ...
  plugins: [
    {
      resolve: `gatsby-plugin-manifest`,
      options: {
        name: `Alligator.io`,
        short_name: `Alligator`,
        start_url: `/`,
        background_color: `#FFF`,
        theme_color: `#FAE042`,
        display: `standalone`,
      },
    },
  ],
}

Now let’s take a look at some of the options to configure our web app manifest.

Icons

We can define a set of icons for the browser to use when the app is saved to the user’s home screen. There are three options available for us to do so.

1. Automatic

There are two automatic options available. With the first, we need to provide Gatsby.js with the largest icon size with the following prerequisites:

• At least 512x512 in size.
• Squared. If it’s not transparent, bars will be automatically added to make it so.
• One of the following formats: JPEG, PNG, WebP, TIFF, GIF or SVG.

We then add the following line to the plugin’s options:

icon: `src/images/icon.png`,

Gatsby will generate a pre-configured set of icons from the provided source.

2. Hybrid

The hybrid option gives us a bit more flexibility over which icons are automatically generated. We follow the same prerequisite as before for the source file. And add the following to the plugin options:

icon: `src/images/icon.png`, 
icons: [
  {
    src: `/favicons/android-chrome-192x192.png`,
    sizes: `192x192`,
    type: `image/png`,
  },
  {
    src: `/favicons/android-chrome-512x512.png`,
    sizes: `512x512`,
    type: `image/png`,
  },
],

Here, we can provide the icons array configurations for the desired icon sizes.

3. Manual

With the manual mode, we’re responsible for providing the desired icons in the static folder, as well as defining the entire web app manifest.

We specify the icon sizes in the plugin’s options, while omitting the icon setting.

icons: [
  {
    src: `/favicons/android-chrome-192x192.png`,
    sizes: `192x192`,
    type: `image/png`,
  },
  {
    src: `/favicons/android-chrome-512x512.png`,
    sizes: `512x512`,
    type: `image/png`,
  },
], 

There are a few more options available to override the defaults, such as localization and data fetching, which you can find in on package’s page on the npm website. I’d also recommend visiting the Web App Manifest fundamentals for further insight into what each option can do.

The Service Worker

Now that we have our web app manifest ready to go, let’s take a look at how we can generate a Service Worker for our site. To get started, let’s install the gatsby-plugin-offline:

$ npm install --save gatsby-plugin-offline

Then, we can add the following to our Gatsby configuration:

plugins: [`gatsby-plugin-offline`]

The plugin creates a service worker for us by leveraging Google’s Workbox library. We get automatic file caching, enabling pages to be available offline after the user’s first visit.

If there is a specific need to your site that requires a little extra from the service worker, you can override the default options with a workbox config. However, keep in mind that changes to the defaults could break offline support. Be sure to go over the linked resources for further information.

Removing the Service Worker

If you find that offline functionality needs to be turned off, you can remove the service worker by utilizing the gatsby-plugin-remove-serviceworker.

To do so, you’ll need to first install the removal plugin and uninstall gatsby-plugin-offline:

$ npm install gatsby-plugin-remove-serviceworker
$ npm uninstall gatsby-plugin-offline

Then, you can update the Gatsby config:

 plugins: [
-  `gatsby-plugin-offline`,
+  `gatsby-plugin-remove-serviceworker`,
 ]

This will ensure the service worker is properly unregistered.

Conclusion

Adding offline support to Gatsby opens up a lot of possibilities. Things like offline browsing, cached assets for faster load times, and saving websites to mobile home screens for easier reach. There’s a lot more you can do with these plugins and I highly encourage you to read the resources linked throughout the article.