From 9c291277239652e7099b608770775a9180c77dd9 Mon Sep 17 00:00:00 2001 From: Vani Date: Thu, 12 Apr 2018 14:41:24 -0700 Subject: [PATCH] docs: document how to enable service worker using ng add command (#23348) PR Close #23348 --- .../guide/service-worker-getting-started.md | 106 +++++------------- aio/content/guide/service-worker-intro.md | 7 +- 2 files changed, 29 insertions(+), 84 deletions(-) diff --git a/aio/content/guide/service-worker-getting-started.md b/aio/content/guide/service-worker-getting-started.md index 9ea8dcf744..ecebada1aa 100644 --- a/aio/content/guide/service-worker-getting-started.md +++ b/aio/content/guide/service-worker-getting-started.md @@ -1,87 +1,35 @@ # Getting started with service workers + +This document explains how to enable Angular service worker support in your CLI projects. It then uses a simple example to show you a service worker in action, demonstrating loading and basic caching. + #### Prerequisites A basic understanding of the following: * [Introduction to Angular service workers](guide/service-worker-intro). +* Angular v6, including Angular CLI v6.
-Beginning in Angular 5.0.0, you can easily enable Angular service worker support in any CLI project. This document explains how to enable Angular service worker support in new and existing projects. It then uses a simple example to show you a service worker in action, demonstrating loading and basic caching. +## Adding a service worker to your project -## Adding a service worker to a new application - -If you're generating a new CLI project, you can use the CLI to set up the Angular service worker as part of creating the project. To do so, add the `--service-worker` flag to the `ng new` command: +To set up the Angular service worker in your project, use the CLI command `ng add @angular/pwa`. It takes care of configuring your app to use service workers by adding the `service-worker` package along +with setting up the necessary support files. ```sh -ng new my-project --service-worker +ng add @angular/pwa --project *project-name* ``` -The `--service-worker` flag takes care of configuring your app to -use service workers by adding the `service-worker` package along -with setting up the necessary files to support service workers. -For information on the details, see the following section -which covers the process in detail as it shows you how to add a -service worker manually to an existing app. +The above command completes the following actions: + +1. Adds the `@angular/service-worker` package. +2. Enables service worker build support in the CLI. +3. Imports and registers the service worker in the app module. +4. Creates the service worker configuration file called `ngsw-config.json` which specifies the caching behaviors and other settings. - -## Adding a service worker to an existing app - -To add a service worker to an existing app: - -1. Add the service worker package. -2. Enable service worker build support in the CLI. -3. Import and register the service worker. -4. Create the service worker configuration file, which specifies the caching behaviors and other settings. -5. Build the project. - -### Step 1: Add the service worker package - -Add the package `@angular/service-worker`, using the yarn utility as shown here: - -```sh -yarn add @angular/service-worker -``` - -### Step 2: Enable service worker build support in the CLI - -To enable the Angular service worker, the CLI must generate an Angular service worker manifest at build time. To cause the CLI to generate the manifest for an existing project, set the `serviceWorker` flag to `true` in the project's `.angular-cli.json` file as shown here: - -```sh -ng set apps.0.serviceWorker=true -``` - -### Step 3: Import and register the service worker - -To import and register the Angular service worker: - -At the top of the root module, `src/app/app.module.ts`, import `ServiceWorkerModule` and `environment`. - - - - -Add `ServiceWorkerModule` to the `@NgModule` `imports` array. Use the `register()` helper to take care of registering the service worker, taking care to disable the service worker when not running in production mode. - - - -The file `ngsw-worker.js` is the name of the prebuilt service worker script, which the CLI copies into `dist/` to deploy along with your server. - -### Step 4: Create the configuration file, `ngsw-config.json` - -The Angular CLI needs a service worker configuration file, called `ngsw-config.json`. The configuration file controls how the service worker caches files and data -resources. - -You can begin with the boilerplate version from the CLI, which configures sensible defaults for most applications. - -Alternately, save the following as `src/ngsw-config.json`: - - - -### Step 5: Build the project - -Finally, build the project: + Now, build the project: ```sh ng build --prod @@ -92,17 +40,18 @@ The CLI project is now set up to use the Angular service worker. ## Service worker in action: a tour -This section demonstrates a service worker in action, -using an example application. +This section demonstrates a service worker in action, +using an example application. ### Serving with `http-server` Because `ng serve` does not work with service workers, you must use a separate HTTP server to test your project locally. You can use any HTTP server. The example below uses the [http-server](https://www.npmjs.com/package/http-server) package from npm. To reduce the possibility of conflicts, test on a dedicated port. -To serve the app, start `http-server` and specify the directory containing your web files and the port: +To serve with `http-server`, change to the directory containing your web files and start the web server: ```sh -http-server dist -p 8080 +cd dist +http-server -p 8080 ``` ### Initial load @@ -113,7 +62,7 @@ With the server running, you can point your browser at http://localhost:8080/. Y ### Simulating a network issue -To simulate a network issue, disable network interaction for your application. In Chrome: +To simulate a network issue, disable network interaction for your application. In Chrome: 1. Select **Tools** > **Developer Tools** (from the Chrome menu located at the top right corner). 2. Go to the **Network tab**. @@ -125,9 +74,9 @@ To simulate a network issue, disable network interaction for your application. I Now the app has no access to network interaction. -For applications that do not use the Angular service worker, refreshing now would display Chrome's Internet disconnected page that says "There is no Internet connection". +For applications that do not use the Angular service worker, refreshing now would display Chrome's Internet disconnected page that says "There is no Internet connection". -With the addition of an Angular service worker, the application behavior changes. On a refresh, the page loads normally. +With the addition of an Angular service worker, the application behavior changes. On a refresh, the page loads normally. If you look at the Network tab, you can verify that the service worker is active. @@ -149,12 +98,12 @@ Notice that all of the files the browser needs to render this application are ca ### Making changes to your application -Now that you've seen how service workers cache your application, the -next step is understanding how updates work. +Now that you've seen how service workers cache your application, the +next step is understanding how updates work. 1. If you're testing in an incognito window, open a second blank tab. This will keep the incognito and the cache state alive during your test. -2. Close the application tab, but not the window. This should also close the Developer Tools. +2. Close the application tab, but not the window. This should also close the Developer Tools. 3. Shut down `http-server`. @@ -168,7 +117,8 @@ next step is understanding how updates work. ```sh ng build --prod -http-server dist -p 8080 +cd dist +http-server -p 8080 ``` ### Updating your application in the browser diff --git a/aio/content/guide/service-worker-intro.md b/aio/content/guide/service-worker-intro.md index 679ed0b9fc..7e1934a33d 100644 --- a/aio/content/guide/service-worker-intro.md +++ b/aio/content/guide/service-worker-intro.md @@ -25,17 +25,12 @@ The Angular service worker's behavior follows that design goal: * Updates happen in the background, relatively quickly after changes are published. The previous version of the application is served until an update is installed and ready. * The service worker conserves bandwidth when possible. Resources are only downloaded if they've changed. -To support these behaviors, the Angular service worker loads a *manifest* file from the server. The manifest describes the resources to cache and includes hashes of every file's contents. When an update to the application is deployed, the contents of the manifest change, informing the service worker that a new version of the application should be downloaded and cached. This manifest is generated from a user-provided configuration file called `ngsw-config.json`, by using a build tool such as the Angular CLI. +To support these behaviors, the Angular service worker loads a *manifest* file from the server. The manifest describes the resources to cache and includes hashes of every file's contents. When an update to the application is deployed, the contents of the manifest change, informing the service worker that a new version of the application should be downloaded and cached. This manifest is generated from a CLI-generated configuration file called `ngsw-config.json`. Installing the Angular service worker is as simple as including an `NgModule`. In addition to registering the Angular service worker with the browser, this also makes a few services available for injection which interact with the service worker and can be used to control it. For example, an application can ask to be notified when a new update becomes available, or an application can ask the service worker to check the server for available updates. ## Prerequisites -To use Angular service workers, you must have the following Angular and CLI versions: - -* Angular 5.0.0 or later. -* Angular CLI 1.6.0 or later. - Your application must run in a web browser that supports service workers. Currently, the latest versions of Chrome and Firefox are supported. To learn about other browsers that are service worker ready, see the [Can I Use](http://caniuse.com/#feat=serviceworkers) page. ## Related resources