- What's this project?
- What changes were made?
- What additional changes might be needed?
- How can I try out the Progressive Web App?
- How can I report bugs?
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.
GitHub's visual diff shows all the changes needed to make a Progressive Web App. They include:
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.
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).
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.
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.
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'.
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=sw-precache-config.json flag to your build script to get
sw-precache to start using that file.
The code from this project is deployed at https://jeffy.info/create-react-pwa/
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.