diff --git a/packages/workbox-build/src/_types.js b/packages/workbox-build/src/_types.js index 0f11a72d9..5757c1c67 100644 --- a/packages/workbox-build/src/_types.js +++ b/packages/workbox-build/src/_types.js @@ -26,3 +26,84 @@ import './_version.mjs'; * * @memberof module:workbox-build */ + +/** + * @typedef {Object} RuntimeCachingEntry + * + * @property {string|module:workbox-routing~handlerCallback} handler + * 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 + * 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 + * will match the generated route. + * + * @property {Object} [options] + * + * @property {Object} [options.backgroundSync] + * + * @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 + * to use when creating the + * [`BackgroundSyncPlugin`]{@link module:workbox-background-sync.BackgroundSyncPlugin}. + * + * @property {Object} [options.broadcastUpdate] + * + * @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 + * to use when creating the + * [`BroadcastCacheUpdatePlugin`]{@link module:workbox-broadcast-update.BroadcastUpdatePlugin}. + * + * @property {Object} [options.cacheableResponse] + * + * @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] `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]{@link module:workbox-strategies}. + * + * @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 to use when creating the + * [`ExpirationPlugin`]{@link module:workbox-expiration.ExpirationPlugin}. + * + * @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 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`]{@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. + * + * @memberof module:workbox-build + */ diff --git a/packages/workbox-build/src/generate-sw.js b/packages/workbox-build/src/generate-sw.js index 73a7fb938..f62f35e77 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 jsdoc/newline-after-description /** * This method creates a list of URLs to precache, referred to as a "precache * manifest", based on the options you provide. @@ -25,8 +26,164 @@ 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.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 {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 + * 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()`]{@link module:workbox-core.skipWaiting} + * to the generated service worker. If `false`, then a `message` listener will + * be added instead, allowing you to conditionally call `skipWaiting()`. + * + * @param {boolean} [config.sourcemap=true] Whether to create a sourcemap + * for the generated service worker files. + * + * @param {Object} [config.templatedURLs] If a URL is rendered based on some + * server-side logic, its contents may depend on multiple files or on some other + * unique string value. The keys in this object are server-rendered URLs. If the + * values are an array of strings, they will be interpreted as `glob` patterns, + * and the contents of any files matching the patterns will be used to uniquely + * version the URL. If used with a single string, it will be interpreted as + * unique versioning information that you've generated for a given URL. + * * @return {Promise<{count: number, filePaths: Array, 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 a11ea7777..a91c9d43b 100644 --- a/packages/workbox-build/src/get-manifest.js +++ b/packages/workbox-build/src/get-manifest.js @@ -10,19 +10,85 @@ 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 {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 + * path prefix from a manifest entry if your web hosting setup doesn't match + * your local filesystem setup. As an alternative with more flexibility, you can + * use the `manifestTransforms` option and provide a function that modifies the + * entries in the manifest using whatever logic you provide. + * + * @param {Object} [config.templatedURLs] If a URL is rendered based on some + * server-side logic, its contents may depend on multiple files or on some other + * unique string value. The keys in this object are server-rendered URLs. If the + * values are an array of strings, they will be interpreted as `glob` patterns, + * and the contents of any files matching the patterns will be used to uniquely + * version the URL. If used with a single string, it will be interpreted as + * unique versioning information that you've generated for a given URL. + * + * @return {Promise<{count: number, filePaths: Array, 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 diff --git a/packages/workbox-build/src/inject-manifest.js b/packages/workbox-build/src/inject-manifest.js index f0039274f..24dd3d5d6 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,86 @@ 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.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 + * path prefix from a manifest entry if your web hosting setup doesn't match + * your local filesystem setup. As an alternative with more flexibility, you can + * use the `manifestTransforms` option and provide a function that modifies the + * entries in the manifest using whatever logic you provide. + * + * @param {Object} [config.templatedURLs] If a URL is rendered based on some + * server-side logic, its contents may depend on multiple files or on some other + * unique string value. The keys in this object are server-rendered URLs. If the + * values are an array of strings, they will be interpreted as `glob` patterns, + * and the contents of any files matching the patterns will be used to uniquely + * version the URL. If used with a single string, it will be interpreted as + * unique versioning information that you've generated for a given URL. + * * @return {Promise<{count: number, filePaths: Array, 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-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 diff --git a/packages/workbox-core/src/skipWaiting.ts b/packages/workbox-core/src/skipWaiting.ts index 5e8885351..3b034cd4b 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. * * @memberof module:workbox-core */ diff --git a/packages/workbox-routing/src/RegExpRoute.ts b/packages/workbox-routing/src/RegExpRoute.ts index cc742becc..c5b5d7ffd 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 module:workbox-routing~handlerCallback} `params` * argument. * 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-streams/README.md b/packages/workbox-streams/README.md index de74a674e..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 diff --git a/packages/workbox-webpack-plugin/src/generate-sw.js b/packages/workbox-webpack-plugin/src/generate-sw.js index e0800057f..d0fd13379 100644 --- a/packages/workbox-webpack-plugin/src/generate-sw.js +++ b/packages/workbox-webpack-plugin/src/generate-sw.js @@ -34,12 +34,156 @@ const _generatedAssetNames = new Set(); * @memberof 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 {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.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 + * 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()`]{@link module:workbox-core.skipWaiting} + * to the generated service worker. If `false`, then a `message` listener will + * be added instead, allowing you to conditionally call `skipWaiting()`. + * + * @param {boolean} [config.sourcemap=true] Whether to create a sourcemap + * for the generated service worker files. + * + * @param {string} [config.swDest='service-worker.js'] The asset name of the + * service worker file that will be created by this plugin. */ constructor(config = {}) { this.config = config; diff --git a/packages/workbox-webpack-plugin/src/inject-manifest.js b/packages/workbox-webpack-plugin/src/inject-manifest.js index e7add6f91..398fda1f4 100644 --- a/packages/workbox-webpack-plugin/src/inject-manifest.js +++ b/packages/workbox-webpack-plugin/src/inject-manifest.js @@ -37,12 +37,81 @@ const _generatedAssetNames = new Set(); * @memberof module:workbox-webpack-plugin */ class InjectManifest { + // eslint-disable-next-line jsdoc/newline-after-description /** * Creates an instance of InjectManifest. * - * @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 {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] If set to 'production', then an optimized service + * worker bundle that excludes debugging info will be produced. If not explicitly + * configured here, the `mode` value configured in the current `webpack` + * compilation will be used. + * + * @param {Object} [config.modifyURLPrefix] A mapping of prefixes + * that, if present in an entry in the precache manifest, will be replaced with + * the corresponding value. This can be used to, for example, remove or add a + * path prefix from a manifest entry if your web hosting setup doesn't match + * your local filesystem setup. As an alternative with more flexibility, you can + * use the `manifestTransforms` option and provide a function that modifies the + * entries in the manifest using whatever logic you provide. + * + * @param {string} [config.swDest] The asset name of the + * service worker file that will be created by this plugin. If omitted, the + * name will be based on the `swSrc` name. + * + * @param {Array} [config.webpackCompilationPlugins] Optional `webpack` + * plugins that will be used when compiling the `swSrc` input file. */ constructor(config = {}) { this.config = config;