mirror of
https://github.com/hanzoai/workbox.git
synced 2026-09-24 17:04:35 +00:00
Add inline examples (#3038)
This commit is contained in:
Jeffrey Posnick
@@ -14,7 +14,6 @@ import {rebasePath} from './lib/rebase-path';
|
||||
import {validateGenerateSWOptions} from './lib/validate-options';
|
||||
import {writeSWUsingDefaultTemplate} from './lib/write-sw-using-default-template';
|
||||
|
||||
// eslint-disable-next-line jsdoc/newline-after-description
|
||||
/**
|
||||
* This method creates a list of URLs to precache, referred to as a "precache
|
||||
* manifest", based on the options you provide.
|
||||
@@ -25,171 +24,37 @@ import {writeSWUsingDefaultTemplate} from './lib/write-sw-using-default-template
|
||||
* Based on the precache manifest and the additional configuration, it writes
|
||||
* a ready-to-use service worker file to disk at `swDest`.
|
||||
*
|
||||
* @param {Object} config The configuration to use.
|
||||
*
|
||||
* @param {string} config.globDirectory The local directory you wish to match
|
||||
* `globPatterns` against. The path is relative to the current directory.
|
||||
*
|
||||
* @param {string} config.swDest The path and filename of the service worker file
|
||||
* that will be created by the build process, relative to the current working
|
||||
* directory. It must end in '.js'.
|
||||
*
|
||||
* @param {Array<workbox-build.ManifestEntry>} [config.additionalManifestEntries]
|
||||
* A list of entries to be precached, in addition to any entries that are
|
||||
* generated as part of the build configuration.
|
||||
*
|
||||
* @param {Array<string>} [config.babelPresetEnvTargets=['chrome >= 56']]
|
||||
* The [targets](https://babeljs.io/docs/en/babel-preset-env#targets) to pass to
|
||||
* `babel-preset-env` when transpiling the service worker bundle.
|
||||
*
|
||||
* @param {string} [config.cacheId] An optional ID to be prepended to cache
|
||||
* names. This is primarily useful for local development where multiple sites
|
||||
* may be served from the same `http://localhost:port` origin.
|
||||
*
|
||||
* @param {boolean} [config.cleanupOutdatedCaches=false] Whether or not Workbox
|
||||
* should attempt to identify and delete any precaches created by older,
|
||||
* incompatible versions.
|
||||
*
|
||||
* @param {boolean} [config.clientsClaim=false] Whether or not the service
|
||||
* worker should [start controlling](https://developers.google.com/web/fundamentals/primers/service-workers/lifecycle#clientsclaim)
|
||||
* any existing clients as soon as it activates.
|
||||
*
|
||||
* @param {string} [config.directoryIndex='index.html'] If a navigation request
|
||||
* for a URL ending in `/` fails to match a precached URL, this value will be
|
||||
* appended to the URL and that will be checked for a precache match. This
|
||||
* should be set to what your web server is using for its directory index.
|
||||
*
|
||||
* @param {RegExp} [config.dontCacheBustURLsMatching] Assets that match this will be
|
||||
* assumed to be uniquely versioned via their URL, and exempted from the normal
|
||||
* HTTP cache-busting that's done when populating the precache. While not
|
||||
* required, it's recommended that if your existing build process already
|
||||
* inserts a `[hash]` value into each filename, you provide a RegExp that will
|
||||
* detect that, as it will reduce the bandwidth consumed when precaching.
|
||||
*
|
||||
* @param {boolean} [config.globFollow=true] Determines whether or not symlinks
|
||||
* are followed when generating the precache manifest. For more information, see
|
||||
* the definition of `follow` in the `glob`
|
||||
* [documentation](https://github.com/isaacs/node-glob#options).
|
||||
*
|
||||
* @param {Array<string>} [config.globIgnores=['node_modules/**']]
|
||||
* A set of patterns matching files to always exclude when generating the
|
||||
* precache manifest. For more information, see the definition of `ignore` in the `glob`
|
||||
* [documentation](https://github.com/isaacs/node-glob#options).
|
||||
*
|
||||
* @param {Array<string>} [config.globPatterns=['**.{js,css,html}']]
|
||||
* Files matching any of these patterns will be included in the precache
|
||||
* manifest. For more information, see the
|
||||
* [`glob` primer](https://github.com/isaacs/node-glob#glob-primer).
|
||||
*
|
||||
* @param {boolean} [config.globStrict=true] If true, an error reading a directory when
|
||||
* generating a precache manifest will cause the build to fail. If false, the
|
||||
* problematic directory will be skipped. For more information, see the
|
||||
* definition of `strict` in the `glob`
|
||||
* [documentation](https://github.com/isaacs/node-glob#options).
|
||||
*
|
||||
* @param {Array<RegExp>} [config.ignoreURLParametersMatching=[/^utm_/, /^fbclid$/]]
|
||||
* Any search parameter names that match against one of the RegExp in this array
|
||||
* will be removed before looking for a precache match. This is useful if your
|
||||
* users might request URLs that contain, for example, URL parameters used to
|
||||
* track the source of the traffic.
|
||||
*
|
||||
* @param {Array<string>} [config.importScripts] A list of JavaScript files that
|
||||
* should be passed to [`importScripts()`](https://developer.mozilla.org/en-US/docs/Web/API/WorkerGlobalScope/importScripts)
|
||||
* inside the generated service worker file. This is useful when you want to
|
||||
* let Workbox create your top-level service worker file, but want to include
|
||||
* some additional code, such as a push event listener.
|
||||
*
|
||||
* @param {boolean} [config.inlineWorkboxRuntime=false] Whether the runtime code
|
||||
* for the Workbox library should be included in the top-level service worker,
|
||||
* or split into a separate file that needs to be deployed alongside the service
|
||||
* worker. Keeping the runtime separate means that users will not have to
|
||||
* re-download the Workbox code each time your top-level service worker changes.
|
||||
*
|
||||
* @param {Array<workbox-build.ManifestTransform>} [config.manifestTransforms] One or more
|
||||
* functions which will be applied sequentially against the generated manifest.
|
||||
* If `modifyURLPrefix` or `dontCacheBustURLsMatching` are also specified, their
|
||||
* corresponding transformations will be applied first.
|
||||
*
|
||||
* @param {number} [config.maximumFileSizeToCacheInBytes=2097152] This value can be
|
||||
* used to determine the maximum size of files that will be precached. This
|
||||
* prevents you from inadvertently precaching very large files that might have
|
||||
* accidentally matched one of your patterns.
|
||||
*
|
||||
* @param {string} [config.mode='production'] If set to 'production', then an
|
||||
* optimized service worker bundle that excludes debugging info will be
|
||||
* produced. If not explicitly configured here, the `process.env.NODE_ENV` value
|
||||
* will be used, and failing that, it will fall back to `'production'`.
|
||||
*
|
||||
* @param {object<string, string>} [config.modifyURLPrefix] A mapping of prefixes
|
||||
* that, if present in an entry in the precache manifest, will be replaced with
|
||||
* the corresponding value. This can be used to, for example, remove or add a
|
||||
* path prefix from a manifest entry if your web hosting setup doesn't match
|
||||
* your local filesystem setup. As an alternative with more flexibility, you can
|
||||
* use the `manifestTransforms` option and provide a function that modifies the
|
||||
* entries in the manifest using whatever logic you provide.
|
||||
*
|
||||
* @param {string} [config.navigateFallback] If specified, all
|
||||
* [navigation requests](https://developers.google.com/web/fundamentals/primers/service-workers/high-performance-loading#first_what_are_navigation_requests)
|
||||
* for URLs that aren't precached will be fulfilled with the HTML at the URL
|
||||
* provided. You must pass in the URL of an HTML document that is listed in your
|
||||
* precache manifest. This is meant to be used in a Single Page App scenario, in
|
||||
* which you want all navigations to use common [App Shell HTML](https://developers.google.com/web/fundamentals/architecture/app-shell).
|
||||
*
|
||||
* @param {Array<RegExp>} [config.navigateFallbackDenylist] An optional array
|
||||
* of regular expressions that restricts which URLs the configured
|
||||
* `navigateFallback` behavior applies to. This is useful if only a subset of
|
||||
* your site's URLs should be treated as being part of a
|
||||
* [Single Page App](https://en.wikipedia.org/wiki/Single-page_application). If
|
||||
* both `navigateFallbackDenylist` and `navigateFallbackAllowlist` are
|
||||
* configured, the denylist takes precedent.
|
||||
*
|
||||
* @param {Array<RegExp>} [config.navigateFallbackAllowlist] An optional array
|
||||
* of regular expressions that restricts which URLs the configured
|
||||
* `navigateFallback` behavior applies to. This is useful if only a subset of
|
||||
* your site's URLs should be treated as being part of a
|
||||
* [Single Page App](https://en.wikipedia.org/wiki/Single-page_application). If
|
||||
* both `navigateFallbackDenylist` and `navigateFallbackAllowlist` are
|
||||
* configured, the denylist takes precedent.
|
||||
*
|
||||
* @param {boolean} [config.navigationPreload=false] Whether or not to enable
|
||||
* [navigation preload](https://developers.google.com/web/tools/workbox/modules/workbox-navigation-preload)
|
||||
* in the generated service worker. When set to true, you must also use
|
||||
* `runtimeCaching` to set up an appropriate response strategy that will match
|
||||
* navigation requests, and make use of the preloaded response.
|
||||
*
|
||||
* @param {boolean|Object} [config.offlineGoogleAnalytics=false] Controls
|
||||
* whether or not to include support for
|
||||
* [offline Google Analytics](https://developers.google.com/web/tools/workbox/guides/enable-offline-analytics).
|
||||
* When `true`, the call to `workbox-google-analytics`'s `initialize()` will be
|
||||
* added to your generated service worker. When set to an `Object`, that object
|
||||
* will be passed in to the `initialize()` call, allowing you to customize the
|
||||
* behavior.
|
||||
*
|
||||
* @param {Array<RuntimeCachingEntry>} [config.runtimeCaching]
|
||||
*
|
||||
* @param {boolean} [config.skipWaiting=false] Whether to add an
|
||||
* unconditional call to [`skipWaiting()`](https://developers.google.com/web/fundamentals/primers/service-workers/lifecycle#skip_the_waiting_phase)
|
||||
* to the generated service worker. If `false`, then a `message` listener will
|
||||
* be added instead, allowing you to conditionally call `skipWaiting()` by posting
|
||||
* a message containing {type: 'SKIP_WAITING'}.
|
||||
*
|
||||
* @param {boolean} [config.sourcemap=true] Whether to create a sourcemap
|
||||
* for the generated service worker files.
|
||||
*
|
||||
* @param {Object} [config.templatedURLs] If a URL is rendered based on some
|
||||
* server-side logic, its contents may depend on multiple files or on some other
|
||||
* unique string value. The keys in this object are server-rendered URLs. If the
|
||||
* values are an array of strings, they will be interpreted as `glob` patterns,
|
||||
* and the contents of any files matching the patterns will be used to uniquely
|
||||
* version the URL. If used with a single string, it will be interpreted as
|
||||
* unique versioning information that you've generated for a given URL.
|
||||
*
|
||||
* @return {Promise<{count: number, filePaths: Array<string>, size: number, warnings: Array<string>}>}
|
||||
* A promise that resolves once the service worker and related files
|
||||
* (indicated by `filePaths`) has been written to `swDest`. The `size` property
|
||||
* contains the aggregate size of all the precached entries, in bytes, and the
|
||||
* `count` property contains the total number of precached entries. Any
|
||||
* non-fatal warning messages will be returned via `warnings`.
|
||||
* @example
|
||||
* // The following lists some common options; see the rest of the documentation
|
||||
* // for the full set of options and defaults.
|
||||
* const {count, size, warnings} = await generateSW({
|
||||
* dontCacheBustURLsMatching: [new RegExp('...')],
|
||||
* globDirectory: '...',
|
||||
* globPatterns: ['...', '...'],
|
||||
* maximumFileSizeToCacheInBytes: ...,
|
||||
* navigateFallback: '...',
|
||||
* runtimeCaching: [{
|
||||
* // Routing via a matchCallback function:
|
||||
* urlPattern: ({request, url}) => ...,
|
||||
* handler: '...',
|
||||
* options: {
|
||||
* cacheName: '...',
|
||||
* expiration: {
|
||||
* maxEntries: ...,
|
||||
* },
|
||||
* },
|
||||
* }, {
|
||||
* // Routing via a RegExp:
|
||||
* urlPattern: new RegExp('...'),
|
||||
* handler: '...',
|
||||
* options: {
|
||||
* cacheName: '...',
|
||||
* plugins: [..., ...],
|
||||
* },
|
||||
* }],
|
||||
* skipWaiting: ...,
|
||||
* swDest: '...',
|
||||
* });
|
||||
*
|
||||
* @memberof workbox-build
|
||||
*/
|
||||
|
||||
@@ -10,81 +10,20 @@ import {getFileManifestEntries} from './lib/get-file-manifest-entries';
|
||||
import {GetManifestOptions, GetManifestResult} from './types';
|
||||
import {validateGetManifestOptions} from './lib/validate-options';
|
||||
|
||||
// eslint-disable-next-line jsdoc/newline-after-description
|
||||
/**
|
||||
* This method returns a list of URLs to precache, referred to as a "precache
|
||||
* manifest", along with details about the number of entries and their size,
|
||||
* based on the options you provide.
|
||||
*
|
||||
* @param {Object} config The configuration to use.
|
||||
*
|
||||
* @param {string} config.globDirectory The local directory you wish to match
|
||||
* `globPatterns` against. The path is relative to the current directory.
|
||||
*
|
||||
* @param {Array<workbox-build.ManifestEntry>} [config.additionalManifestEntries]
|
||||
* A list of entries to be precached, in addition to any entries that are
|
||||
* generated as part of the build configuration.
|
||||
*
|
||||
* @param {RegExp} [config.dontCacheBustURLsMatching] Assets that match this will be
|
||||
* assumed to be uniquely versioned via their URL, and exempted from the normal
|
||||
* HTTP cache-busting that's done when populating the precache. While not
|
||||
* required, it's recommended that if your existing build process already
|
||||
* inserts a `[hash]` value into each filename, you provide a RegExp that will
|
||||
* detect that, as it will reduce the bandwidth consumed when precaching.
|
||||
*
|
||||
* @param {boolean} [config.globFollow=true] Determines whether or not symlinks
|
||||
* are followed when generating the precache manifest. For more information, see
|
||||
* the definition of `follow` in the `glob`
|
||||
* [documentation](https://github.com/isaacs/node-glob#options).
|
||||
*
|
||||
* @param {Array<string>} [config.globIgnores=['node_modules/**']]
|
||||
* A set of patterns matching files to always exclude when generating the
|
||||
* precache manifest. For more information, see the definition of `ignore` in the `glob`
|
||||
* [documentation](https://github.com/isaacs/node-glob#options).
|
||||
*
|
||||
* @param {Array<string>} [config.globPatterns=['**.{js,css,html}']]
|
||||
* Files matching any of these patterns will be included in the precache
|
||||
* manifest. For more information, see the
|
||||
* [`glob` primer](https://github.com/isaacs/node-glob#glob-primer).
|
||||
*
|
||||
* @param {boolean} [config.globStrict=true] If true, an error reading a directory when
|
||||
* generating a precache manifest will cause the build to fail. If false, the
|
||||
* problematic directory will be skipped. For more information, see the
|
||||
* definition of `strict` in the `glob`
|
||||
* [documentation](https://github.com/isaacs/node-glob#options).
|
||||
*
|
||||
* @param {Array<workbox-build.ManifestTransform>} [config.manifestTransforms] One or more
|
||||
* functions which will be applied sequentially against the generated manifest.
|
||||
* If `modifyURLPrefix` or `dontCacheBustURLsMatching` are also specified, their
|
||||
* corresponding transformations will be applied first.
|
||||
*
|
||||
* @param {number} [config.maximumFileSizeToCacheInBytes=2097152] This value can be
|
||||
* used to determine the maximum size of files that will be precached. This
|
||||
* prevents you from inadvertently precaching very large files that might have
|
||||
* accidentally matched one of your patterns.
|
||||
*
|
||||
* @param {object<string, string>} [config.modifyURLPrefix] A mapping of prefixes
|
||||
* that, if present in an entry in the precache manifest, will be replaced with
|
||||
* the corresponding value. This can be used to, for example, remove or add a
|
||||
* path prefix from a manifest entry if your web hosting setup doesn't match
|
||||
* your local filesystem setup. As an alternative with more flexibility, you can
|
||||
* use the `manifestTransforms` option and provide a function that modifies the
|
||||
* entries in the manifest using whatever logic you provide.
|
||||
*
|
||||
* @param {Object} [config.templatedURLs] If a URL is rendered based on some
|
||||
* server-side logic, its contents may depend on multiple files or on some other
|
||||
* unique string value. The keys in this object are server-rendered URLs. If the
|
||||
* values are an array of strings, they will be interpreted as `glob` patterns,
|
||||
* and the contents of any files matching the patterns will be used to uniquely
|
||||
* version the URL. If used with a single string, it will be interpreted as
|
||||
* unique versioning information that you've generated for a given URL.
|
||||
*
|
||||
* @return {Promise<{count: number, manifestEntries: Array<workbox-build.ManifestEntry>, size: number, warnings: Array<string>}>}
|
||||
* A promise that resolves once the precache manifest (available in the
|
||||
* `manifestEntries` property) has been determined. The `size` property
|
||||
* contains the aggregate size of all the precached entries, in bytes, and the
|
||||
* `count` property contains the total number of precached entries. Any
|
||||
* non-fatal warning messages will be returned via `warnings`.
|
||||
* @example
|
||||
* // The following lists some common options; see the rest of the documentation
|
||||
* // for the full set of options and defaults.
|
||||
* const {count, manifestEntries, size, warnings} = await getManifest({
|
||||
* dontCacheBustURLsMatching: [new RegExp('...')],
|
||||
* globDirectory: '...',
|
||||
* globPatterns: ['...', '...'],
|
||||
* maximumFileSizeToCacheInBytes: ...,
|
||||
* });
|
||||
*
|
||||
* @memberof workbox-build
|
||||
*/
|
||||
|
||||
@@ -22,7 +22,6 @@ import {replaceAndUpdateSourceMap} from './lib/replace-and-update-source-map';
|
||||
import {translateURLToSourcemapPaths} from './lib/translate-url-to-sourcemap-paths';
|
||||
import {validateInjectManifestOptions} from './lib/validate-options';
|
||||
|
||||
// eslint-disable-next-line jsdoc/newline-after-description
|
||||
/**
|
||||
* This method creates a list of URLs to precache, referred to as a "precache
|
||||
* manifest", based on the options you provide.
|
||||
@@ -33,87 +32,20 @@ import {validateInjectManifestOptions} from './lib/validate-options';
|
||||
* The final service worker file, with the manifest injected, is written to
|
||||
* disk at `swDest`.
|
||||
*
|
||||
* @param {Object} config The configuration to use.
|
||||
* This method will not compile or bundle your `swSrc` file; it just handles
|
||||
* injecting the manifest.
|
||||
*
|
||||
* @param {string} config.globDirectory The local directory you wish to match
|
||||
* `globPatterns` against. The path is relative to the current directory.
|
||||
*
|
||||
* @param {string} config.swDest The path and filename of the service worker file
|
||||
* that will be created by the build process, relative to the current working
|
||||
* directory. It must end in '.js'.
|
||||
*
|
||||
* @param {string} config.swSrc The path and filename of the service worker file
|
||||
* that will be read during the build process, relative to the current working
|
||||
* directory.
|
||||
*
|
||||
* @param {Array<workbox-build.ManifestEntry>} [config.additionalManifestEntries]
|
||||
* A list of entries to be precached, in addition to any entries that are
|
||||
* generated as part of the build configuration.
|
||||
*
|
||||
* @param {RegExp} [config.dontCacheBustURLsMatching] Assets that match this will be
|
||||
* assumed to be uniquely versioned via their URL, and exempted from the normal
|
||||
* HTTP cache-busting that's done when populating the precache. While not
|
||||
* required, it's recommended that if your existing build process already
|
||||
* inserts a `[hash]` value into each filename, you provide a RegExp that will
|
||||
* detect that, as it will reduce the bandwidth consumed when precaching.
|
||||
*
|
||||
* @param {boolean} [config.globFollow=true] Determines whether or not symlinks
|
||||
* are followed when generating the precache manifest. For more information, see
|
||||
* the definition of `follow` in the `glob`
|
||||
* [documentation](https://github.com/isaacs/node-glob#options).
|
||||
*
|
||||
* @param {Array<string>} [config.globIgnores=['node_modules/**']]
|
||||
* A set of patterns matching files to always exclude when generating the
|
||||
* precache manifest. For more information, see the definition of `ignore` in the `glob`
|
||||
* [documentation](https://github.com/isaacs/node-glob#options).
|
||||
*
|
||||
* @param {Array<string>} [config.globPatterns=['**.{js,css,html}']]
|
||||
* Files matching any of these patterns will be included in the precache
|
||||
* manifest. For more information, see the
|
||||
* [`glob` primer](https://github.com/isaacs/node-glob#glob-primer).
|
||||
*
|
||||
* @param {boolean} [config.globStrict=true] If true, an error reading a directory when
|
||||
* generating a precache manifest will cause the build to fail. If false, the
|
||||
* problematic directory will be skipped. For more information, see the
|
||||
* definition of `strict` in the `glob`
|
||||
* [documentation](https://github.com/isaacs/node-glob#options).
|
||||
*
|
||||
* @param {string} [config.injectionPoint='self.__WB_MANIFEST'] The string to
|
||||
* find inside of the `swSrc` file. Once found, it will be replaced by the
|
||||
* generated precache manifest.
|
||||
*
|
||||
* @param {Array<workbox-build.ManifestTransform>} [config.manifestTransforms] One or more
|
||||
* functions which will be applied sequentially against the generated manifest.
|
||||
* If `modifyURLPrefix` or `dontCacheBustURLsMatching` are also specified, their
|
||||
* corresponding transformations will be applied first.
|
||||
*
|
||||
* @param {number} [config.maximumFileSizeToCacheInBytes=2097152] This value can be
|
||||
* used to determine the maximum size of files that will be precached. This
|
||||
* prevents you from inadvertently precaching very large files that might have
|
||||
* accidentally matched one of your patterns.
|
||||
*
|
||||
* @param {object<string, string>} [config.modifyURLPrefix] A mapping of prefixes
|
||||
* that, if present in an entry in the precache manifest, will be replaced with
|
||||
* the corresponding value. This can be used to, for example, remove or add a
|
||||
* path prefix from a manifest entry if your web hosting setup doesn't match
|
||||
* your local filesystem setup. As an alternative with more flexibility, you can
|
||||
* use the `manifestTransforms` option and provide a function that modifies the
|
||||
* entries in the manifest using whatever logic you provide.
|
||||
*
|
||||
* @param {Object} [config.templatedURLs] If a URL is rendered based on some
|
||||
* server-side logic, its contents may depend on multiple files or on some other
|
||||
* unique string value. The keys in this object are server-rendered URLs. If the
|
||||
* values are an array of strings, they will be interpreted as `glob` patterns,
|
||||
* and the contents of any files matching the patterns will be used to uniquely
|
||||
* version the URL. If used with a single string, it will be interpreted as
|
||||
* unique versioning information that you've generated for a given URL.
|
||||
*
|
||||
* @return {Promise<{count: number, filePaths: Array<string>, size: number, warnings: Array<string>}>}
|
||||
* A promise that resolves once the service worker and related files
|
||||
* (indicated by `filePaths`) has been written to `swDest`. The `size` property
|
||||
* contains the aggregate size of all the precached entries, in bytes, and the
|
||||
* `count` property contains the total number of precached entries. Any
|
||||
* non-fatal warning messages will be returned via `warnings`.
|
||||
* @example
|
||||
* // The following lists some common options; see the rest of the documentation
|
||||
* // for the full set of options and defaults.
|
||||
* const {count, size, warnings} = await injectManifest({
|
||||
* dontCacheBustURLsMatching: [new RegExp('...')],
|
||||
* globDirectory: '...',
|
||||
* globPatterns: ['...', '...'],
|
||||
* maximumFileSizeToCacheInBytes: ...,
|
||||
* swDest: '...',
|
||||
* swSrc: '...',
|
||||
* });
|
||||
*
|
||||
* @memberof workbox-build
|
||||
*/
|
||||
|
||||
@@ -36,162 +36,43 @@ interface GenerateSWConfig extends WebpackGenerateSWOptions {
|
||||
* [`plugins` array](https://webpack.js.org/concepts/plugins/#usage) of a
|
||||
* webpack config.
|
||||
*
|
||||
* @example
|
||||
* // The following lists some common options; see the rest of the documentation
|
||||
* // for the full set of options and defaults.
|
||||
* new GenerateSW({
|
||||
* exclude: [/.../, '...'],
|
||||
* maximumFileSizeToCacheInBytes: ...,
|
||||
* navigateFallback: '...',
|
||||
* runtimeCaching: [{
|
||||
* // Routing via a matchCallback function:
|
||||
* urlPattern: ({request, url}) => ...,
|
||||
* handler: '...',
|
||||
* options: {
|
||||
* cacheName: '...',
|
||||
* expiration: {
|
||||
* maxEntries: ...,
|
||||
* },
|
||||
* },
|
||||
* }, {
|
||||
* // Routing via a RegExp:
|
||||
* urlPattern: new RegExp('...'),
|
||||
* handler: '...',
|
||||
* options: {
|
||||
* cacheName: '...',
|
||||
* plugins: [..., ...],
|
||||
* },
|
||||
* }],
|
||||
* skipWaiting: ...,
|
||||
* });
|
||||
*
|
||||
* @memberof module:workbox-webpack-plugin
|
||||
*/
|
||||
class GenerateSW {
|
||||
private config: GenerateSWConfig;
|
||||
private alreadyCalled: boolean;
|
||||
// eslint-disable-next-line jsdoc/newline-after-description
|
||||
|
||||
/**
|
||||
* Creates an instance of GenerateSW.
|
||||
*
|
||||
* @param {Object} config The configuration to use.
|
||||
*
|
||||
* @param {Array<module:workbox-build.ManifestEntry>} [config.additionalManifestEntries]
|
||||
* A list of entries to be precached, in addition to any entries that are
|
||||
* generated as part of the build configuration.
|
||||
*
|
||||
* @param {Array<string>} [config.babelPresetEnvTargets=['chrome >= 56']]
|
||||
* The [targets](https://babeljs.io/docs/en/babel-preset-env#targets) to pass to
|
||||
* `babel-preset-env` when transpiling the service worker bundle.
|
||||
*
|
||||
* @param {string} [config.cacheId] An optional ID to be prepended to cache
|
||||
* names. This is primarily useful for local development where multiple sites
|
||||
* may be served from the same `http://localhost:port` origin.
|
||||
*
|
||||
* @param {boolean} [config.cleanupOutdatedCaches=false] Whether or not Workbox
|
||||
* should attempt to identify and delete any precaches created by older,
|
||||
* incompatible versions.
|
||||
*
|
||||
* @param {boolean} [config.clientsClaim=false] Whether or not the service
|
||||
* worker should [start controlling](https://developers.google.com/web/fundamentals/primers/service-workers/lifecycle#clientsclaim)
|
||||
* any existing clients as soon as it activates.
|
||||
*
|
||||
* @param {Array<string>} [config.chunks] One or more chunk names whose corresponding
|
||||
* output files should be included in the precache manifest.
|
||||
*
|
||||
* @param {string} [config.directoryIndex='index.html'] If a navigation request
|
||||
* for a URL ending in `/` fails to match a precached URL, this value will be
|
||||
* appended to the URL and that will be checked for a precache match. This
|
||||
* should be set to what your web server is using for its directory index.
|
||||
*
|
||||
* @param {RegExp} [config.dontCacheBustURLsMatching] Assets that match this will be
|
||||
* assumed to be uniquely versioned via their URL, and exempted from the normal
|
||||
* HTTP cache-busting that's done when populating the precache. (As of Workbox
|
||||
* v6, this option is usually not needed, as each
|
||||
* [asset's metadata](https://github.com/webpack/webpack/issues/9038) is used
|
||||
* to determine whether it's immutable or not.)
|
||||
*
|
||||
* @param {Array<string|RegExp>} [config.exclude=[/\.map$/, /^manifest.*\.js$]]
|
||||
* One or more specifiers used to exclude assets from the precache manifest.
|
||||
* This is interpreted following
|
||||
* [the same rules](https://webpack.js.org/configuration/module/#condition)
|
||||
* as `webpack`'s standard `exclude` option.
|
||||
*
|
||||
* @param {Array<string>} [config.excludeChunks] One or more chunk names whose
|
||||
* corresponding output files should be excluded from the precache manifest.
|
||||
*
|
||||
* @param {Array<RegExp>} [config.ignoreURLParametersMatching=[/^utm_/, /^fbclid$/]]
|
||||
* Any search parameter names that match against one of the RegExp in this array
|
||||
* will be removed before looking for a precache match. This is useful if your
|
||||
* users might request URLs that contain, for example, URL parameters used to
|
||||
* track the source of the traffic.
|
||||
*
|
||||
* @param {Array<string>} [config.importScripts] A list of JavaScript files that
|
||||
* should be passed to [`importScripts()`](https://developer.mozilla.org/en-US/docs/Web/API/WorkerGlobalScope/importScripts)
|
||||
* inside the generated service worker file. This is useful when you want to
|
||||
* let Workbox create your top-level service worker file, but want to include
|
||||
* some additional code, such as a push event listener.
|
||||
*
|
||||
* @param {Array<string>} [config.importScriptsViaChunks] One or more names of
|
||||
* webpack chunks. The content of those chunks will be included in the
|
||||
* generated service worker, via a call to `importScripts()`.
|
||||
*
|
||||
* @param {Array<string|RegExp>} [config.include]
|
||||
* One or more specifiers used to include assets in the precache manifest.
|
||||
* This is interpreted following
|
||||
* [the same rules](https://webpack.js.org/configuration/module/#condition)
|
||||
* as `webpack`'s standard `include` option.
|
||||
*
|
||||
* @param {boolean} [config.inlineWorkboxRuntime=false] Whether the runtime code
|
||||
* for the Workbox library should be included in the top-level service worker,
|
||||
* or split into a separate file that needs to be deployed alongside the service
|
||||
* worker. Keeping the runtime separate means that users will not have to
|
||||
* re-download the Workbox code each time your top-level service worker changes.
|
||||
*
|
||||
* @param {Array<module:workbox-build.ManifestTransform>} [config.manifestTransforms]
|
||||
* One or more functions which will be applied sequentially against the
|
||||
* generated manifest. If `modifyURLPrefix` or `dontCacheBustURLsMatching` are
|
||||
* also specified, their corresponding transformations will be applied first.
|
||||
*
|
||||
* @param {number} [config.maximumFileSizeToCacheInBytes=2097152] This value can be
|
||||
* used to determine the maximum size of files that will be precached. This
|
||||
* prevents you from inadvertently precaching very large files that might have
|
||||
* accidentally matched one of your patterns.
|
||||
*
|
||||
* @param {string} [config.mode] If set to 'production', then an optimized service
|
||||
* worker bundle that excludes debugging info will be produced. If not explicitly
|
||||
* configured here, the `mode` value configured in the current `webpack` compilation
|
||||
* will be used.
|
||||
*
|
||||
* @param {object<string, string>} [config.modifyURLPrefix] A mapping of prefixes
|
||||
* that, if present in an entry in the precache manifest, will be replaced with
|
||||
* the corresponding value. This can be used to, for example, remove or add a
|
||||
* path prefix from a manifest entry if your web hosting setup doesn't match
|
||||
* your local filesystem setup. As an alternative with more flexibility, you can
|
||||
* use the `manifestTransforms` option and provide a function that modifies the
|
||||
* entries in the manifest using whatever logic you provide.
|
||||
*
|
||||
* @param {string} [config.navigateFallback] If specified, all
|
||||
* [navigation requests](https://developers.google.com/web/fundamentals/primers/service-workers/high-performance-loading#first_what_are_navigation_requests)
|
||||
* for URLs that aren't precached will be fulfilled with the HTML at the URL
|
||||
* provided. You must pass in the URL of an HTML document that is listed in your
|
||||
* precache manifest. This is meant to be used in a Single Page App scenario, in
|
||||
* which you want all navigations to use common [App Shell HTML](https://developers.google.com/web/fundamentals/architecture/app-shell).
|
||||
*
|
||||
* @param {Array<RegExp>} [config.navigateFallbackDenylist] An optional array
|
||||
* of regular expressions that restricts which URLs the configured
|
||||
* `navigateFallback` behavior applies to. This is useful if only a subset of
|
||||
* your site's URLs should be treated as being part of a
|
||||
* [Single Page App](https://en.wikipedia.org/wiki/Single-page_application). If
|
||||
* both `navigateFallbackDenylist` and `navigateFallbackAllowlist` are
|
||||
* configured, the denylist takes precedent.
|
||||
*
|
||||
* @param {Array<RegExp>} [config.navigateFallbackAllowlist] An optional array
|
||||
* of regular expressions that restricts which URLs the configured
|
||||
* `navigateFallback` behavior applies to. This is useful if only a subset of
|
||||
* your site's URLs should be treated as being part of a
|
||||
* [Single Page App](https://en.wikipedia.org/wiki/Single-page_application). If
|
||||
* both `navigateFallbackDenylist` and `navigateFallbackAllowlist` are
|
||||
* configured, the denylist takes precedent.
|
||||
*
|
||||
* @param {boolean} [config.navigationPreload=false] Whether or not to enable
|
||||
* [navigation preload](https://developers.google.com/web/tools/workbox/modules/workbox-navigation-preload)
|
||||
* in the generated service worker. When set to true, you must also use
|
||||
* `runtimeCaching` to set up an appropriate response strategy that will match
|
||||
* navigation requests, and make use of the preloaded response.
|
||||
*
|
||||
* @param {boolean|Object} [config.offlineGoogleAnalytics=false] Controls
|
||||
* whether or not to include support for
|
||||
* [offline Google Analytics](https://developers.google.com/web/tools/workbox/guides/enable-offline-analytics).
|
||||
* When `true`, the call to `workbox-google-analytics`'s `initialize()` will be
|
||||
* added to your generated service worker. When set to an `Object`, that object
|
||||
* will be passed in to the `initialize()` call, allowing you to customize the
|
||||
* behavior.
|
||||
*
|
||||
* @param {Array<module:workbox-build.RuntimeCachingEntry>} [config.runtimeCaching]
|
||||
*
|
||||
* @param {boolean} [config.skipWaiting=false] Whether to add an
|
||||
* unconditional call to [`skipWaiting()`]{@link module:workbox-core.skipWaiting}
|
||||
* to the generated service worker. If `false`, then a `message` listener will
|
||||
* be added instead, allowing you to conditionally call `skipWaiting()` by posting
|
||||
* a message containing {type: 'SKIP_WAITING'}.
|
||||
*
|
||||
* @param {boolean} [config.sourcemap=true] Whether to create a sourcemap
|
||||
* for the generated service worker files.
|
||||
*
|
||||
* @param {string} [config.swDest='service-worker.js'] The asset name of the
|
||||
* service worker file that will be created by this plugin.
|
||||
*/
|
||||
constructor(config: GenerateSWConfig = {}) {
|
||||
this.config = config;
|
||||
|
||||
@@ -38,87 +38,26 @@ const {RawSource} = webpack.sources || require('webpack-sources');
|
||||
* [`plugins` array](https://webpack.js.org/concepts/plugins/#usage) of a
|
||||
* webpack config.
|
||||
*
|
||||
* In addition to injecting the manifest, this plugin will perform a compilation
|
||||
* of the `swSrc` file, using the options from the main webpack configuration.
|
||||
*
|
||||
* @example
|
||||
* // The following lists some common options; see the rest of the documentation
|
||||
* // for the full set of options and defaults.
|
||||
* new InjectManifest({
|
||||
* exclude: [/.../, '...'],
|
||||
* maximumFileSizeToCacheInBytes: ...,
|
||||
* swSrc: '...',
|
||||
* });
|
||||
*
|
||||
* @memberof module:workbox-webpack-plugin
|
||||
*/
|
||||
class InjectManifest {
|
||||
private config: WebpackInjectManifestOptions;
|
||||
private alreadyCalled: boolean;
|
||||
// eslint-disable-next-line jsdoc/newline-after-description
|
||||
|
||||
/**
|
||||
* Creates an instance of InjectManifest.
|
||||
*
|
||||
* @param {Object} config The configuration to use.
|
||||
*
|
||||
* @param {string} config.swSrc An existing service worker file that will be
|
||||
* compiled and have a precache manifest injected into it.
|
||||
*
|
||||
* @param {Array<module:workbox-build.ManifestEntry>} [config.additionalManifestEntries]
|
||||
* A list of entries to be precached, in addition to any entries that are
|
||||
* generated as part of the build configuration.
|
||||
*
|
||||
* @param {Array<string>} [config.chunks] One or more chunk names whose corresponding
|
||||
* output files should be included in the precache manifest.
|
||||
*
|
||||
* @param {boolean} [config.compileSrc=true] When `true` (the default), the
|
||||
* `swSrc` file will be compiled by webpack. When `false`, compilation will
|
||||
* not occur (and `webpackCompilationPlugins` can't be used.) Set to `false`
|
||||
* if you want to inject the manifest into, e.g., a JSON file.
|
||||
*
|
||||
* @param {RegExp} [config.dontCacheBustURLsMatching] Assets that match this will be
|
||||
* assumed to be uniquely versioned via their URL, and exempted from the normal
|
||||
* HTTP cache-busting that's done when populating the precache. (As of Workbox
|
||||
* v6, this option is usually not needed, as each
|
||||
* [asset's metadata](https://github.com/webpack/webpack/issues/9038) is used
|
||||
* to determine whether it's immutable or not.)
|
||||
*
|
||||
* @param {Array<string|RegExp|Function>} [config.exclude=[/\.map$/, /^manifest.*\.js$]]
|
||||
* One or more specifiers used to exclude assets from the precache manifest.
|
||||
* This is interpreted following
|
||||
* [the same rules](https://webpack.js.org/configuration/module/#condition)
|
||||
* as `webpack`'s standard `exclude` option.
|
||||
*
|
||||
* @param {Array<string>} [config.excludeChunks] One or more chunk names whose
|
||||
* corresponding output files should be excluded from the precache manifest.
|
||||
*
|
||||
* @param {Array<string|RegExp|Function>} [config.include]
|
||||
* One or more specifiers used to include assets in the precache manifest.
|
||||
* This is interpreted following
|
||||
* [the same rules](https://webpack.js.org/configuration/module/#condition)
|
||||
* as `webpack`'s standard `include` option.
|
||||
*
|
||||
* @param {string} [config.injectionPoint='self.__WB_MANIFEST'] The string to
|
||||
* find inside of the `swSrc` file. Once found, it will be replaced by the
|
||||
* generated precache manifest.
|
||||
*
|
||||
* @param {Array<module:workbox-build.ManifestTransform>} [config.manifestTransforms]
|
||||
* One or more functions which will be applied sequentially against the
|
||||
* generated manifest. If `modifyURLPrefix` or `dontCacheBustURLsMatching` are
|
||||
* also specified, their corresponding transformations will be applied first.
|
||||
*
|
||||
* @param {number} [config.maximumFileSizeToCacheInBytes=2097152] This value can be
|
||||
* used to determine the maximum size of files that will be precached. This
|
||||
* prevents you from inadvertently precaching very large files that might have
|
||||
* accidentally matched one of your patterns.
|
||||
*
|
||||
* @param {string} [config.mode] If set to 'production', then an optimized service
|
||||
* worker bundle that excludes debugging info will be produced. If not explicitly
|
||||
* configured here, the `mode` value configured in the current `webpack`
|
||||
* compilation will be used.
|
||||
*
|
||||
* @param {object<string, string>} [config.modifyURLPrefix] A mapping of prefixes
|
||||
* that, if present in an entry in the precache manifest, will be replaced with
|
||||
* the corresponding value. This can be used to, for example, remove or add a
|
||||
* path prefix from a manifest entry if your web hosting setup doesn't match
|
||||
* your local filesystem setup. As an alternative with more flexibility, you can
|
||||
* use the `manifestTransforms` option and provide a function that modifies the
|
||||
* entries in the manifest using whatever logic you provide.
|
||||
*
|
||||
* @param {string} [config.swDest] The asset name of the
|
||||
* service worker file that will be created by this plugin. If omitted, the
|
||||
* name will be based on the `swSrc` name.
|
||||
*
|
||||
* @param {Array<Object>} [config.webpackCompilationPlugins] Optional `webpack`
|
||||
* plugins that will be used when compiling the `swSrc` input file.
|
||||
*/
|
||||
constructor(config: WebpackInjectManifestOptions) {
|
||||
this.config = config;
|
||||
|
||||
Reference in New Issue
Block a user