diff --git a/docusaurus/docs/making-a-progressive-web-app.md b/docusaurus/docs/making-a-progressive-web-app.md new file mode 100644 index 00000000..d59f0923 --- /dev/null +++ b/docusaurus/docs/making-a-progressive-web-app.md @@ -0,0 +1,105 @@ +--- +id: making-a-progressive-web-app +title: Making a Progressive Web App +--- + +The production build has all the tools necessary to generate a first-class +[Progressive Web App](https://developers.google.com/web/progressive-web-apps/), +but **the offline/cache-first behavior is opt-in only**. By default, +the build process will generate a service worker file, but it will not be +registered, so it will not take control of your production web app. + +In order to opt-in to the offline-first behavior, developers should look for the +following in their [`src/index.js`](src/index.js) file: + +```js +// If you want your app to work offline and load faster, you can change +// unregister() to register() below. Note this comes with some pitfalls. +// Learn more about service workers: http://bit.ly/CRA-PWA +serviceWorker.unregister(); +``` + +As the comment states, switching `serviceWorker.unregister()` to +`serviceWorker.register()` will opt you in to using the service worker. + +### Why Opt-in? + +Offline-first Progressive Web Apps are faster and more reliable than traditional web pages, and provide an engaging mobile experience: + +- All static site assets are cached so that your page loads fast on subsequent visits, regardless of network connectivity (such as 2G or 3G). Updates are downloaded in the background. +- Your app will work regardless of network state, even if offline. This means your users will be able to use your app at 10,000 feet and on the subway. +- On mobile devices, your app can be added directly to the user's home screen, app icon and all. This eliminates the need for the app store. + +However, they [can make debugging deployments more challenging](https://github.com/facebook/create-react-app/issues/2398) so, starting with Create React App 2, service workers are opt-in. + +The [`workbox-webpack-plugin`](https://developers.google.com/web/tools/workbox/modules/workbox-webpack-plugin) +is integrated into production configuration, +and it will take care of generating a service worker file that will automatically +precache all of your local assets and keep them up to date as you deploy updates. +The service worker will use a [cache-first strategy](https://developers.google.com/web/fundamentals/instant-and-offline/offline-cookbook/#cache-falling-back-to-network) +for handling all requests for local assets, including +[navigation requests](https://developers.google.com/web/fundamentals/primers/service-workers/high-performance-loading#first_what_are_navigation_requests) +for your HTML, ensuring that your web app is consistently fast, even on a slow +or unreliable network. + +### Offline-First Considerations + +If you do decide to opt-in to service worker registration, please take the +following into account: + +1. Service workers [require HTTPS](https://developers.google.com/web/fundamentals/getting-started/primers/service-workers#you_need_https), + although to facilitate local testing, that policy + [does not apply to `localhost`](http://stackoverflow.com/questions/34160509/options-for-testing-service-workers-via-http/34161385#34161385). + If your production web server does not support HTTPS, then the service worker + registration will fail, but the rest of your web app will remain functional. + +1. Service workers are [not supported](https://jakearchibald.github.io/isserviceworkerready/#moar) + in older web browsers. Service worker registration [won't be attempted](src/registerServiceWorker.js) + on browsers that lack support. + +1. The service worker is only enabled in the [production environment](#deployment), + e.g. the output of `npm run build`. It's recommended that you do not enable an + offline-first service worker in a development environment, as it can lead to + frustration when previously cached assets are used and do not include the latest + changes you've made locally. + +1. If you _need_ to test your offline-first service worker locally, build + the application (using `npm run build`) and run a simple http server from your + build directory. After running the build script, `create-react-app` will give + instructions for one way to test your production build locally and the [deployment instructions](#deployment) have + instructions for using other methods. _Be sure to always use an + incognito window to avoid complications with your browser cache._ + +1. Users aren't always familiar with offline-first web apps. It can be useful to + [let the user know](https://developers.google.com/web/fundamentals/instant-and-offline/offline-ux#inform_the_user_when_the_app_is_ready_for_offline_consumption) + when the service worker has finished populating your caches (showing a "This web + app works offline!" message) and also let them know when the service worker has + fetched the latest updates that will be available the next time they load the + page (showing a "New content is available; please refresh." message). Showing + this messages is currently left as an exercise to the developer, but as a + starting point, you can make use of the logic included in [`src/registerServiceWorker.js`](src/registerServiceWorker.js), which + demonstrates which service worker lifecycle events to listen for to detect each + scenario, and which as a default, just logs appropriate messages to the + JavaScript console. + +1. By default, the generated service worker file will not intercept or cache any + cross-origin traffic, like HTTP [API requests](#integrating-with-an-api-backend), + images, or embeds loaded from a different domain. + +### Progressive Web App Metadata + +The default configuration includes a web app manifest located at +[`public/manifest.json`](public/manifest.json), that you can customize with +details specific to your web application. + +When a user adds a web app to their homescreen using Chrome or Firefox on +Android, the metadata in [`manifest.json`](public/manifest.json) determines what +icons, names, and branding colors to use when the web app is displayed. +[The Web App Manifest guide](https://developers.google.com/web/fundamentals/engage-and-retain/web-app-manifest/) +provides more context about what each field means, and how your customizations +will affect your users' experience. + +Progressive web apps that have been added to the homescreen will load faster and +work offline when there's an active service worker. That being said, the +metadata from the web app manifest will still be used regardless of whether or +not you opt-in to service worker registration. diff --git a/docusaurus/docs/user-guide.md b/docusaurus/docs/user-guide.md index f6a2469d..671f07c1 100644 --- a/docusaurus/docs/user-guide.md +++ b/docusaurus/docs/user-guide.md @@ -11,116 +11,9 @@ You can find the most recent version of this guide [here](https://github.com/fac ## Table of Contents -- [Making a Progressive Web App](#making-a-progressive-web-app) - - [Why Opt-in?](#why-opt-in) - - [Offline-First Considerations](#offline-first-considerations) - - [Progressive Web App Metadata](#progressive-web-app-metadata) - [Advanced Configuration](#advanced-configuration) - [Alternatives to Ejecting](#alternatives-to-ejecting) -## Making a Progressive Web App - -The production build has all the tools necessary to generate a first-class -[Progressive Web App](https://developers.google.com/web/progressive-web-apps/), -but **the offline/cache-first behavior is opt-in only**. By default, -the build process will generate a service worker file, but it will not be -registered, so it will not take control of your production web app. - -In order to opt-in to the offline-first behavior, developers should look for the -following in their [`src/index.js`](src/index.js) file: - -```js -// If you want your app to work offline and load faster, you can change -// unregister() to register() below. Note this comes with some pitfalls. -// Learn more about service workers: http://bit.ly/CRA-PWA -serviceWorker.unregister(); -``` - -As the comment states, switching `serviceWorker.unregister()` to -`serviceWorker.register()` will opt you in to using the service worker. - -### Why Opt-in? - -Offline-first Progressive Web Apps are faster and more reliable than traditional web pages, and provide an engaging mobile experience: - -- All static site assets are cached so that your page loads fast on subsequent visits, regardless of network connectivity (such as 2G or 3G). Updates are downloaded in the background. -- Your app will work regardless of network state, even if offline. This means your users will be able to use your app at 10,000 feet and on the subway. -- On mobile devices, your app can be added directly to the user's home screen, app icon and all. This eliminates the need for the app store. - -However, they [can make debugging deployments more challenging](https://github.com/facebook/create-react-app/issues/2398) so, starting with Create React App 2, service workers are opt-in. - -The [`workbox-webpack-plugin`](https://developers.google.com/web/tools/workbox/modules/workbox-webpack-plugin) -is integrated into production configuration, -and it will take care of generating a service worker file that will automatically -precache all of your local assets and keep them up to date as you deploy updates. -The service worker will use a [cache-first strategy](https://developers.google.com/web/fundamentals/instant-and-offline/offline-cookbook/#cache-falling-back-to-network) -for handling all requests for local assets, including -[navigation requests](https://developers.google.com/web/fundamentals/primers/service-workers/high-performance-loading#first_what_are_navigation_requests) -for your HTML, ensuring that your web app is consistently fast, even on a slow -or unreliable network. - -### Offline-First Considerations - -If you do decide to opt-in to service worker registration, please take the -following into account: - -1. Service workers [require HTTPS](https://developers.google.com/web/fundamentals/getting-started/primers/service-workers#you_need_https), - although to facilitate local testing, that policy - [does not apply to `localhost`](http://stackoverflow.com/questions/34160509/options-for-testing-service-workers-via-http/34161385#34161385). - If your production web server does not support HTTPS, then the service worker - registration will fail, but the rest of your web app will remain functional. - -1. Service workers are [not supported](https://jakearchibald.github.io/isserviceworkerready/#moar) - in older web browsers. Service worker registration [won't be attempted](src/registerServiceWorker.js) - on browsers that lack support. - -1. The service worker is only enabled in the [production environment](#deployment), - e.g. the output of `npm run build`. It's recommended that you do not enable an - offline-first service worker in a development environment, as it can lead to - frustration when previously cached assets are used and do not include the latest - changes you've made locally. - -1. If you _need_ to test your offline-first service worker locally, build - the application (using `npm run build`) and run a simple http server from your - build directory. After running the build script, `create-react-app` will give - instructions for one way to test your production build locally and the [deployment instructions](#deployment) have - instructions for using other methods. _Be sure to always use an - incognito window to avoid complications with your browser cache._ - -1. Users aren't always familiar with offline-first web apps. It can be useful to - [let the user know](https://developers.google.com/web/fundamentals/instant-and-offline/offline-ux#inform_the_user_when_the_app_is_ready_for_offline_consumption) - when the service worker has finished populating your caches (showing a "This web - app works offline!" message) and also let them know when the service worker has - fetched the latest updates that will be available the next time they load the - page (showing a "New content is available; please refresh." message). Showing - this messages is currently left as an exercise to the developer, but as a - starting point, you can make use of the logic included in [`src/registerServiceWorker.js`](src/registerServiceWorker.js), which - demonstrates which service worker lifecycle events to listen for to detect each - scenario, and which as a default, just logs appropriate messages to the - JavaScript console. - -1. By default, the generated service worker file will not intercept or cache any - cross-origin traffic, like HTTP [API requests](#integrating-with-an-api-backend), - images, or embeds loaded from a different domain. - -### Progressive Web App Metadata - -The default configuration includes a web app manifest located at -[`public/manifest.json`](public/manifest.json), that you can customize with -details specific to your web application. - -When a user adds a web app to their homescreen using Chrome or Firefox on -Android, the metadata in [`manifest.json`](public/manifest.json) determines what -icons, names, and branding colors to use when the web app is displayed. -[The Web App Manifest guide](https://developers.google.com/web/fundamentals/engage-and-retain/web-app-manifest/) -provides more context about what each field means, and how your customizations -will affect your users' experience. - -Progressive web apps that have been added to the homescreen will load faster and -work offline when there's an active service worker. That being said, the -metadata from the web app manifest will still be used regardless of whether or -not you opt-in to service worker registration. - ## Advanced Configuration You can adjust various development and production settings by setting environment variables in your shell or with [.env](#adding-development-environment-variables-in-env). diff --git a/docusaurus/website/sidebars.json b/docusaurus/website/sidebars.json index dd5bc75b..a2ac89ab 100644 --- a/docusaurus/website/sidebars.json +++ b/docusaurus/website/sidebars.json @@ -39,7 +39,8 @@ "using-https-in-development", "generating-dynamic-meta-tags-on-the-server", "pre-rendering-into-static-html-files", - "injecting-data-from-the-server-into-the-page" + "injecting-data-from-the-server-into-the-page", + "making-a-progressive-web-app" ], "Testing": ["running-tests", "debugging-tests"], "Deployment": ["publishing-components-to-npm", "deployment"],