• What's this project?
• What changes were made?
  • Adding in a service worker
  • Adding in a Web App Manifest
  • Adding in a GitHub deployment step
• What additional changes might be needed?
  • I've added in React Router and now my URLs don't work offline
  • I'm using cross-origin APIs or resources, and they aren't working while offline
• How can I try out the Progressive Web App?
• How can I report bugs?

What's this project?

This is one approach to taking a project created with the create-react-app tool and adding in some additional bits commonly found in Progressive Web Apps.

What changes were made?

GitHub's visual diff shows all the changes needed to make a Progressive Web App. They include:

Adding in a service worker

The service worker that's generated will ensure that the local images, JavaScript, CSS, and HTML for your web app will be cached and continue to work, even when a user is offline. It also will save bandwidth and improve performance while users are online, by only making network requests for those local resources when there's actually an update that's been deployed.

A sw-precache dependency was added to package.json, and the npm run build command has been updated to call the sw-precache command-line interface after the webpack build process is completed.

sw-precache generates a service-worker.js file that will automatically cache the other static files in the build/ directory, and keep them up to date when you deploy changes.

Code to register the service worker was also added to index.html.

The service worker is only generated as part of the production build, so the development environment will continue to work as before. When running a production server locally, make sure you use a different port than 3000, to ensure the service worker does not inadvertantly take control of the development environment.

Adding in a Web App Manifest

A web app manifest provides metadata about your web app. Along with a service worker, your web app needs a manifest in order to trigger the Add to Homescreen prompt (in supported browsers).

Adding in a GitHub deployment step

While not strictly necessary, a new npm run gh-pages script was added in, relying on the gh-pages module.

Additionally, the "homepage": "./" property was set in package.json, to ensure that relative paths are used in the generated output. This plays nicely with both GitHub Pages hosting and should work well with other hosting environments, too.

What additional changes might be needed?

By following the changes made, you should end up with a Progressive Web App using React that's ready to be deployed to any static hosting environment. However, if you add in additional functionality to the starting point, you may need to update your sw-precache settings to ensure the service worker behaves properly.

I've added in React Router and now my URLs don't work offline

If you've followed the suggestions in the create-react-app documentation and added in React Router using the History API to manage URLs, then you need to tell the service worker that navigations to all the random URLs your web app now supports should actually be fulfilled with the cached copy of your index.html. You can do this with the navigateFallback option in sw-precache.

Assuming you're using the sw-precache command-line interface, the additional flag would look like --navigate-fallback='index.html'.

I'm using cross-origin APIs or resources, and they aren't working while offline

The service worker generated by default by sw-precache only handles requests for local, static resources, like your images, JavaScript, CSS, and HTML. Requests made at runtime for, e.g., APIs or images that live on other servers won't be handled by the default sw-precache setup. This means they will stop working offline.

The sw-toolbox allows you to set up runtime caching strategies, using URL patterns to determine what strategy and cache sizes to use. sw-precache provides an easy way to use sw-toolbox via the runtimeCaching configuration option.

Because the configuration can get complex, it's best not to attempt to provide it via a command-line flag. Instead, you can transition to a JSON config file to set up runtime caching, along with all the other sw-precache options. This sample config file can be used as a starting point, and you'd add in the --config-file=sw-precache-config.json flag to your build script to get sw-precache to start using that file.

How can I try out the Progressive Web App?

The code from this project is deployed at https://jeffy.info/create-react-pwa/

How can I report bugs?

If you've found a bug in the code output by create-react-app, please let the project maintainers know in their issue tracker.

If you've found an issue specific to the Progressive Web App bits (the service worker, the Web App Manifest, etc.), then please let us know in this project's issue tracker.