From 95cb6c8f60253346021061a0ffea220d7f2757a4 Mon Sep 17 00:00:00 2001 From: Jeff Posnick Date: Fri, 13 Sep 2019 15:17:27 -0400 Subject: [PATCH 01/16] WIP. --- packages/workbox-build/src/generate-sw.js | 60 ++++++++++++++++++- .../workbox-build/src/lib/module-registry.js | 8 +++ 2 files changed, 66 insertions(+), 2 deletions(-) diff --git a/packages/workbox-build/src/generate-sw.js b/packages/workbox-build/src/generate-sw.js index 893fa5379..d63c41dcb 100644 --- a/packages/workbox-build/src/generate-sw.js +++ b/packages/workbox-build/src/generate-sw.js @@ -22,8 +22,64 @@ const writeServiceWorkerUsingDefaultTemplate = * 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 Please refer to the - * [configuration guide](https://developers.google.com/web/tools/workbox/modules/workbox-build#full_generatesw_config). + * @param {Object} config The configuration to use. + * @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} [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 {Array} [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} [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 {Array} [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 an 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 {Array} [config.ignoreURLParametersMatching=[/^utm_/]] + * 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} [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. * @return {Promise<{count: number, filePaths: Array, size: number, warnings: Array}>} * A promise that resolves once the service worker and related files * (indicated by `filePaths`) has been written to `swDest`. The `size` property diff --git a/packages/workbox-build/src/lib/module-registry.js b/packages/workbox-build/src/lib/module-registry.js index ac4995311..4c7a03441 100644 --- a/packages/workbox-build/src/lib/module-registry.js +++ b/packages/workbox-build/src/lib/module-registry.js @@ -12,6 +12,8 @@ const upath = require('upath'); /** * Class for keeping track of which Workbox modules are used by the generated * service worker script. + * + * @private */ class ModuleRegistry { /** @@ -24,6 +26,8 @@ class ModuleRegistry { /** * @return {Array} A list of all of the import statements that are * needed for the modules being used. + * + * @private */ getImportStatements() { const workboxModuleImports = []; @@ -48,6 +52,8 @@ class ModuleRegistry { * @param {string} pkg The workbox package that the module belongs to. * @param {string} moduleName The name of the module to import. * @return {string} The local variable name that corresponds to that module. + * + * @private */ getLocalName(pkg, moduleName) { return `${pkg.replace(/-/g, '_')}_${moduleName}`; @@ -57,6 +63,8 @@ class ModuleRegistry { * @param {string} pkg The workbox package that the module belongs to. * @param {string} moduleName The name of the module to import. * @return {string} The local variable name that corresponds to that module. + * + * @private */ use(pkg, moduleName) { const localName = this.getLocalName(pkg, moduleName); From 681defbdd5f6e873a8a9025d884e20200f3366fa Mon Sep 17 00:00:00 2001 From: Jeff Posnick Date: Thu, 10 Oct 2019 11:07:40 -0400 Subject: [PATCH 02/16] WIP. --- packages/workbox-build/src/generate-sw.js | 78 +++++++++++++++++++++++ 1 file changed, 78 insertions(+) diff --git a/packages/workbox-build/src/generate-sw.js b/packages/workbox-build/src/generate-sw.js index 95495d9d1..07ccb2840 100644 --- a/packages/workbox-build/src/generate-sw.js +++ b/packages/workbox-build/src/generate-sw.js @@ -83,6 +83,84 @@ const writeServiceWorkerUsingDefaultTemplate = * 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 {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} [config.navigateFallbackBlacklist] 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 `navigateFallbackBlacklist` and `navigateFallbackWhitelist` are + * configured, the blacklist takes precedent. + * @param {Array} [config.navigateFallbackWhitelist] 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 `navigateFallbackBlacklist` and `navigateFallbackWhitelist` are + * configured, the blacklist 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} [config.runtimeCaching] + * @param {string} [config.runtimeCaching[].method='GET'] The + * [HTTP method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) that + * will match the generated route. + * @param {string|RegExp|workbox.routing.Route~matchCallback} config.runtimeCaching[].urlPattern + * The value that will be passed to workbox.routing.Router~registerRoute, used + * to determine whether the generated route will match a given request. + * @param {string|workbox.routing.Route~handlerCallback} config.runtimeCaching[].handler + * Either the name of one of the [built-in strategy classes](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.strategies), + * or custom handler callback to use when the generated route matches. + * @param {Object} [config.runtimeCaching[].options] + * @param {Object} [config.runtimeCaching[].options.backgroundSync] + * @param {string} config.runtimeCaching[].options.backgroundSync.name The + * [`name` parameter](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.backgroundSync.Queue.html) + * to use when creating the `BackgroundSyncPlugin`. + * @param {Object} [config.runtimeCaching[].options.backgroundSync.options] The + * [`options` parameter](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.backgroundSync.Queue.html) + * to use when creating the `BackgroundSyncPlugin`. + * @param {Object} [config.runtimeCaching[].options.broadcastUpdate] + * @param {string} config.runtimeCaching[].options.broadcastUpdate.channelName + * The [`channelName` parameter](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.broadcastUpdate.BroadcastCacheUpdate) + * to use when creating the `BroadcastCacheUpdatePlugin`. + * @param {Object} [config.runtimeCaching[].options.broadcastUpdate.options] The + * [`options` parameter](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.broadcastUpdate.BroadcastCacheUpdate) + * to use when creating the `BroadcastCacheUpdatePlugin`. + * @param {Object} [config.runtimeCaching[].options.cacheableResponse] + * @param {Array} [config.runtimeCaching[].options.cacheableResponse.statuses] + * The [`status` parameter](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.cacheableResponse.CacheableResponse) + * to use when creating the `CacheableResponsePlugin`. + * @param {Object} [config.runtimeCaching[].options.cacheableResponse.headers] + * The [`headers` parameter](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.cacheableResponse.CacheableResponse) + * to use when creating the `CacheableResponsePlugin`. + * @param {string} [config.runtimeCaching[].options.cacheName] The `cacheName` + * to use when constructing one of the [Workbox strategy classes](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.strategies). + * @param {Object} [config.runtimeCaching[].options.expiration] + * @param {Number} [config.runtimeCaching[].options.expiration.maxAgeSeconds] + * The [`maxAgeSeconds` parameter](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.expiration.CacheExpiration) + * to use when creating the `CacheExpirationPlugin`. + * @param {Number} [config.runtimeCaching[].options.expiration.maxEntries] + * The [`maxAgeSeconds` parameter](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.expiration.CacheExpiration) + * to use when creating the `CacheExpirationPlugin`. * @return {Promise<{count: number, filePaths: Array, size: number, warnings: Array}>} * A promise that resolves once the service worker and related files * (indicated by `filePaths`) has been written to `swDest`. The `size` property From a347da70f30cf5040d64ae6670464006c284ff83 Mon Sep 17 00:00:00 2001 From: Jeff Posnick Date: Wed, 20 Nov 2019 16:20:01 -0500 Subject: [PATCH 03/16] WIP --- packages/workbox-build/src/generate-sw.js | 52 +++++++++++++++++++++-- packages/workbox-core/src/skipWaiting.ts | 5 ++- 2 files changed, 52 insertions(+), 5 deletions(-) diff --git a/packages/workbox-build/src/generate-sw.js b/packages/workbox-build/src/generate-sw.js index 07ccb2840..b848effd2 100644 --- a/packages/workbox-build/src/generate-sw.js +++ b/packages/workbox-build/src/generate-sw.js @@ -15,6 +15,7 @@ const validate = require('./lib/validate-options'); const writeServiceWorkerUsingDefaultTemplate = require('./lib/write-sw-using-default-template'); +// eslint-disable-next-line valid-jsdoc, 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. @@ -146,7 +147,7 @@ const writeServiceWorkerUsingDefaultTemplate = * [`options` parameter](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.broadcastUpdate.BroadcastCacheUpdate) * to use when creating the `BroadcastCacheUpdatePlugin`. * @param {Object} [config.runtimeCaching[].options.cacheableResponse] - * @param {Array} [config.runtimeCaching[].options.cacheableResponse.statuses] + * @param {Array} [config.runtimeCaching[].options.cacheableResponse.statuses] * The [`status` parameter](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.cacheableResponse.CacheableResponse) * to use when creating the `CacheableResponsePlugin`. * @param {Object} [config.runtimeCaching[].options.cacheableResponse.headers] @@ -155,12 +156,57 @@ const writeServiceWorkerUsingDefaultTemplate = * @param {string} [config.runtimeCaching[].options.cacheName] The `cacheName` * to use when constructing one of the [Workbox strategy classes](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.strategies). * @param {Object} [config.runtimeCaching[].options.expiration] - * @param {Number} [config.runtimeCaching[].options.expiration.maxAgeSeconds] + * @param {number} [config.runtimeCaching[].options.expiration.maxAgeSeconds] * The [`maxAgeSeconds` parameter](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.expiration.CacheExpiration) * to use when creating the `CacheExpirationPlugin`. - * @param {Number} [config.runtimeCaching[].options.expiration.maxEntries] + * @param {number} [config.runtimeCaching[].options.expiration.maxEntries] * The [`maxAgeSeconds` parameter](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.expiration.CacheExpiration) * to use when creating the `CacheExpirationPlugin`. + * @param {number} [config.runtimeCaching[].options.networkTimeoutSeconds] + * The `networkTimeoutSeconds` parameter value to use when creating a + * `NetworkFirst` handler. + * @param {Array} [config.runtimeCaching[].options.plugins] + * One or more [additional plugins](https://developers.google.com/web/tools/workbox/guides/using-plugins#custom_plugins) + * to apply to the handler. Useful when you want a plugin that doesn't have a + * "shortcut" configuration, like `expiration` or `cacheableResponse`. + * @param {Object} [config.runtimeCaching[].options.fetchOptions] + * The `fetchOptions` parameter value to use when creating the handler. + * @param {Object} [config.runtimeCaching[].options.matchOptions] + * The `matchOptions` parameter value to use when creating the handler. + * @param {boolean} [config.skipWaiting=false] Whether to add an + * unconditional call to [`skipWaiting()`](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.core#.skipWaiting) + * to the generated service worker. If `false`, then a `message` listener will + * be added instead, all you to conditionally call `skipWaiting()`. + * @param {boolean} [config.sourcemap=true] Whether to create a sourcemap + * for the generated service worker files. + * @param {string} config.globDirectory The local directory you wish to match + * `globPatterns` against. The path is relative to the current directory. + * @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} [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} [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 {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, size: number, warnings: Array}>} * A promise that resolves once the service worker and related files * (indicated by `filePaths`) has been written to `swDest`. The `size` property diff --git a/packages/workbox-core/src/skipWaiting.ts b/packages/workbox-core/src/skipWaiting.ts index 61876bf64..afe99e639 100644 --- a/packages/workbox-core/src/skipWaiting.ts +++ b/packages/workbox-core/src/skipWaiting.ts @@ -13,8 +13,9 @@ import './_version.js'; declare var self: ServiceWorkerGlobalScope; /** - * Force a service worker to become active, instead of waiting. This is - * normally used in conjunction with `clientsClaim()`. + * Force a service worker to activate immediately, instead of + * [waiting](https://developers.google.com/web/fundamentals/primers/service-workers/lifecycle#waiting) + * for existing clients to close. * * @alias workbox.core.skipWaiting */ From 787115300d1b886e86ec6a1e449eea536e2a84a1 Mon Sep 17 00:00:00 2001 From: Jeff Posnick Date: Tue, 7 Jan 2020 16:35:20 -0500 Subject: [PATCH 04/16] RuntimeCachingEntry --- packages/workbox-build/src/_types.js | 58 +++++++++++++++++++++++ packages/workbox-build/src/generate-sw.js | 55 +-------------------- 2 files changed, 59 insertions(+), 54 deletions(-) diff --git a/packages/workbox-build/src/_types.js b/packages/workbox-build/src/_types.js index 0f11a72d9..5579f6aad 100644 --- a/packages/workbox-build/src/_types.js +++ b/packages/workbox-build/src/_types.js @@ -26,3 +26,61 @@ import './_version.mjs'; * * @memberof module:workbox-build */ + +/** + * @typedef {Object} RuntimeCachingEntry + * + * @property {string} [method='GET'] The + * [HTTP method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) that + * will match the generated route. + * @property {string|RegExp|workbox.routing.Route~matchCallback} urlPattern + * The value that will be passed to workbox.routing.Router~registerRoute, used + * to determine whether the generated route will match a given request. + * @property {string|workbox.routing.Route~handlerCallback} handler + * Either the name of one of the [built-in strategy classes](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.strategies), + * or custom handler callback to use when the generated route matches. + * @property {Object} [options] + * @property {Object} [options.backgroundSync] + * @property {string} options.backgroundSync.name The + * [`name` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.backgroundSync.Queue.html) + * to use when creating the `BackgroundSyncPlugin`. + * @property {Object} [options.backgroundSync.options] The + * [`options` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.backgroundSync.Queue.html) + * to use when creating the `BackgroundSyncPlugin`. + * @property {Object} [options.broadcastUpdate] + * @property {string} options.broadcastUpdate.channelName + * The [`channelName` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.broadcastUpdate.BroadcastCacheUpdate) + * to use when creating the `BroadcastCacheUpdatePlugin`. + * @property {Object} [options.broadcastUpdate.options] The + * [`options` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.broadcastUpdate.BroadcastCacheUpdate) + * to use when creating the `BroadcastCacheUpdatePlugin`. + * @property {Object} [options.cacheableResponse] + * @property {Array} [options.cacheableResponse.statuses] + * The [`status` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.cacheableResponse.CacheableResponse) + * to use when creating the `CacheableResponsePlugin`. + * @property {Object} [options.cacheableResponse.headers] + * The [`headers` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.cacheableResponse.CacheableResponse) + * to use when creating the `CacheableResponsePlugin`. + * @property {string} [options.cacheName] The `cacheName` + * to use when constructing one of the [Workbox strategy classes](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.strategies). + * @property {Object} [options.expiration] + * @property {number} [options.expiration.maxAgeSeconds] + * The [`maxAgeSeconds` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.expiration.CacheExpiration) + * to use when creating the `CacheExpirationPlugin`. + * @property {number} [options.expiration.maxEntries] + * The [`maxAgeSeconds` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.expiration.CacheExpiration) + * to use when creating the `CacheExpirationPlugin`. + * @property {number} [options.networkTimeoutSeconds] + * The `networkTimeoutSeconds` property value to use when creating a + * `NetworkFirst` handler. + * @property {Array} [options.plugins] + * One or more [additional plugins](https://developers.google.com/web/tools/workbox/guides/using-plugins#custom_plugins) + * to apply to the handler. Useful when you want a plugin that doesn't have a + * "shortcut" configuration, like `expiration` or `cacheableResponse`. + * @property {Object} [options.fetchOptions] + * The `fetchOptions` property value to use when creating the handler. + * @property {Object} [options.matchOptions] + * The `matchOptions` property value to use when creating the handler. + * + * @memberof module:workbox-build + */ diff --git a/packages/workbox-build/src/generate-sw.js b/packages/workbox-build/src/generate-sw.js index b848effd2..c15388288 100644 --- a/packages/workbox-build/src/generate-sw.js +++ b/packages/workbox-build/src/generate-sw.js @@ -121,58 +121,7 @@ const writeServiceWorkerUsingDefaultTemplate = * 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} [config.runtimeCaching] - * @param {string} [config.runtimeCaching[].method='GET'] The - * [HTTP method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) that - * will match the generated route. - * @param {string|RegExp|workbox.routing.Route~matchCallback} config.runtimeCaching[].urlPattern - * The value that will be passed to workbox.routing.Router~registerRoute, used - * to determine whether the generated route will match a given request. - * @param {string|workbox.routing.Route~handlerCallback} config.runtimeCaching[].handler - * Either the name of one of the [built-in strategy classes](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.strategies), - * or custom handler callback to use when the generated route matches. - * @param {Object} [config.runtimeCaching[].options] - * @param {Object} [config.runtimeCaching[].options.backgroundSync] - * @param {string} config.runtimeCaching[].options.backgroundSync.name The - * [`name` parameter](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.backgroundSync.Queue.html) - * to use when creating the `BackgroundSyncPlugin`. - * @param {Object} [config.runtimeCaching[].options.backgroundSync.options] The - * [`options` parameter](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.backgroundSync.Queue.html) - * to use when creating the `BackgroundSyncPlugin`. - * @param {Object} [config.runtimeCaching[].options.broadcastUpdate] - * @param {string} config.runtimeCaching[].options.broadcastUpdate.channelName - * The [`channelName` parameter](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.broadcastUpdate.BroadcastCacheUpdate) - * to use when creating the `BroadcastCacheUpdatePlugin`. - * @param {Object} [config.runtimeCaching[].options.broadcastUpdate.options] The - * [`options` parameter](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.broadcastUpdate.BroadcastCacheUpdate) - * to use when creating the `BroadcastCacheUpdatePlugin`. - * @param {Object} [config.runtimeCaching[].options.cacheableResponse] - * @param {Array} [config.runtimeCaching[].options.cacheableResponse.statuses] - * The [`status` parameter](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.cacheableResponse.CacheableResponse) - * to use when creating the `CacheableResponsePlugin`. - * @param {Object} [config.runtimeCaching[].options.cacheableResponse.headers] - * The [`headers` parameter](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.cacheableResponse.CacheableResponse) - * to use when creating the `CacheableResponsePlugin`. - * @param {string} [config.runtimeCaching[].options.cacheName] The `cacheName` - * to use when constructing one of the [Workbox strategy classes](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.strategies). - * @param {Object} [config.runtimeCaching[].options.expiration] - * @param {number} [config.runtimeCaching[].options.expiration.maxAgeSeconds] - * The [`maxAgeSeconds` parameter](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.expiration.CacheExpiration) - * to use when creating the `CacheExpirationPlugin`. - * @param {number} [config.runtimeCaching[].options.expiration.maxEntries] - * The [`maxAgeSeconds` parameter](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.expiration.CacheExpiration) - * to use when creating the `CacheExpirationPlugin`. - * @param {number} [config.runtimeCaching[].options.networkTimeoutSeconds] - * The `networkTimeoutSeconds` parameter value to use when creating a - * `NetworkFirst` handler. - * @param {Array} [config.runtimeCaching[].options.plugins] - * One or more [additional plugins](https://developers.google.com/web/tools/workbox/guides/using-plugins#custom_plugins) - * to apply to the handler. Useful when you want a plugin that doesn't have a - * "shortcut" configuration, like `expiration` or `cacheableResponse`. - * @param {Object} [config.runtimeCaching[].options.fetchOptions] - * The `fetchOptions` parameter value to use when creating the handler. - * @param {Object} [config.runtimeCaching[].options.matchOptions] - * The `matchOptions` parameter value to use when creating the handler. + * @param {Array} [config.runtimeCaching] * @param {boolean} [config.skipWaiting=false] Whether to add an * unconditional call to [`skipWaiting()`](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.core#.skipWaiting) * to the generated service worker. If `false`, then a `message` listener will @@ -198,8 +147,6 @@ const writeServiceWorkerUsingDefaultTemplate = * 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 {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 From b558df3ed3323209200db50beeeb3190c0e6d4ad Mon Sep 17 00:00:00 2001 From: Jeff Posnick Date: Wed, 8 Jan 2020 15:37:20 -0500 Subject: [PATCH 05/16] injectManifest JSDocs --- packages/workbox-build/src/generate-sw.js | 2 +- packages/workbox-build/src/inject-manifest.js | 67 ++++++++++++++++++- 2 files changed, 66 insertions(+), 3 deletions(-) diff --git a/packages/workbox-build/src/generate-sw.js b/packages/workbox-build/src/generate-sw.js index c15388288..f6b886ac9 100644 --- a/packages/workbox-build/src/generate-sw.js +++ b/packages/workbox-build/src/generate-sw.js @@ -15,7 +15,7 @@ const validate = require('./lib/validate-options'); const writeServiceWorkerUsingDefaultTemplate = require('./lib/write-sw-using-default-template'); -// eslint-disable-next-line valid-jsdoc, jsdoc/newline-after-description +// 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. diff --git a/packages/workbox-build/src/inject-manifest.js b/packages/workbox-build/src/inject-manifest.js index d0d218308..06990f54b 100644 --- a/packages/workbox-build/src/inject-manifest.js +++ b/packages/workbox-build/src/inject-manifest.js @@ -21,6 +21,7 @@ const replaceAndUpdateSourceMap = require('./lib/replace-and-update-source-map'); const validate = require('./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. @@ -31,8 +32,70 @@ const validate = require('./lib/validate-options'); * The final service worker file, with the manifest injected, is written to * disk at `swDest`. * - * @param {Object} config Please refer to the - * [configuration guide](https://developers.google.com/web/tools/workbox/modules/workbox-build#full_injectmanifest_config). + * @param {Object} config The configuration to use. + * @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} [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 {Array} [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} [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.globDirectory The local directory you wish to match + * `globPatterns` against. The path is relative to the current directory. + * @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} [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} [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 {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. + * @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 {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. * @return {Promise<{count: number, filePaths: Array, size: number, warnings: Array}>} * A promise that resolves once the service worker and related files * (indicated by `filePaths`) has been written to `swDest`. The `size` property From 14cf31acfd19df91546c2561c738cec80234de82 Mon Sep 17 00:00:00 2001 From: Jeff Posnick Date: Wed, 8 Jan 2020 16:16:42 -0500 Subject: [PATCH 06/16] getManifest JSDocs --- packages/workbox-build/src/get-manifest.js | 69 +++++++++++++++++++--- 1 file changed, 61 insertions(+), 8 deletions(-) diff --git a/packages/workbox-build/src/get-manifest.js b/packages/workbox-build/src/get-manifest.js index a11ea7777..4e0069e0d 100644 --- a/packages/workbox-build/src/get-manifest.js +++ b/packages/workbox-build/src/get-manifest.js @@ -10,19 +10,72 @@ const getFileManifestEntries = require('./lib/get-file-manifest-entries'); const getManifestSchema = require('./options/schema/get-manifest'); const validate = require('./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 Please refer to the - * [configuration guide](https://developers.google.com/web/tools/workbox/modules/workbox-build#getmanifest_mode). - * @return {Promise<{manifestEntries: Array, - * count: number, size: number, warnings: Array}>} A promise that - * resolves once the precache manifest is determined. The `size` property - * contains the aggregate size of all the precached entries, in bytes, the - * `count` property contains the total number of precached entries, and the - * `manifestEntries` property contains all the `ManifestEntry` items. Any + * @param {Object} config The configuration to use. + * @param {Array} [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 {Array} [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} [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.globDirectory The local directory you wish to match + * `globPatterns` against. The path is relative to the current directory. + * @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} [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} [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 {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, size: number, warnings: Array}>} + * 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`. * * @memberof module:workbox-build From f9db784cd76ff50c25a9e30646ef7573190b5d62 Mon Sep 17 00:00:00 2001 From: Jeff Posnick Date: Wed, 8 Jan 2020 16:22:28 -0500 Subject: [PATCH 07/16] workbox-cli update --- packages/workbox-cli/src/lib/help-text.js | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/packages/workbox-cli/src/lib/help-text.js b/packages/workbox-cli/src/lib/help-text.js index 56fa6be48..6787a53f0 100644 --- a/packages/workbox-cli/src/lib/help-text.js +++ b/packages/workbox-cli/src/lib/help-text.js @@ -24,7 +24,7 @@ Commands: If --watch is provided, the CLI will stay running, and will rebuild the service worker each time a file in the precache manifest changes. - See https://goo.gl/gVo87N + See https://bit.ly/wb-generateSW injectManifest [] [--watch] Takes an existing service worker file and creates a @@ -34,7 +34,7 @@ Commands: If --watch is provided, the CLI will stay running, and will rebuild the service worker each time a file in the precache manifest changes. - See https://goo.gl/8bs14N + See https://bit.ly/wb-injectManifest copyLibraries Makes a local copy of all of the Workbox libraries inside @@ -45,9 +45,8 @@ Commands: Config file: In 'generateSW' or 'injectManifest' mode, the config file should be a JavaScript file, in CommonJS module format. - By default, a config location of workbox-config.js in the current + By default, a config file named workbox-config.js in the current directory is assumed, but this can be overridden. - The exported object's properties should follow https://goo.gl/YYPcyY Examples: $ workbox wizard From 9e50fd9b229eda931d6134193adcf01018b8c9b8 Mon Sep 17 00:00:00 2001 From: Jeff Posnick Date: Thu, 9 Jan 2020 12:14:56 -0500 Subject: [PATCH 08/16] GenerateSW (and random typos) --- .../workbox-routing/src/NavigationRoute.ts | 2 +- packages/workbox-routing/src/RegExpRoute.ts | 4 +- .../workbox-webpack-plugin/src/generate-sw.js | 122 +++++++++++++++++- 3 files changed, 122 insertions(+), 6 deletions(-) diff --git a/packages/workbox-routing/src/NavigationRoute.ts b/packages/workbox-routing/src/NavigationRoute.ts index 2701b00a7..b1b806063 100644 --- a/packages/workbox-routing/src/NavigationRoute.ts +++ b/packages/workbox-routing/src/NavigationRoute.ts @@ -37,7 +37,7 @@ class NavigationRoute extends Route { private _blacklist: RegExp[]; /** - * If both `blacklist` and `whiltelist` are provided, the `blacklist` will + * If both `blacklist` and `whitelist` are provided, the `blacklist` will * take precedence and the request will not match this route. * * The regular expressions in `whitelist` and `blacklist` diff --git a/packages/workbox-routing/src/RegExpRoute.ts b/packages/workbox-routing/src/RegExpRoute.ts index 466ab442b..d046a326f 100644 --- a/packages/workbox-routing/src/RegExpRoute.ts +++ b/packages/workbox-routing/src/RegExpRoute.ts @@ -29,9 +29,9 @@ import './_version.js'; */ class RegExpRoute extends Route { /** - * If the regulard expression contains + * If the regular expression contains * [capture groups]{@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#grouping-back-references}, - * th ecaptured values will be passed to the + * the captured values will be passed to the * [handler's]{@link workbox.routing.Route~handlerCallback} `params` * argument. * diff --git a/packages/workbox-webpack-plugin/src/generate-sw.js b/packages/workbox-webpack-plugin/src/generate-sw.js index 219d89534..d95ec95d8 100644 --- a/packages/workbox-webpack-plugin/src/generate-sw.js +++ b/packages/workbox-webpack-plugin/src/generate-sw.js @@ -34,12 +34,128 @@ const _generatedAssetNames = new Set(); * @module workbox-webpack-plugin */ class GenerateSW { + // eslint-disable-next-line jsdoc/newline-after-description /** * Creates an instance of GenerateSW. * - * @param {Object} [config] See the - * [configuration guide](https://developers.google.com/web/tools/workbox/modules/workbox-webpack-plugin#configuration) - * for all supported options and defaults. + * @param {Object} config The configuration to use. + * @param {string} [config.swDest='service-worker.js'] The asset name of the + * service worker file that will be created by this plugin. + * @param {Array} [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} [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 {Array} [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} [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 {Array} [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 an 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 {Array} [config.ignoreURLParametersMatching=[/^utm_/]] + * 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} [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 {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} [config.navigateFallbackBlacklist] 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 `navigateFallbackBlacklist` and `navigateFallbackWhitelist` are + * configured, the blacklist takes precedent. + * @param {Array} [config.navigateFallbackWhitelist] 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 `navigateFallbackBlacklist` and `navigateFallbackWhitelist` are + * configured, the blacklist 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} [config.runtimeCaching] + * @param {boolean} [config.skipWaiting=false] Whether to add an + * unconditional call to [`skipWaiting()`](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.core#.skipWaiting) + * to the generated service worker. If `false`, then a `message` listener will + * be added instead, all you to conditionally call `skipWaiting()`. + * @param {boolean} [config.sourcemap=true] Whether to create a sourcemap + * for the generated service worker files. + * @param {Array} [chunks] One or more chunk names whose corresponding + * output files should be included in the precache manifest. + * @param {Array} [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} [excludeChunks] One or more chunk names whose + * corresponding output files should be excluded from the precache manifest. + * @param {Array} [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. */ constructor(config = {}) { this.config = config; From bd4b1ae7a9ae7f3e5cec3c1c7a47abd082b75641 Mon Sep 17 00:00:00 2001 From: Jeff Posnick Date: Thu, 9 Jan 2020 15:38:13 -0500 Subject: [PATCH 09/16] InjectManifest --- .../src/inject-manifest.js | 62 +++++++++++++++++-- 1 file changed, 58 insertions(+), 4 deletions(-) diff --git a/packages/workbox-webpack-plugin/src/inject-manifest.js b/packages/workbox-webpack-plugin/src/inject-manifest.js index 28789edbb..201cf154e 100644 --- a/packages/workbox-webpack-plugin/src/inject-manifest.js +++ b/packages/workbox-webpack-plugin/src/inject-manifest.js @@ -37,12 +37,66 @@ const _generatedAssetNames = new Set(); * @module workbox-webpack-plugin */ class InjectManifest { + // eslint-disable-next-line jsdoc/newline-after-description /** - * Creates an instance of InjectManifest. + * Creates an instance of GenerateSW. * - * @param {Object} [config] See the - * [configuration guide](https://developers.google.com/web/tools/workbox/modules/workbox-webpack-plugin#configuration) - * for all supported options and defaults. + * @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 {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} [webpackCompilationPlugins] Optional `webpack` + * plugins that will be used when compiling the `swSrc` input file. + * @param {Array} [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} [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 {Array} [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} [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.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} [chunks] One or more chunk names whose corresponding + * output files should be included in the precache manifest. + * @param {Array} [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} [excludeChunks] One or more chunk names whose + * corresponding output files should be excluded from the precache manifest. + * @param {Array} [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. */ constructor(config = {}) { this.config = config; From e2b673b4f337e588a52b6d21e5ea6edf4970520c Mon Sep 17 00:00:00 2001 From: Jeff Posnick Date: Thu, 9 Jan 2020 16:20:49 -0500 Subject: [PATCH 10/16] Cleanup/reordering --- packages/workbox-build/src/generate-sw.js | 118 +++++++++++------- packages/workbox-build/src/get-manifest.js | 51 +++++--- packages/workbox-build/src/inject-manifest.js | 66 ++++++---- .../workbox-webpack-plugin/src/generate-sw.js | 116 ++++++++++------- .../src/inject-manifest.js | 73 ++++++----- 5 files changed, 263 insertions(+), 161 deletions(-) diff --git a/packages/workbox-build/src/generate-sw.js b/packages/workbox-build/src/generate-sw.js index f6b886ac9..385562113 100644 --- a/packages/workbox-build/src/generate-sw.js +++ b/packages/workbox-build/src/generate-sw.js @@ -27,74 +27,115 @@ const writeServiceWorkerUsingDefaultTemplate = * 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} [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 {Array} [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} [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 {Array} [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 an 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} [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} [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} [config.ignoreURLParametersMatching=[/^utm_/]] * 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} [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} [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} [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} [config.navigateFallbackBlacklist] An optional array * of regular expressions that restricts which URLs the configured * `navigateFallback` behavior applies to. This is useful if only a subset of @@ -102,6 +143,7 @@ const writeServiceWorkerUsingDefaultTemplate = * [Single Page App](https://en.wikipedia.org/wiki/Single-page_application). If * both `navigateFallbackBlacklist` and `navigateFallbackWhitelist` are * configured, the blacklist takes precedent. + * * @param {Array} [config.navigateFallbackWhitelist] An optional array * of regular expressions that restricts which URLs the configured * `navigateFallback` behavior applies to. This is useful if only a subset of @@ -109,11 +151,13 @@ const writeServiceWorkerUsingDefaultTemplate = * [Single Page App](https://en.wikipedia.org/wiki/Single-page_application). If * both `navigateFallbackBlacklist` and `navigateFallbackWhitelist` are * configured, the blacklist 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). @@ -121,32 +165,17 @@ const writeServiceWorkerUsingDefaultTemplate = * 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} [config.runtimeCaching] + * * @param {boolean} [config.skipWaiting=false] Whether to add an * unconditional call to [`skipWaiting()`](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.core#.skipWaiting) * to the generated service worker. If `false`, then a `message` listener will * be added instead, all you to conditionally call `skipWaiting()`. + * * @param {boolean} [config.sourcemap=true] Whether to create a sourcemap * for the generated service worker files. - * @param {string} config.globDirectory The local directory you wish to match - * `globPatterns` against. The path is relative to the current directory. - * @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} [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} [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 {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 @@ -154,6 +183,7 @@ const writeServiceWorkerUsingDefaultTemplate = * 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, size: number, warnings: Array}>} * A promise that resolves once the service worker and related files * (indicated by `filePaths`) has been written to `swDest`. The `size` property diff --git a/packages/workbox-build/src/get-manifest.js b/packages/workbox-build/src/get-manifest.js index 4e0069e0d..a91c9d43b 100644 --- a/packages/workbox-build/src/get-manifest.js +++ b/packages/workbox-build/src/get-manifest.js @@ -17,27 +17,57 @@ const validate = require('./lib/validate-options'); * 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} [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} [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} [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} [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} [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 @@ -45,25 +75,7 @@ const validate = require('./lib/validate-options'); * 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.globDirectory The local directory you wish to match - * `globPatterns` against. The path is relative to the current directory. - * @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} [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} [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 {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 @@ -71,6 +83,7 @@ const validate = require('./lib/validate-options'); * 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, size: number, warnings: Array}>} * A promise that resolves once the service worker and related files * (indicated by `filePaths`) has been written to `swDest`. The `size` property diff --git a/packages/workbox-build/src/inject-manifest.js b/packages/workbox-build/src/inject-manifest.js index 06990f54b..a501d0801 100644 --- a/packages/workbox-build/src/inject-manifest.js +++ b/packages/workbox-build/src/inject-manifest.js @@ -33,30 +33,69 @@ const validate = require('./lib/validate-options'); * 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 {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} [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} [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} [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} [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} [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 @@ -64,25 +103,7 @@ const validate = require('./lib/validate-options'); * 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.globDirectory The local directory you wish to match - * `globPatterns` against. The path is relative to the current directory. - * @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} [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} [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 {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 @@ -90,12 +111,7 @@ const validate = require('./lib/validate-options'); * 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. - * @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 {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. + * * @return {Promise<{count: number, filePaths: Array, size: number, warnings: Array}>} * A promise that resolves once the service worker and related files * (indicated by `filePaths`) has been written to `swDest`. The `size` property diff --git a/packages/workbox-webpack-plugin/src/generate-sw.js b/packages/workbox-webpack-plugin/src/generate-sw.js index d95ec95d8..16ed4f858 100644 --- a/packages/workbox-webpack-plugin/src/generate-sw.js +++ b/packages/workbox-webpack-plugin/src/generate-sw.js @@ -39,76 +39,109 @@ class GenerateSW { * Creates an instance of GenerateSW. * * @param {Object} config The configuration to use. - * @param {string} [config.swDest='service-worker.js'] The asset name of the - * service worker file that will be created by this plugin. - * @param {Array} [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} [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 {Array} [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} [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 {Array} [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 an 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} [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. 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 {Array} [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} [config.excludeChunks] One or more chunk names whose + * corresponding output files should be excluded from the precache manifest. + * * @param {Array} [config.ignoreURLParametersMatching=[/^utm_/]] * 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} [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} [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} [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} [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` compiltion + * will be used. + * + * @param {Object} [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} [config.navigateFallbackBlacklist] An optional array * of regular expressions that restricts which URLs the configured * `navigateFallback` behavior applies to. This is useful if only a subset of @@ -116,6 +149,7 @@ class GenerateSW { * [Single Page App](https://en.wikipedia.org/wiki/Single-page_application). If * both `navigateFallbackBlacklist` and `navigateFallbackWhitelist` are * configured, the blacklist takes precedent. + * * @param {Array} [config.navigateFallbackWhitelist] An optional array * of regular expressions that restricts which URLs the configured * `navigateFallback` behavior applies to. This is useful if only a subset of @@ -123,11 +157,13 @@ class GenerateSW { * [Single Page App](https://en.wikipedia.org/wiki/Single-page_application). If * both `navigateFallbackBlacklist` and `navigateFallbackWhitelist` are * configured, the blacklist 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). @@ -135,27 +171,19 @@ class GenerateSW { * 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} [config.runtimeCaching] + * * @param {boolean} [config.skipWaiting=false] Whether to add an * unconditional call to [`skipWaiting()`](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.core#.skipWaiting) * to the generated service worker. If `false`, then a `message` listener will * be added instead, all you to conditionally call `skipWaiting()`. + * * @param {boolean} [config.sourcemap=true] Whether to create a sourcemap * for the generated service worker files. - * @param {Array} [chunks] One or more chunk names whose corresponding - * output files should be included in the precache manifest. - * @param {Array} [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} [excludeChunks] One or more chunk names whose - * corresponding output files should be excluded from the precache manifest. - * @param {Array} [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.swDest='service-worker.js'] The asset name of the + * service worker file that will be created by this plugin. */ constructor(config = {}) { this.config = config; diff --git a/packages/workbox-webpack-plugin/src/inject-manifest.js b/packages/workbox-webpack-plugin/src/inject-manifest.js index 201cf154e..e26897d3c 100644 --- a/packages/workbox-webpack-plugin/src/inject-manifest.js +++ b/packages/workbox-webpack-plugin/src/inject-manifest.js @@ -42,37 +42,62 @@ class InjectManifest { * Creates an instance of GenerateSW. * * @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 {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} [webpackCompilationPlugins] Optional `webpack` - * plugins that will be used when compiling the `swSrc` input file. - * @param {Array} [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} [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} [config.chunks] One or more chunk names whose corresponding + * output files should be included in the precache manifest. + * * @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 {Array} [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} [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} [config.excludeChunks] One or more chunk names whose + * corresponding output files should be excluded from the precache manifest. + * + * @param {Array} [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} [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 {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` compiltion + * will be used. + * * @param {Object} [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 @@ -80,23 +105,13 @@ class InjectManifest { * 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.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} [chunks] One or more chunk names whose corresponding - * output files should be included in the precache manifest. - * @param {Array} [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} [excludeChunks] One or more chunk names whose - * corresponding output files should be excluded from the precache manifest. - * @param {Array} [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.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} [config.webpackCompilationPlugins] Optional `webpack` + * plugins that will be used when compiling the `swSrc` input file. */ constructor(config = {}) { this.config = config; From e484cc9323b8b1fa6a72a6f47ef8a389e5e40d5f Mon Sep 17 00:00:00 2001 From: Jeff Posnick Date: Thu, 9 Jan 2020 16:29:28 -0500 Subject: [PATCH 11/16] Alphabetizing --- packages/workbox-build/src/_types.js | 50 +++++++++++++++++++--------- 1 file changed, 35 insertions(+), 15 deletions(-) diff --git a/packages/workbox-build/src/_types.js b/packages/workbox-build/src/_types.js index 5579f6aad..388136c74 100644 --- a/packages/workbox-build/src/_types.js +++ b/packages/workbox-build/src/_types.js @@ -30,57 +30,77 @@ import './_version.mjs'; /** * @typedef {Object} RuntimeCachingEntry * - * @property {string} [method='GET'] The - * [HTTP method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) that - * will match the generated route. - * @property {string|RegExp|workbox.routing.Route~matchCallback} urlPattern - * The value that will be passed to workbox.routing.Router~registerRoute, used - * to determine whether the generated route will match a given request. * @property {string|workbox.routing.Route~handlerCallback} handler * Either the name of one of the [built-in strategy classes](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.strategies), * or custom handler callback to use when the generated route matches. + * + * @property {string|RegExp|workbox.routing.Route~matchCallback} urlPattern + * The value that will be passed to workbox.routing.Router~registerRoute, used + * to determine whether the generated route will match a given request. + * + * @property {string} [method='GET'] The + * [HTTP method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) that + * will match the generated route. + * * @property {Object} [options] + * * @property {Object} [options.backgroundSync] - * @property {string} options.backgroundSync.name The + * + * @property {string} [options.backgroundSync.name] The * [`name` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.backgroundSync.Queue.html) * to use when creating the `BackgroundSyncPlugin`. + * * @property {Object} [options.backgroundSync.options] The * [`options` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.backgroundSync.Queue.html) * to use when creating the `BackgroundSyncPlugin`. + * * @property {Object} [options.broadcastUpdate] - * @property {string} options.broadcastUpdate.channelName + * + * @property {string} [options.broadcastUpdate.channelName] * The [`channelName` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.broadcastUpdate.BroadcastCacheUpdate) * to use when creating the `BroadcastCacheUpdatePlugin`. + * * @property {Object} [options.broadcastUpdate.options] The * [`options` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.broadcastUpdate.BroadcastCacheUpdate) * to use when creating the `BroadcastCacheUpdatePlugin`. + * * @property {Object} [options.cacheableResponse] - * @property {Array} [options.cacheableResponse.statuses] - * The [`status` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.cacheableResponse.CacheableResponse) - * to use when creating the `CacheableResponsePlugin`. + * * @property {Object} [options.cacheableResponse.headers] * The [`headers` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.cacheableResponse.CacheableResponse) * to use when creating the `CacheableResponsePlugin`. + * + * @property {Array} [options.cacheableResponse.statuses] + * The [`status` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.cacheableResponse.CacheableResponse) + * to use when creating the `CacheableResponsePlugin`. + * * @property {string} [options.cacheName] The `cacheName` * to use when constructing one of the [Workbox strategy classes](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.strategies). + * + * @property {Object} [options.fetchOptions] + * The `fetchOptions` property value to use when creating the handler. + * * @property {Object} [options.expiration] + * * @property {number} [options.expiration.maxAgeSeconds] * The [`maxAgeSeconds` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.expiration.CacheExpiration) * to use when creating the `CacheExpirationPlugin`. + * * @property {number} [options.expiration.maxEntries] * The [`maxAgeSeconds` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.expiration.CacheExpiration) * to use when creating the `CacheExpirationPlugin`. + * + * @property {Object} [options.matchOptions] + * The `matchOptions` property value to use when creating the handler. + * * @property {number} [options.networkTimeoutSeconds] * The `networkTimeoutSeconds` property value to use when creating a * `NetworkFirst` handler. + * * @property {Array} [options.plugins] * One or more [additional plugins](https://developers.google.com/web/tools/workbox/guides/using-plugins#custom_plugins) * to apply to the handler. Useful when you want a plugin that doesn't have a * "shortcut" configuration, like `expiration` or `cacheableResponse`. - * @property {Object} [options.fetchOptions] - * The `fetchOptions` property value to use when creating the handler. - * @property {Object} [options.matchOptions] - * The `matchOptions` property value to use when creating the handler. * * @memberof module:workbox-build */ From 2fc79930e68b0ba886209c128a7cdff6f9e8a0f4 Mon Sep 17 00:00:00 2001 From: Jeff Posnick Date: Thu, 9 Jan 2020 16:30:42 -0500 Subject: [PATCH 12/16] Linting --- packages/workbox-build/src/_types.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/workbox-build/src/_types.js b/packages/workbox-build/src/_types.js index 388136c74..67b5b74bd 100644 --- a/packages/workbox-build/src/_types.js +++ b/packages/workbox-build/src/_types.js @@ -33,7 +33,7 @@ import './_version.mjs'; * @property {string|workbox.routing.Route~handlerCallback} handler * Either the name of one of the [built-in strategy classes](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.strategies), * or custom handler callback to use when the generated route matches. - * + * * @property {string|RegExp|workbox.routing.Route~matchCallback} urlPattern * The value that will be passed to workbox.routing.Router~registerRoute, used * to determine whether the generated route will match a given request. From a90f827b6417bfa255665332e4dc224571080ef5 Mon Sep 17 00:00:00 2001 From: Jeff Posnick Date: Wed, 15 Jan 2020 15:58:51 -0500 Subject: [PATCH 13/16] Updates to use the JSDoc module syntax --- packages/workbox-build/src/_types.js | 8 ++++---- packages/workbox-routing/src/Route.ts | 4 ++-- .../workbox-webpack-plugin/src/generate-sw.js | 12 ++++++------ .../src/inject-manifest.js | 16 ++++++++-------- 4 files changed, 20 insertions(+), 20 deletions(-) diff --git a/packages/workbox-build/src/_types.js b/packages/workbox-build/src/_types.js index 67b5b74bd..7dcea956a 100644 --- a/packages/workbox-build/src/_types.js +++ b/packages/workbox-build/src/_types.js @@ -30,13 +30,13 @@ import './_version.mjs'; /** * @typedef {Object} RuntimeCachingEntry * - * @property {string|workbox.routing.Route~handlerCallback} handler + * @property {string|module:workbox-routing~handlerCallback} handler * Either the name of one of the [built-in strategy classes](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.strategies), * or custom handler callback to use when the generated route matches. * - * @property {string|RegExp|workbox.routing.Route~matchCallback} urlPattern - * The value that will be passed to workbox.routing.Router~registerRoute, used - * to determine whether the generated route will match a given request. + * @property {string|RegExp|module:workbox-routing~matchCallback} urlPattern + * The value that will be passed to [`registerRoute()`]{@link module:workbox-routing.registerRoute}, + * used to determine whether the generated route will match a given request. * * @property {string} [method='GET'] The * [HTTP method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) that diff --git a/packages/workbox-routing/src/Route.ts b/packages/workbox-routing/src/Route.ts index fa9e0b708..da8a728e1 100644 --- a/packages/workbox-routing/src/Route.ts +++ b/packages/workbox-routing/src/Route.ts @@ -30,7 +30,7 @@ class Route { /** * Constructor for Route class. * - * @param {module:workbox-routing.Route~matchCallback} match + * @param {module:workbox-routing~matchCallback} match * A callback function that determines whether the route matches a given * `fetch` event by returning a non-falsy value. * @param {module:workbox-routing~handlerCallback} handler A callback @@ -56,7 +56,7 @@ class Route { } // These values are referenced directly by Router so cannot be - // altered by minifification. + // altered by minificaton. this.handler = normalizeHandler(handler); this.match = match; this.method = method; diff --git a/packages/workbox-webpack-plugin/src/generate-sw.js b/packages/workbox-webpack-plugin/src/generate-sw.js index 0adbfaf9a..daa9789a0 100644 --- a/packages/workbox-webpack-plugin/src/generate-sw.js +++ b/packages/workbox-webpack-plugin/src/generate-sw.js @@ -40,7 +40,7 @@ class GenerateSW { * * @param {Object} config The configuration to use. * - * @param {Array} [config.additionalManifestEntries] + * @param {Array} [config.additionalManifestEntries] * A list of entries to be precached, in addition to any entries that are * generated as part of the build configuration. * @@ -112,10 +112,10 @@ class GenerateSW { * 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} [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 {Array} [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 @@ -172,7 +172,7 @@ class GenerateSW { * will be passed in to the `initialize()` call, allowing you to customize the * behavior. * - * @param {Array} [config.runtimeCaching] + * @param {Array} [config.runtimeCaching] * * @param {boolean} [config.skipWaiting=false] Whether to add an * unconditional call to [`skipWaiting()`](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.core#.skipWaiting) diff --git a/packages/workbox-webpack-plugin/src/inject-manifest.js b/packages/workbox-webpack-plugin/src/inject-manifest.js index c1109de62..398fda1f4 100644 --- a/packages/workbox-webpack-plugin/src/inject-manifest.js +++ b/packages/workbox-webpack-plugin/src/inject-manifest.js @@ -39,14 +39,14 @@ const _generatedAssetNames = new Set(); class InjectManifest { // eslint-disable-next-line jsdoc/newline-after-description /** - * Creates an instance of GenerateSW. + * 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} [config.additionalManifestEntries] + * @param {Array} [config.additionalManifestEntries] * A list of entries to be precached, in addition to any entries that are * generated as part of the build configuration. * @@ -83,10 +83,10 @@ class InjectManifest { * find inside of the `swSrc` file. Once found, it will be replaced by the * generated precache manifest. * - * @param {Array} [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 {Array} [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 @@ -95,8 +95,8 @@ class InjectManifest { * * @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` compiltion - * will be used. + * configured here, the `mode` value configured in the current `webpack` + * compilation will be used. * * @param {Object} [config.modifyURLPrefix] A mapping of prefixes * that, if present in an entry in the precache manifest, will be replaced with From 15cedc5dfab42936228ff895665cb08b863541ef Mon Sep 17 00:00:00 2001 From: Jeff Posnick Date: Wed, 15 Jan 2020 16:57:17 -0500 Subject: [PATCH 14/16] Move off of d.g.c URLs --- packages/workbox-build/src/_types.js | 73 ++++++++++--------- packages/workbox-build/src/generate-sw.js | 2 +- packages/workbox-streams/README.md | 2 +- .../workbox-webpack-plugin/src/generate-sw.js | 2 +- 4 files changed, 41 insertions(+), 38 deletions(-) diff --git a/packages/workbox-build/src/_types.js b/packages/workbox-build/src/_types.js index 7dcea956a..5757c1c67 100644 --- a/packages/workbox-build/src/_types.js +++ b/packages/workbox-build/src/_types.js @@ -31,7 +31,7 @@ import './_version.mjs'; * @typedef {Object} RuntimeCachingEntry * * @property {string|module:workbox-routing~handlerCallback} handler - * Either the name of one of the [built-in strategy classes](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.strategies), + * Either the name of one of the [built-in strategy classes]{@link module:workbox-strategies}, * or custom handler callback to use when the generated route matches. * * @property {string|RegExp|module:workbox-routing~matchCallback} urlPattern @@ -46,61 +46,64 @@ import './_version.mjs'; * * @property {Object} [options.backgroundSync] * - * @property {string} [options.backgroundSync.name] The - * [`name` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.backgroundSync.Queue.html) - * to use when creating the `BackgroundSyncPlugin`. + * @property {string} [options.backgroundSync.name] The `name` property to use + * when creating the + * [`BackgroundSyncPlugin`]{@link module:workbox-background-sync.BackgroundSyncPlugin}. * - * @property {Object} [options.backgroundSync.options] The - * [`options` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.backgroundSync.Queue.html) - * to use when creating the `BackgroundSyncPlugin`. + * @property {Object} [options.backgroundSync.options] The `options` property + * to use when creating the + * [`BackgroundSyncPlugin`]{@link module:workbox-background-sync.BackgroundSyncPlugin}. * * @property {Object} [options.broadcastUpdate] * - * @property {string} [options.broadcastUpdate.channelName] - * The [`channelName` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.broadcastUpdate.BroadcastCacheUpdate) - * to use when creating the `BroadcastCacheUpdatePlugin`. + * @property {string} [options.broadcastUpdate.channelName] The `channelName` + * property to use when creating the + * [`BroadcastCacheUpdatePlugin`]{@link module:workbox-broadcast-update.BroadcastUpdatePlugin}. * - * @property {Object} [options.broadcastUpdate.options] The - * [`options` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.broadcastUpdate.BroadcastCacheUpdate) - * to use when creating the `BroadcastCacheUpdatePlugin`. + * @property {Object} [options.broadcastUpdate.options] The `options` property + * to use when creating the + * [`BroadcastCacheUpdatePlugin`]{@link module:workbox-broadcast-update.BroadcastUpdatePlugin}. * * @property {Object} [options.cacheableResponse] * - * @property {Object} [options.cacheableResponse.headers] - * The [`headers` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.cacheableResponse.CacheableResponse) - * to use when creating the `CacheableResponsePlugin`. + * @property {Object} [options.cacheableResponse.headers] The `headers` property + * to use when creating the + * [`CacheableResponsePlugin`]{@link module:workbox-cacheable-response.CacheableResponsePlugin}. * - * @property {Array} [options.cacheableResponse.statuses] - * The [`status` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.cacheableResponse.CacheableResponse) - * to use when creating the `CacheableResponsePlugin`. + * @property {Array} [options.cacheableResponse.statuses] `statuses` + * property to use when creating the + * [`CacheableResponsePlugin`]{@link module:workbox-cacheable-response.CacheableResponsePlugin}. * - * @property {string} [options.cacheName] The `cacheName` - * to use when constructing one of the [Workbox strategy classes](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.strategies). + * @property {string} [options.cacheName] The `cacheName` to use when + * constructing one of the + * [Workbox strategy classes]{@link module:workbox-strategies}. * - * @property {Object} [options.fetchOptions] - * The `fetchOptions` property value to use when creating the handler. + * @property {Object} [options.fetchOptions] The `fetchOptions` property value + * to use when constructing one of the + * [Workbox strategy classes]{@link module:workbox-strategies}. * * @property {Object} [options.expiration] * - * @property {number} [options.expiration.maxAgeSeconds] - * The [`maxAgeSeconds` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.expiration.CacheExpiration) - * to use when creating the `CacheExpirationPlugin`. + * @property {number} [options.expiration.maxAgeSeconds] The `maxAgeSeconds` + * property to use when creating the + * [`ExpirationPlugin`]{@link module:workbox-expiration.ExpirationPlugin}. * - * @property {number} [options.expiration.maxEntries] - * The [`maxAgeSeconds` property](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.expiration.CacheExpiration) - * to use when creating the `CacheExpirationPlugin`. + * @property {number} [options.expiration.maxEntries] The `maxAgeSeconds` + * property to use when creating the + * [`ExpirationPlugin`]{@link module:workbox-expiration.ExpirationPlugin}. * - * @property {Object} [options.matchOptions] - * The `matchOptions` property value to use when creating the handler. + * @property {Object} [options.matchOptions] The `matchOptions` property value + * to use when constructing one of the + * [Workbox strategy classes]{@link module:workbox-strategies}. * - * @property {number} [options.networkTimeoutSeconds] - * The `networkTimeoutSeconds` property value to use when creating a - * `NetworkFirst` handler. + * @property {number} [options.networkTimeoutSeconds] The + * `networkTimeoutSeconds` property value to use when creating a + * [`NetworkFirst`]{@link module:workbox-strategies.NetworkFirst} strategy. * * @property {Array} [options.plugins] * One or more [additional plugins](https://developers.google.com/web/tools/workbox/guides/using-plugins#custom_plugins) * to apply to the handler. Useful when you want a plugin that doesn't have a - * "shortcut" configuration, like `expiration` or `cacheableResponse`. + * "shortcut" configuration. * * @memberof module:workbox-build */ diff --git a/packages/workbox-build/src/generate-sw.js b/packages/workbox-build/src/generate-sw.js index 385562113..4ac75841e 100644 --- a/packages/workbox-build/src/generate-sw.js +++ b/packages/workbox-build/src/generate-sw.js @@ -169,7 +169,7 @@ const writeServiceWorkerUsingDefaultTemplate = * @param {Array} [config.runtimeCaching] * * @param {boolean} [config.skipWaiting=false] Whether to add an - * unconditional call to [`skipWaiting()`](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.core#.skipWaiting) + * unconditional call to [`skipWaiting()`]{@link module:workbox-core.skipWaiting} * to the generated service worker. If `false`, then a `message` listener will * be added instead, all you to conditionally call `skipWaiting()`. * diff --git a/packages/workbox-streams/README.md b/packages/workbox-streams/README.md index de74a674e..e3efd1052 100644 --- a/packages/workbox-streams/README.md +++ b/packages/workbox-streams/README.md @@ -1 +1 @@ -This module's documentation can be found at https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.streams +This module's documentation can be found at https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox-streams diff --git a/packages/workbox-webpack-plugin/src/generate-sw.js b/packages/workbox-webpack-plugin/src/generate-sw.js index daa9789a0..5e14ae579 100644 --- a/packages/workbox-webpack-plugin/src/generate-sw.js +++ b/packages/workbox-webpack-plugin/src/generate-sw.js @@ -175,7 +175,7 @@ class GenerateSW { * @param {Array} [config.runtimeCaching] * * @param {boolean} [config.skipWaiting=false] Whether to add an - * unconditional call to [`skipWaiting()`](https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox.core#.skipWaiting) + * unconditional call to [`skipWaiting()`]{@link module:workbox-core.skipWaiting} * to the generated service worker. If `false`, then a `message` listener will * be added instead, all you to conditionally call `skipWaiting()`. * From 8ef79087497bfb3d43dd5d43b2010cec7574ca75 Mon Sep 17 00:00:00 2001 From: Jeff Posnick Date: Wed, 15 Jan 2020 16:59:34 -0500 Subject: [PATCH 15/16] Typo fix --- packages/workbox-build/src/generate-sw.js | 2 +- packages/workbox-webpack-plugin/src/generate-sw.js | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/workbox-build/src/generate-sw.js b/packages/workbox-build/src/generate-sw.js index 4ac75841e..f62f35e77 100644 --- a/packages/workbox-build/src/generate-sw.js +++ b/packages/workbox-build/src/generate-sw.js @@ -171,7 +171,7 @@ const writeServiceWorkerUsingDefaultTemplate = * @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, all you to conditionally call `skipWaiting()`. + * be added instead, allowing you to conditionally call `skipWaiting()`. * * @param {boolean} [config.sourcemap=true] Whether to create a sourcemap * for the generated service worker files. diff --git a/packages/workbox-webpack-plugin/src/generate-sw.js b/packages/workbox-webpack-plugin/src/generate-sw.js index 5e14ae579..d0fd13379 100644 --- a/packages/workbox-webpack-plugin/src/generate-sw.js +++ b/packages/workbox-webpack-plugin/src/generate-sw.js @@ -177,7 +177,7 @@ class GenerateSW { * @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, all you to conditionally call `skipWaiting()`. + * be added instead, allowing you to conditionally call `skipWaiting()`. * * @param {boolean} [config.sourcemap=true] Whether to create a sourcemap * for the generated service worker files. From d3c3b71165deb85be06fe5b8b6804c1fecb982c0 Mon Sep 17 00:00:00 2001 From: Jeff Posnick Date: Wed, 15 Jan 2020 17:08:17 -0500 Subject: [PATCH 16/16] module-workbox-streams --- packages/workbox-streams/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/workbox-streams/README.md b/packages/workbox-streams/README.md index e3efd1052..8abfa9cd3 100644 --- a/packages/workbox-streams/README.md +++ b/packages/workbox-streams/README.md @@ -1 +1 @@ -This module's documentation can be found at https://developers.google.com/web/tools/workbox/reference-docs/latest/workbox-streams +This module's documentation can be found at https://developers.google.com/web/tools/workbox/reference-docs/latest/module-workbox-streams