5 lines
23 KiB
JSON
5 lines
23 KiB
JSON
{
|
|
"id": "guide/service-worker-config",
|
|
"title": "Service worker configuration",
|
|
"contents": "\n\n\n<div class=\"github-links\">\n <a href=\"https://github.com/angular/angular/edit/master/aio/content/guide/service-worker-config.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=\"service-worker-configuration\">Service worker configuration<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#service-worker-configuration\"><i class=\"material-icons\">link</i></a></h1>\n<h4 id=\"prerequisites\">Prerequisites<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#prerequisites\"><i class=\"material-icons\">link</i></a></h4>\n<p>A basic understanding of the following:</p>\n<ul>\n<li><a href=\"guide/service-worker-devops\">Service Worker in Production</a>.</li>\n</ul>\n<hr>\n<p>The <code>ngsw-config.json</code> configuration file specifies which files and data URLs the Angular service\nworker should cache and how it should update the cached files and data. The <a href=\"cli\">Angular CLI</a>\nprocesses the configuration file during <code>ng build</code>. Manually, you can process it with the\n<code>ngsw-config</code> tool (where <code><project-name></code> is the name of the project being built):</p>\n<code-example language=\"sh\">\n./node_modules/.bin/ngsw-config ./dist/<project-name> ./ngsw-config.json [/base/href]\n</code-example>\n<p>The configuration file uses the JSON format. All file paths must begin with <code>/</code>, which corresponds\nto the deployment directory—usually <code>dist/<project-name></code> in CLI projects.</p>\n<a id=\"glob-patterns\"></a>\n<p>Unless otherwise noted, patterns use a limited glob format:</p>\n<ul>\n<li><code>**</code> matches 0 or more path segments.</li>\n<li><code>*</code> matches 0 or more characters excluding <code>/</code>.</li>\n<li><code>?</code> matches exactly one character excluding <code>/</code>.</li>\n<li>The <code>!</code> prefix marks the pattern as being negative, meaning that only files that don't match the pattern will be included.</li>\n</ul>\n<p>Example patterns:</p>\n<ul>\n<li><code>/**/*.html</code> specifies all HTML files.</li>\n<li><code>/*.html</code> specifies only HTML files in the root.</li>\n<li><code>!/**/*.map</code> exclude all sourcemaps.</li>\n</ul>\n<p>Each section of the configuration file is described below.</p>\n<h2 id=\"appdata\"><code>appData</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#appdata\"><i class=\"material-icons\">link</i></a></h2>\n<p>This section enables you to pass any data you want that describes this particular version of the app.\nThe <code><a href=\"api/service-worker/SwUpdate\" class=\"code-anchor\">SwUpdate</a></code> service includes that data in the update notifications. Many apps use this section to provide additional information for the display of UI popups, notifying users of the available update.</p>\n<a id=\"index-file\"></a>\n<h2 id=\"index\"><code>index</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#index\"><i class=\"material-icons\">link</i></a></h2>\n<p>Specifies the file that serves as the index page to satisfy navigation requests. Usually this is <code>/index.html</code>.</p>\n<h2 id=\"assetgroups\"><code>assetGroups</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#assetgroups\"><i class=\"material-icons\">link</i></a></h2>\n<p><em>Assets</em> are resources that are part of the app version that update along with the app. They can include resources loaded from the page's origin as well as third-party resources loaded from CDNs and other external URLs. As not all such external URLs may be known at build time, URL patterns can be matched.</p>\n<p>This field contains an array of asset groups, each of which defines a set of asset resources and the policy by which they are cached.</p>\n<code-example language=\"json\">\n{\n \"assetGroups\": [\n {\n ...\n },\n {\n ...\n }\n ]\n}\n</code-example>\n<div class=\"alert is-helpful\">\n<p>When the ServiceWorker handles a request, it checks asset groups in the order in which they appear in <code>ngsw-config.json</code>.\nThe first asset group that matches the requested resource handles the request.</p>\n<p>It is recommended that you put the more specific asset groups higher in the list.\nFor example, an asset group that matches <code>/foo.js</code> should appear before one that matches <code>*.js</code>.</p>\n</div>\n<p>Each asset group specifies both a group of resources and a policy that governs them. This policy determines when the resources are fetched and what happens when changes are detected.</p>\n<p>Asset groups follow the Typescript interface shown here:</p>\n<code-example language=\"typescript\">\ninterface AssetGroup {\n name: string;\n installMode?: 'prefetch' | 'lazy';\n updateMode?: 'prefetch' | 'lazy';\n resources: {\n files?: string[];\n urls?: string[];\n };\n cacheQueryOptions?: {\n ignoreSearch?: boolean;\n };\n}\n</code-example>\n<h3 id=\"name\"><code>name</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#name\"><i class=\"material-icons\">link</i></a></h3>\n<p>A <code>name</code> is mandatory. It identifies this particular group of assets between versions of the configuration.</p>\n<h3 id=\"installmode\"><code>installMode</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#installmode\"><i class=\"material-icons\">link</i></a></h3>\n<p>The <code>installMode</code> determines how these resources are initially cached. The <code>installMode</code> can be either of two values:</p>\n<ul>\n<li>\n<p><code>prefetch</code> tells the Angular service worker to fetch every single listed resource while it's caching the current version of the app. This is bandwidth-intensive but ensures resources are available whenever they're requested, even if the browser is currently offline.</p>\n</li>\n<li>\n<p><code>lazy</code> does not cache any of the resources up front. Instead, the Angular service worker only caches resources for which it receives requests. This is an on-demand caching mode. Resources that are never requested will not be cached. This is useful for things like images at different resolutions, so the service worker only caches the correct assets for the particular screen and orientation.</p>\n</li>\n</ul>\n<p>Defaults to <code>prefetch</code>.</p>\n<h3 id=\"updatemode\"><code>updateMode</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#updatemode\"><i class=\"material-icons\">link</i></a></h3>\n<p>For resources already in the cache, the <code>updateMode</code> determines the caching behavior when a new version of the app is discovered. Any resources in the group that have changed since the previous version are updated in accordance with <code>updateMode</code>.</p>\n<ul>\n<li>\n<p><code>prefetch</code> tells the service worker to download and cache the changed resources immediately.</p>\n</li>\n<li>\n<p><code>lazy</code> tells the service worker to not cache those resources. Instead, it treats them as unrequested and waits until they're requested again before updating them. An <code>updateMode</code> of <code>lazy</code> is only valid if the <code>installMode</code> is also <code>lazy</code>.</p>\n</li>\n</ul>\n<p>Defaults to the value <code>installMode</code> is set to.</p>\n<h3 id=\"resources\"><code>resources</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#resources\"><i class=\"material-icons\">link</i></a></h3>\n<p>This section describes the resources to cache, broken up into the following groups:</p>\n<ul>\n<li>\n<p><code>files</code> lists patterns that match files in the distribution directory. These can be single files or glob-like patterns that match a number of files.</p>\n</li>\n<li>\n<p><code>urls</code> includes both URLs and URL patterns that will be matched at runtime. These resources are not fetched directly and do not have content hashes, but they will be cached according to their HTTP headers. This is most useful for CDNs such as the Google Fonts service.<br>\n<em>(Negative glob patterns are not supported and <code>?</code> will be matched literally; i.e. it will not match any character other than <code>?</code>.)</em></p>\n</li>\n</ul>\n<h3 id=\"cachequeryoptions\"><code>cacheQueryOptions</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#cachequeryoptions\"><i class=\"material-icons\">link</i></a></h3>\n<p>These options are used to modify the matching behavior of requests. They are passed to the browsers <code>Cache#match</code> function. See <a href=\"https://developer.mozilla.org/en-US/docs/Web/API/Cache/match\">MDN</a> for details. Currently, only the following options are supported:</p>\n<ul>\n<li><code>ignoreSearch</code>: Ignore query parameters. Defaults to <code>false</code>.</li>\n</ul>\n<h2 id=\"datagroups\"><code>dataGroups</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#datagroups\"><i class=\"material-icons\">link</i></a></h2>\n<p>Unlike asset resources, data requests are not versioned along with the app. They're cached according to manually-configured policies that are more useful for situations such as API requests and other data dependencies.</p>\n<p>This field contains an array of data groups, each of which defines a set of data resources and the policy by which they are cached.</p>\n<code-example language=\"json\">\n{\n \"dataGroups\": [\n {\n ...\n },\n {\n ...\n }\n ]\n}\n</code-example>\n<div class=\"alert is-helpful\">\n<p>When the ServiceWorker handles a request, it checks data groups in the order in which they appear in <code>ngsw-config.json</code>.\nThe first data group that matches the requested resource handles the request.</p>\n<p>It is recommended that you put the more specific data groups higher in the list.\nFor example, a data group that matches <code>/api/foo.json</code> should appear before one that matches <code>/api/*.json</code>.</p>\n</div>\n<p>Data groups follow this Typescript interface:</p>\n<code-example language=\"typescript\">\nexport interface DataGroup {\n name: string;\n urls: string[];\n version?: number;\n cacheConfig: {\n maxSize: number;\n maxAge: string;\n timeout?: string;\n strategy?: 'freshness' | 'performance';\n };\n cacheQueryOptions?: {\n ignoreSearch?: boolean;\n };\n}\n</code-example>\n<h3 id=\"name-1\"><code>name</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#name-1\"><i class=\"material-icons\">link</i></a></h3>\n<p>Similar to <code>assetGroups</code>, every data group has a <code>name</code> which uniquely identifies it.</p>\n<h3 id=\"urls\"><code>urls</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#urls\"><i class=\"material-icons\">link</i></a></h3>\n<p>A list of URL patterns. URLs that match these patterns are cached according to this data group's policy. Only non-mutating requests (GET and HEAD) are cached.</p>\n<ul>\n<li>Negative glob patterns are not supported.</li>\n<li><code>?</code> is matched literally; that is, it matches <em>only</em> the character <code>?</code>.</li>\n</ul>\n<h3 id=\"version\"><code>version</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#version\"><i class=\"material-icons\">link</i></a></h3>\n<p>Occasionally APIs change formats in a way that is not backward-compatible. A new version of the app may not be compatible with the old API format and thus may not be compatible with existing cached resources from that API.</p>\n<p><code>version</code> provides a mechanism to indicate that the resources being cached have been updated in a backwards-incompatible way, and that the old cache entries—those from previous versions—should be discarded.</p>\n<p><code>version</code> is an integer field and defaults to <code>1</code>.</p>\n<h3 id=\"cacheconfig\"><code>cacheConfig</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#cacheconfig\"><i class=\"material-icons\">link</i></a></h3>\n<p>This section defines the policy by which matching requests will be cached.</p>\n<h4 id=\"maxsize\"><code>maxSize</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#maxsize\"><i class=\"material-icons\">link</i></a></h4>\n<p>(required) The maximum number of entries, or responses, in the cache. Open-ended caches can grow in unbounded ways and eventually exceed storage quotas, calling for eviction.</p>\n<h4 id=\"maxage\"><code>maxAge</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#maxage\"><i class=\"material-icons\">link</i></a></h4>\n<p>(required) The <code>maxAge</code> parameter indicates how long responses are allowed to remain in the cache before being considered invalid and evicted. <code>maxAge</code> is a duration string, using the following unit suffixes:</p>\n<ul>\n<li><code>d</code>: days</li>\n<li><code>h</code>: hours</li>\n<li><code>m</code>: minutes</li>\n<li><code>s</code>: seconds</li>\n<li><code>u</code>: milliseconds</li>\n</ul>\n<p>For example, the string <code>3d12h</code> will cache content for up to three and a half days.</p>\n<h4 id=\"timeout\"><code>timeout</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#timeout\"><i class=\"material-icons\">link</i></a></h4>\n<p>This duration string specifies the network timeout. The network timeout is how long the Angular service worker will wait for the network to respond before using a cached response, if configured to do so. <code>timeout</code> is a duration string, using the following unit suffixes:</p>\n<ul>\n<li><code>d</code>: days</li>\n<li><code>h</code>: hours</li>\n<li><code>m</code>: minutes</li>\n<li><code>s</code>: seconds</li>\n<li><code>u</code>: milliseconds</li>\n</ul>\n<p>For example, the string <code>5s30u</code> will translate to five seconds and 30 milliseconds of network timeout.</p>\n<h4 id=\"strategy\"><code>strategy</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#strategy\"><i class=\"material-icons\">link</i></a></h4>\n<p>The Angular service worker can use either of two caching strategies for data resources.</p>\n<ul>\n<li>\n<p><code>performance</code>, the default, optimizes for responses that are as fast as possible. If a resource exists in the cache, the cached version is used, and no network request is made. This allows for some staleness, depending on the <code>maxAge</code>, in exchange for better performance. This is suitable for resources that don't change often; for example, user avatar images.</p>\n</li>\n<li>\n<p><code>freshness</code> optimizes for currency of data, preferentially fetching requested data from the network. Only if the network times out, according to <code>timeout</code>, does the request fall back to the cache. This is useful for resources that change frequently; for example, account balances.</p>\n</li>\n</ul>\n<div class=\"alert is-helpful\">\n<p>You can also emulate a third strategy, <a href=\"https://developers.google.com/web/fundamentals/instant-and-offline/offline-cookbook/#stale-while-revalidate\">staleWhileRevalidate</a>, which returns cached data (if available), but also fetches fresh data from the network in the background for next time.\nTo use this strategy set <code>strategy</code> to <code>freshness</code> and <code>timeout</code> to <code>0u</code> in <code>cacheConfig</code>.</p>\n<p>This will essentially do the following:</p>\n<ol>\n<li>Try to fetch from the network first.</li>\n<li>If the network request does not complete after 0ms (i.e. immediately), fall back to the cache (ignoring cache age).</li>\n<li>Once the network request completes, update the cache for future requests.</li>\n<li>If the resource does not exist in the cache, wait for the network request anyway.</li>\n</ol>\n</div>\n<h3 id=\"cachequeryoptions-1\"><code>cacheQueryOptions</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#cachequeryoptions-1\"><i class=\"material-icons\">link</i></a></h3>\n<p>See <a href=\"guide/service-worker-config#assetgroups\">assetGroups</a> for details.</p>\n<h2 id=\"navigationurls\"><code>navigationUrls</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#navigationurls\"><i class=\"material-icons\">link</i></a></h2>\n<p>This optional section enables you to specify a custom list of URLs that will be redirected to the index file.</p>\n<h3 id=\"handling-navigation-requests\">Handling navigation requests<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#handling-navigation-requests\"><i class=\"material-icons\">link</i></a></h3>\n<p>The ServiceWorker will redirect navigation requests that don't match any <code>asset</code> or <code>data</code> group to the specified <a href=\"guide/service-worker-config#index-file\">index file</a>. A request is considered to be a navigation request if:</p>\n<ol>\n<li>Its <a href=\"https://developer.mozilla.org/en-US/docs/Web/API/Request/mode\">mode</a> is <code>navigation</code>.</li>\n<li>It accepts a <code>text/html</code> response (as determined by the value of the <code>Accept</code> header).</li>\n<li>Its URL matches certain criteria (see below).</li>\n</ol>\n<p>By default, these criteria are:</p>\n<ol>\n<li>The URL must not contain a file extension (i.e. a <code>.</code>) in the last path segment.</li>\n<li>The URL must not contain <code>__</code>.</li>\n</ol>\n<div class=\"alert is-helpful\">\n<p>To configure whether navigation requests are sent through to the network or not, see the <a href=\"guide/service-worker-config#navigation-request-strategy\">navigationRequestStrategy</a> section.</p>\n</div>\n<h3 id=\"matching-navigation-request-urls\">Matching navigation request URLs<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#matching-navigation-request-urls\"><i class=\"material-icons\">link</i></a></h3>\n<p>While these default criteria are fine in most cases, it is sometimes desirable to configure different rules. For example, you may want to ignore specific routes (that are not part of the Angular app) and pass them through to the server.</p>\n<p>This field contains an array of URLs and <a href=\"guide/service-worker-config#glob-patterns\">glob-like</a> URL patterns that will be matched at runtime. It can contain both negative patterns (i.e. patterns starting with <code>!</code>) and non-negative patterns and URLs.</p>\n<p>Only requests whose URLs match <em>any</em> of the non-negative URLs/patterns and <em>none</em> of the negative ones will be considered navigation requests. The URL query will be ignored when matching.</p>\n<p>If the field is omitted, it defaults to:</p>\n<code-example language=\"ts\">\n[\n '/**', // Include all URLs.\n '!/**/*.*', // Exclude URLs to files.\n '!/**/*__*', // Exclude URLs containing `__` in the last segment.\n '!/**/*__*/**', // Exclude URLs containing `__` in any other segment.\n]\n</code-example>\n<a id=\"navigation-request-strategy\"></a>\n<h2 id=\"navigationrequeststrategy\"><code>navigationRequestStrategy</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/service-worker-config#navigationrequeststrategy\"><i class=\"material-icons\">link</i></a></h2>\n<p>This optional property enables you to configure how the service worker handles navigation requests:</p>\n<code-example language=\"json\">\n{\n \"navigationRequestStrategy\": \"freshness\"\n}\n</code-example>\n<p>Possible values:</p>\n<ul>\n<li><code>'performance'</code>: The default setting. Serves the specified <a href=\"guide/service-worker-config#index-file\">index file</a>, which is typically cached.</li>\n<li>\n<p><code>'freshness'</code>: Passes the requests through to the network and falls back to the <code>performance</code> behavior when offline.\nThis value is useful when the server redirects the navigation requests elsewhere using an HTTP redirect (3xx status code).\nReasons for using this value include:</p>\n<ul>\n<li>Redirecting to an authentication website when authentication is not handled by the application.</li>\n<li>Redirecting specific URLs to avoid breaking existing links/bookmarks after a website redesign.</li>\n<li>Redirecting to a different website, such as a server-status page, while a page is temporarily down.</li>\n</ul>\n</li>\n</ul>\n<div class=\"alert is-important\">\n<p>The <code>freshness</code> strategy usually results in more requests sent to the server, which can increase response latency.\nIt is recommended that you use the default performance strategy whenever possible.</p>\n</div>\n\n \n</div>\n\n<!-- links to this doc:\n - guide/service-worker-devops\n - guide/service-worker-intro\n-->\n<!-- links from this doc:\n - api/service-worker/SwUpdate\n - cli\n - guide/service-worker-config#appdata\n - guide/service-worker-config#assetgroups\n - guide/service-worker-config#cacheconfig\n - guide/service-worker-config#cachequeryoptions\n - guide/service-worker-config#cachequeryoptions-1\n - guide/service-worker-config#datagroups\n - guide/service-worker-config#glob-patterns\n - guide/service-worker-config#handling-navigation-requests\n - guide/service-worker-config#index\n - guide/service-worker-config#index-file\n - guide/service-worker-config#installmode\n - guide/service-worker-config#matching-navigation-request-urls\n - guide/service-worker-config#maxage\n - guide/service-worker-config#maxsize\n - guide/service-worker-config#name\n - guide/service-worker-config#name-1\n - guide/service-worker-config#navigation-request-strategy\n - guide/service-worker-config#navigationrequeststrategy\n - guide/service-worker-config#navigationurls\n - guide/service-worker-config#prerequisites\n - guide/service-worker-config#resources\n - guide/service-worker-config#service-worker-configuration\n - guide/service-worker-config#strategy\n - guide/service-worker-config#timeout\n - guide/service-worker-config#updatemode\n - guide/service-worker-config#urls\n - guide/service-worker-config#version\n - guide/service-worker-devops\n - https://developer.mozilla.org/en-US/docs/Web/API/Cache/match\n - https://developer.mozilla.org/en-US/docs/Web/API/Request/mode\n - https://developers.google.com/web/fundamentals/instant-and-offline/offline-cookbook/#stale-while-revalidate\n - https://github.com/angular/angular/edit/master/aio/content/guide/service-worker-config.md?message=docs%3A%20describe%20your%20change...\n-->"
|
|
} |