5 lines
12 KiB
JSON
5 lines
12 KiB
JSON
{
|
|
"id": "guide/service-worker-getting-started",
|
|
"title": "Getting started with service workers",
|
|
"contents": "\n\n\n<div class=\"github-links\">\n <a href=\"https://github.com/angular/angular/edit/master/aio/content/guide/service-worker-getting-started.md?message=docs%3A%20describe%20your%20change...\" aria-label=\"Suggest Edits\" title=\"Suggest Edits\"><i class=\"material-icons\" aria-hidden=\"true\" role=\"img\">mode_edit</i></a>\n</div>\n\n\n<div class=\"content\">\n <h1 id=\"getting-started-with-service-workers\">Getting started with service workers<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-getting-started#getting-started-with-service-workers\"><i class=\"material-icons\">link</i></a></h1>\n<p>This document explains how to enable Angular service worker support in projects that you created with the <a href=\"cli\">Angular CLI</a>. It then uses a simple example to show you a service worker in action, demonstrating loading and basic caching.</p>\n<h4 id=\"prerequisites\">Prerequisites<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-getting-started#prerequisites\"><i class=\"material-icons\">link</i></a></h4>\n<p>A basic understanding of the information in <a href=\"guide/service-worker-intro\">Introduction to Angular service workers</a>.</p>\n<h2 id=\"adding-a-service-worker-to-your-project\">Adding a service worker to your project<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-getting-started#adding-a-service-worker-to-your-project\"><i class=\"material-icons\">link</i></a></h2>\n<p>To set up the Angular service worker in your project, use the CLI command <code>ng add @angular/pwa</code>. It takes care of configuring your app to use service workers by adding the <code>service-worker</code> package along\nwith setting up the necessary support files.</p>\n<code-example language=\"sh\">\nng add @angular/pwa --project *project-name*\n</code-example>\n<p>The above command completes the following actions:</p>\n<ol>\n<li>Adds the <code>@angular/service-worker</code> package to your project.</li>\n<li>Enables service worker build support in the CLI.</li>\n<li>Imports and registers the service worker in the app module.</li>\n<li>\n<p>Updates the <code>index.html</code> file:</p>\n<ul>\n<li>Includes a link to add the <code>manifest.webmanifest</code> file.</li>\n<li>Adds meta tags for <code>theme-color</code>.</li>\n</ul>\n</li>\n<li>Installs icon files to support the installed Progressive Web App (PWA).</li>\n<li>Creates the service worker configuration file called <a href=\"/guide/service-worker-config\"><code>ngsw-config.json</code></a>, which specifies the caching behaviors and other settings.</li>\n</ol>\n<p> Now, build the project:</p>\n<code-example language=\"sh\">\nng build\n</code-example>\n<p>The CLI project is now set up to use the Angular service worker.</p>\n<h2 id=\"service-worker-in-action-a-tour\">Service worker in action: a tour<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-getting-started#service-worker-in-action-a-tour\"><i class=\"material-icons\">link</i></a></h2>\n<p>This section demonstrates a service worker in action,\nusing an example application.</p>\n<h3 id=\"serving-with-http-server\">Serving with <code>http-server</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-getting-started#serving-with-http-server\"><i class=\"material-icons\">link</i></a></h3>\n<p>Because <code>ng serve</code> 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 <a href=\"https://www.npmjs.com/package/http-server\">http-server</a> package from npm. To reduce the possibility of conflicts and avoid serving stale content, test on a dedicated port and disable caching.</p>\n<p>To serve the directory containing your web files with <code>http-server</code>, run the following command:</p>\n<code-example language=\"sh\">\nhttp-server -p 8080 -c-1 dist/<project-name>\n</code-example>\n<h3 id=\"initial-load\">Initial load<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-getting-started#initial-load\"><i class=\"material-icons\">link</i></a></h3>\n<p>With the server running, you can point your browser at <a href=\"http://localhost:8080/\">http://localhost:8080/</a>. Your application should load normally.</p>\n<p><strong>Tip:</strong> When testing Angular service workers, it's a good idea to use an incognito or private window in your browser to ensure the service worker doesn't end up reading from a previous leftover state, which can cause unexpected behavior.</p>\n<div class=\"alert is-helpful\">\n<p><strong>Note:</strong>\nIf you are not using HTTPS, the service worker will only be registered when accessing the app on <code>localhost</code>.</p>\n</div>\n<h3 id=\"simulating-a-network-issue\">Simulating a network issue<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-getting-started#simulating-a-network-issue\"><i class=\"material-icons\">link</i></a></h3>\n<p>To simulate a network issue, disable network interaction for your application. In Chrome:</p>\n<ol>\n<li>Select <strong>Tools</strong> > <strong>Developer Tools</strong> (from the Chrome menu located at the top right corner).</li>\n<li>Go to the <strong>Network tab</strong>.</li>\n<li>Check the <strong>Offline box</strong>.</li>\n</ol>\n<div class=\"lightbox\">\n <img src=\"generated/images/guide/service-worker/offline-checkbox.png\" alt=\"The offline checkbox in the Network tab is checked\" width=\"600\" height=\"62\">\n</div>\n<p>Now the app has no access to network interaction.</p>\n<p>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\".</p>\n<p>With the addition of an Angular service worker, the application behavior changes. On a refresh, the page loads normally.</p>\n<p>If you look at the Network tab, you can verify that the service worker is active.</p>\n<div class=\"lightbox\">\n <img src=\"generated/images/guide/service-worker/sw-active.png\" alt=\"Requests are marked as from ServiceWorker\" width=\"630\" height=\"112\">\n</div>\n<p>Notice that under the \"Size\" column, the requests state is <code>(from ServiceWorker)</code>. This means that the resources are not being loaded from the network. Instead, they are being loaded from the service worker's cache.</p>\n<h3 id=\"whats-being-cached\">What's being cached?<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-getting-started#whats-being-cached\"><i class=\"material-icons\">link</i></a></h3>\n<p>Notice that all of the files the browser needs to render this application are cached. The <code>ngsw-config.json</code> boilerplate configuration is set up to cache the specific resources used by the CLI:</p>\n<ul>\n<li><code>index.html</code>.</li>\n<li><code>favicon.ico</code>.</li>\n<li>Build artifacts (JS and CSS bundles).</li>\n<li>Anything under <code>assets</code>.</li>\n<li>Images and fonts directly under the configured <code>outputPath</code> (by default <code>./dist/<project-name>/</code>) or <code>resourcesOutputPath</code>. See <a href=\"cli/build\"><code>ng build</code></a> for more information about these options.</li>\n</ul>\n<div class=\"alert is-helpful\">\nPay attention to two key points:\n<ol>\n<li>\n<p>The generated <code>ngsw-config.json</code> includes a limited list of cacheable fonts and images extensions. In some cases, you might want to modify the glob pattern to suit your needs.</p>\n</li>\n<li>\n<p>If <code>resourcesOutputPath</code> or <code>assets</code> paths are modified after the generation of configuration file, you need to change the paths manually in <code>ngsw-config.json</code>.</p>\n</li></ol></div>\n\n\n<h3 id=\"making-changes-to-your-application\">Making changes to your application<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-getting-started#making-changes-to-your-application\"><i class=\"material-icons\">link</i></a></h3>\n<p>Now that you've seen how service workers cache your application, the\nnext step is understanding how updates work. Let's make a change to the application, and watch the service worker install the update:</p>\n<ol>\n<li>\n<p>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.</p>\n</li>\n<li>\n<p>Close the application tab, but not the window. This should also close the Developer Tools.</p>\n</li>\n<li>\n<p>Shut down <code>http-server</code>.</p>\n</li>\n<li>\n<p>Open <code>src/app/app.component.html</code> for editing.</p>\n</li>\n<li>\n<p>Change the text <code>Welcome to {{title}}!</code> to <code>Bienvenue à {{title}}!</code>.</p>\n</li>\n<li>\n<p>Build and run the server again:</p>\n</li>\n</ol>\n<code-example language=\"sh\">\nng build\nhttp-server -p 8080 -c-1 dist/<project-name>\n</code-example>\n<h3 id=\"updating-your-application-in-the-browser\">Updating your application in the browser<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-getting-started#updating-your-application-in-the-browser\"><i class=\"material-icons\">link</i></a></h3>\n<p>Now look at how the browser and service worker handle the updated application.</p>\n<ol>\n<li>Open <a href=\"http://localhost:8080\">http://localhost:8080</a> again in the same window. What happens?</li>\n</ol>\n<div class=\"lightbox\">\n <img src=\"generated/images/guide/service-worker/welcome-msg-en.png\" alt=\"It still says Welcome to Service Workers!\" width=\"411\" height=\"248\">\n</div>\n<p>What went wrong? Nothing, actually. The Angular service worker is doing its job and serving the version of the application that it has <strong>installed</strong>, even though there is an update available. In the interest of speed, the service worker doesn't wait to check for updates before it serves the application that it has cached.</p>\n<p>If you look at the <code>http-server</code> logs, you can see the service worker requesting <code>/ngsw.json</code>. This is how the service worker checks for updates.</p>\n<ol start=\"2\">\n<li>Refresh the page.</li>\n</ol>\n<div class=\"lightbox\">\n <img src=\"generated/images/guide/service-worker/welcome-msg-fr.png\" alt=\"The text has changed to say Bienvenue à app!\" width=\"393\" height=\"240\">\n</div>\n<p>The service worker installed the updated version of your app <em>in the background</em>, and the next time the page is loaded or reloaded, the service worker switches to the latest version.</p>\n<h2 id=\"more-on-angular-service-workers\">More on Angular service workers<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-getting-started#more-on-angular-service-workers\"><i class=\"material-icons\">link</i></a></h2>\n<p>You may also be interested in the following:</p>\n<ul>\n<li><a href=\"guide/service-worker-communications\">Communicating with service workers</a>.</li>\n</ul>\n\n \n</div>\n\n<!-- links to this doc:\n - guide/service-worker-communications\n - guide/service-worker-intro\n-->\n<!-- links from this doc:\n - /guide/service-worker-config\n - cli\n - cli/build\n - guide/service-worker-communications\n - guide/service-worker-getting-started#adding-a-service-worker-to-your-project\n - guide/service-worker-getting-started#getting-started-with-service-workers\n - guide/service-worker-getting-started#initial-load\n - guide/service-worker-getting-started#making-changes-to-your-application\n - guide/service-worker-getting-started#more-on-angular-service-workers\n - guide/service-worker-getting-started#prerequisites\n - guide/service-worker-getting-started#service-worker-in-action-a-tour\n - guide/service-worker-getting-started#serving-with-http-server\n - guide/service-worker-getting-started#simulating-a-network-issue\n - guide/service-worker-getting-started#updating-your-application-in-the-browser\n - guide/service-worker-getting-started#whats-being-cached\n - guide/service-worker-intro\n - http://localhost:8080\n - http://localhost:8080/\n - https://github.com/angular/angular/edit/master/aio/content/guide/service-worker-getting-started.md?message=docs%3A%20describe%20your%20change...\n - https://www.npmjs.com/package/http-server\n-->"
|
|
} |