Using Custom Workbox Service Workers with Create-React-App (without ejecting, no third-party libraries)

Currently, there’s no way to add a custom service worker with the Workbox InjectManifest plugin in create-react-app (2.x). There are a few solutions floating around, but if you don’t want to eject, here’s a simple way to add Workbox to your Create-React-App (2.x) workflow.

The Issue: This PR would allow adding custom configurations to the built-in service worker that uses the GenerateSW plugin in create-react-app 2.x (cra). However, among many other things, the default Workbox GenerateSW plugin configured with CRA, doesn’t allow you to add custom caching rules. For this, you will need to configure Workbox to use the InjectManifest mode in CRA, and currently, there’s no clear documentation on how to achieve this.

TL;DR – This involves not using the SW generated by Create-React-App but generating your own SW. The SW is configured to use the InjectManifest plugin and the Workbox build workflow. Build commands are added to the react-build script in package.json.

Step 1: Make sure you register for a SW in the main index.js file of your app

Register for a Service Worker in CRA by editingsrc/index.js and then change serviceWorker.unregister(); to serviceWorker.register();

This tells CRA to look in the src/serviceWorker.js, and load the default Service Worker.

Step 2: Tell CRA to Load a Custom Service Worker

Next, open src/serviceWorker.js and look at the method export function register(config). Here, you’ll find the loadevent listener (around line 34) window.addEventListener('load', () => { which provides the reference to the Service Worker for react.

You need to change the swURL to point to a new file which will be created in the build step at a later stage.

So, change this – const swUrl = ``${process.env.PUBLIC_URL}/service-worker.js``;
to const swUrl = ``${process.env.PUBLIC_URL}/sw.js``;

 window.addEventListener('load', () => {
      // const swUrl = `${process.env.PUBLIC_URL}/service-worker.js`;
      // Add a custom service worker until CRA team provides a way to inject config into workbox.
      const swUrl = `${process.env.PUBLIC_URL}/sw.js`;

      if (isLocalhost) {

Step3: Create the Custom Service Worker Template and Build Files

Now, create two files under src/ – sw-build.js and sw.js

sw-build.js – Provides the build instructions for the custom Service Worker generation.

sw-template.js – Is the template for Workbox Service Worker. Custom caching rules go here.

Step 4 – Add the Service Worker Build Instructions with InjectManifest Mode

In src/sw-build.js add the build instructions as provided by
 Google’s injectManifest example here.

const workboxBuild = require('workbox-build');
// NOTE: This should be run *AFTER* all your assets are built
const buildSW = () => {
  // This will return a Promise
  return workboxBuild.injectManifest({
    swSrc: 'src/sw-template.js', // this is your sw template file
    swDest: 'build/sw.js', // this will be created in the build step
    globDirectory: 'build',
    globPatterns: [
      '**\/*.{js,css,html,png}',
    ]
  }).then(({count, size, warnings}) => {
    // Optionally, log any warnings and details.
    warnings.forEach(console.warn);
    console.log(`${count} files will be precached, totaling ${size} bytes.`);
  });
}
buildSW();

In the code snippet above, you’ll notice that the reference for swSRC is the newly created sw-template.js file that you created in the previous step. By using the injectManifest mode you have full control of your caching rules. So, the next step is to provide your caching rules.
The swDest directive tells Workbox to create the custom Service Worker in the build directory of create-react-app.

Step 5 – Provide Custom Caching Rules in src/sw-template.js

You now need to add the injection point and caching rules for Workbox. Workbox will load these from the src/sw-template.js during the Service Worker generation. Here’s a generic code snippet for caching rules that you can customize based on your requirements.

Add the following to src/sw-template.js

if ('function' === typeof importScripts) {
  importScripts(
    'https://storage.googleapis.com/workbox-cdn/releases/3.5.0/workbox-sw.js'
  );
  /* global workbox */
  if (workbox) {
    console.log('Workbox is loaded');

    /* injection point for manifest files.  */
    workbox.precaching.precacheAndRoute([]);

/* custom cache rules*/
workbox.routing.registerNavigationRoute('/index.html', {
      blacklist: [/^\/_/, /\/[^\/]+\.[^\/]+$/],
    });

workbox.routing.registerRoute(
      /\.(?:png|gif|jpg|jpeg)$/,
      workbox.strategies.cacheFirst({
        cacheName: 'images',
        plugins: [
          new workbox.expiration.Plugin({
            maxEntries: 60,
            maxAgeSeconds: 30 * 24 * 60 * 60, // 30 Days
          }),
        ],
      })
    );

} else {
    console.log('Workbox could not be loaded. No Offline support');
  }
}

Now, all you need is to add the build instructions for the custom Service Worker in package.json of your React application.

Step 6: Install the workbox-build dependency

Install workbox-build dependency by running
npm install workbox-build --save-dev

Note: workbox-build may already be included in your node_modules, but running the above will also make an entry in your package.json, and let’s you be aware of it.

Step 7: Add the Workbox Build Instructions for CRA

You now need to specify the Workbox build step in package.json

To do this, edit package.jsonand add a new entry in the scripts section – "build-sw": "node ./src/sw-build.js"

This will run a node command to build the custom service worker using the instructions from src/sw-build.js

Next, change the default React build command: "build": "react-scripts build
to "build": "react-scripts build && npm run build-sw

This is how it should look –

   },
  "scripts": {
    "start": "react-scripts start",
    "build-sw": "node ./src/sw-build.js",
    "build": "react-scripts build && npm run build-sw",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },

Final Step – Cleanup Default CRA Service Worker

When your run npm run build you will see the the file sw.js inside your build folder.

The default CRA generated service-worker.js will continue to be there, but it won’t be used because we changed the swURL in step2. So it’s a good idea to do some cleanup by modifying the build step above as below:

   },
  "scripts": {
    "start": "react-scripts start",
    "build-sw": "node ./src/sw-build.js",
    "clean-cra-sw": "rm -f build/precache-manifest.*.js && rm -f build/service-worker.js",
    "build": "react-scripts build && npm run build-sw && npm run clean-cra-sw",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
},

/**
 * UPDATE
 * thanks to @do in the comments
 *
 * in sw-build.js you need to update the glob patterns before adding clean-cra-sw,
 * else the files removed will be added to the precache of workbox.
 */

globPatterns: [
'**\/!(service-worker|precache-manifest.*).{js,css,html,png}',
],

That’s it. When you run npm run build your React app will now use your custom Service Worker!

You can also follow this issue on Github for Guidelines to use Workbox with Create-React-App (2.x)