diff --git a/packages/workbox-build/src/generate-sw.ts b/packages/workbox-build/src/generate-sw.ts index ba803fb4d..d6193e23c 100644 --- a/packages/workbox-build/src/generate-sw.ts +++ b/packages/workbox-build/src/generate-sw.ts @@ -14,7 +14,6 @@ import {rebasePath} from './lib/rebase-path'; import {validateGenerateSWOptions} from './lib/validate-options'; import {writeSWUsingDefaultTemplate} from './lib/write-sw-using-default-template'; -// eslint-disable-next-line jsdoc/newline-after-description /** * This method creates a list of URLs to precache, referred to as a "precache * manifest", based on the options you provide. @@ -25,171 +24,37 @@ import {writeSWUsingDefaultTemplate} from './lib/write-sw-using-default-template * Based on the precache manifest and the additional configuration, it writes * a ready-to-use service worker file to disk at `swDest`. * - * @param {Object} config The configuration to use. - * - * @param {string} config.globDirectory The local directory you wish to match - * `globPatterns` against. The path is relative to the current directory. - * - * @param {string} config.swDest The path and filename of the service worker file - * that will be created by the build process, relative to the current working - * directory. It must end in '.js'. - * - * @param {Array} [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 and delete any precaches created by older, - * incompatible versions. - * - * @param {boolean} [config.clientsClaim=false] Whether or not the service - * worker should [start controlling](https://developers.google.com/web/fundamentals/primers/service-workers/lifecycle#clientsclaim) - * any existing clients as soon as it activates. - * - * @param {string} [config.directoryIndex='index.html'] If a navigation request - * for a URL ending in `/` fails to match a precached URL, this value will be - * appended to the URL and that will be checked for a precache match. This - * should be set to what your web server is using for its directory index. - * - * @param {RegExp} [config.dontCacheBustURLsMatching] Assets that match this will be - * assumed to be uniquely versioned via their URL, and exempted from the normal - * HTTP cache-busting that's done when populating the precache. While not - * required, it's recommended that if your existing build process already - * inserts a `[hash]` value into each filename, you provide a RegExp that will - * detect that, as it will reduce the bandwidth consumed when precaching. - * - * @param {boolean} [config.globFollow=true] Determines whether or not symlinks - * are followed when generating the precache manifest. For more information, see - * the definition of `follow` in the `glob` - * [documentation](https://github.com/isaacs/node-glob#options). - * - * @param {Array} [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_/, /^fbclid$/]] - * Any search parameter names that match against one of the RegExp in this array - * will be removed before looking for a precache match. This is useful if your - * users might request URLs that contain, for example, URL parameters used to - * track the source of the traffic. - * - * @param {Array} [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.navigateFallbackDenylist] An optional array - * of regular expressions that restricts which URLs the configured - * `navigateFallback` behavior applies to. This is useful if only a subset of - * your site's URLs should be treated as being part of a - * [Single Page App](https://en.wikipedia.org/wiki/Single-page_application). If - * both `navigateFallbackDenylist` and `navigateFallbackAllowlist` are - * configured, the denylist takes precedent. - * - * @param {Array} [config.navigateFallbackAllowlist] An optional array - * of regular expressions that restricts which URLs the configured - * `navigateFallback` behavior applies to. This is useful if only a subset of - * your site's URLs should be treated as being part of a - * [Single Page App](https://en.wikipedia.org/wiki/Single-page_application). If - * both `navigateFallbackDenylist` and `navigateFallbackAllowlist` are - * configured, the denylist takes precedent. - * - * @param {boolean} [config.navigationPreload=false] Whether or not to enable - * [navigation preload](https://developers.google.com/web/tools/workbox/modules/workbox-navigation-preload) - * in the generated service worker. When set to true, you must also use - * `runtimeCaching` to set up an appropriate response strategy that will match - * navigation requests, and make use of the preloaded response. - * - * @param {boolean|Object} [config.offlineGoogleAnalytics=false] Controls - * whether or not to include support for - * [offline Google Analytics](https://developers.google.com/web/tools/workbox/guides/enable-offline-analytics). - * When `true`, the call to `workbox-google-analytics`'s `initialize()` will be - * added to your generated service worker. When set to an `Object`, that object - * will be passed in to the `initialize()` call, allowing you to customize the - * behavior. - * - * @param {Array} [config.runtimeCaching] - * - * @param {boolean} [config.skipWaiting=false] Whether to add an - * unconditional call to [`skipWaiting()`](https://developers.google.com/web/fundamentals/primers/service-workers/lifecycle#skip_the_waiting_phase) - * to the generated service worker. If `false`, then a `message` listener will - * be added instead, allowing you to conditionally call `skipWaiting()` by posting - * a message containing {type: 'SKIP_WAITING'}. - * - * @param {boolean} [config.sourcemap=true] Whether to create a sourcemap - * for the generated service worker files. - * - * @param {Object} [config.templatedURLs] If a URL is rendered based on some - * server-side logic, its contents may depend on multiple files or on some other - * unique string value. The keys in this object are server-rendered URLs. If the - * values are an array of strings, they will be interpreted as `glob` patterns, - * and the contents of any files matching the patterns will be used to uniquely - * version the URL. If used with a single string, it will be interpreted as - * unique versioning information that you've generated for a given URL. - * - * @return {Promise<{count: number, filePaths: Array, 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`. + * @example + * // The following lists some common options; see the rest of the documentation + * // for the full set of options and defaults. + * const {count, size, warnings} = await generateSW({ + * dontCacheBustURLsMatching: [new RegExp('...')], + * globDirectory: '...', + * globPatterns: ['...', '...'], + * maximumFileSizeToCacheInBytes: ..., + * navigateFallback: '...', + * runtimeCaching: [{ + * // Routing via a matchCallback function: + * urlPattern: ({request, url}) => ..., + * handler: '...', + * options: { + * cacheName: '...', + * expiration: { + * maxEntries: ..., + * }, + * }, + * }, { + * // Routing via a RegExp: + * urlPattern: new RegExp('...'), + * handler: '...', + * options: { + * cacheName: '...', + * plugins: [..., ...], + * }, + * }], + * skipWaiting: ..., + * swDest: '...', + * }); * * @memberof workbox-build */ diff --git a/packages/workbox-build/src/get-manifest.ts b/packages/workbox-build/src/get-manifest.ts index d9c1fce15..051dee759 100644 --- a/packages/workbox-build/src/get-manifest.ts +++ b/packages/workbox-build/src/get-manifest.ts @@ -10,81 +10,20 @@ import {getFileManifestEntries} from './lib/get-file-manifest-entries'; import {GetManifestOptions, GetManifestResult} from './types'; import {validateGetManifestOptions} from './lib/validate-options'; -// eslint-disable-next-line jsdoc/newline-after-description /** * This method returns a list of URLs to precache, referred to as a "precache * manifest", along with details about the number of entries and their size, * based on the options you provide. * - * @param {Object} config The configuration to use. - * - * @param {string} config.globDirectory The local directory you wish to match - * `globPatterns` against. The path is relative to the current directory. - * - * @param {Array} [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 {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, manifestEntries: Array, size: number, warnings: Array}>} - * A promise that resolves once the precache manifest (available in the - * `manifestEntries` property) has been determined. The `size` property - * contains the aggregate size of all the precached entries, in bytes, and the - * `count` property contains the total number of precached entries. Any - * non-fatal warning messages will be returned via `warnings`. + * @example + * // The following lists some common options; see the rest of the documentation + * // for the full set of options and defaults. + * const {count, manifestEntries, size, warnings} = await getManifest({ + * dontCacheBustURLsMatching: [new RegExp('...')], + * globDirectory: '...', + * globPatterns: ['...', '...'], + * maximumFileSizeToCacheInBytes: ..., + * }); * * @memberof workbox-build */ diff --git a/packages/workbox-build/src/inject-manifest.ts b/packages/workbox-build/src/inject-manifest.ts index f31631591..47f403002 100644 --- a/packages/workbox-build/src/inject-manifest.ts +++ b/packages/workbox-build/src/inject-manifest.ts @@ -22,7 +22,6 @@ import {replaceAndUpdateSourceMap} from './lib/replace-and-update-source-map'; import {translateURLToSourcemapPaths} from './lib/translate-url-to-sourcemap-paths'; import {validateInjectManifestOptions} from './lib/validate-options'; -// eslint-disable-next-line jsdoc/newline-after-description /** * This method creates a list of URLs to precache, referred to as a "precache * manifest", based on the options you provide. @@ -33,87 +32,20 @@ import {validateInjectManifestOptions} from './lib/validate-options'; * The final service worker file, with the manifest injected, is written to * disk at `swDest`. * - * @param {Object} config The configuration to use. - * - * @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 {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`. + * This method will not compile or bundle your `swSrc` file; it just handles + * injecting the manifest. + * + * @example + * // The following lists some common options; see the rest of the documentation + * // for the full set of options and defaults. + * const {count, size, warnings} = await injectManifest({ + * dontCacheBustURLsMatching: [new RegExp('...')], + * globDirectory: '...', + * globPatterns: ['...', '...'], + * maximumFileSizeToCacheInBytes: ..., + * swDest: '...', + * swSrc: '...', + * }); * * @memberof workbox-build */ diff --git a/packages/workbox-webpack-plugin/src/generate-sw.ts b/packages/workbox-webpack-plugin/src/generate-sw.ts index 0815b3a6d..8b3c02863 100644 --- a/packages/workbox-webpack-plugin/src/generate-sw.ts +++ b/packages/workbox-webpack-plugin/src/generate-sw.ts @@ -36,162 +36,43 @@ interface GenerateSWConfig extends WebpackGenerateSWOptions { * [`plugins` array](https://webpack.js.org/concepts/plugins/#usage) of a * webpack config. * + * @example + * // The following lists some common options; see the rest of the documentation + * // for the full set of options and defaults. + * new GenerateSW({ + * exclude: [/.../, '...'], + * maximumFileSizeToCacheInBytes: ..., + * navigateFallback: '...', + * runtimeCaching: [{ + * // Routing via a matchCallback function: + * urlPattern: ({request, url}) => ..., + * handler: '...', + * options: { + * cacheName: '...', + * expiration: { + * maxEntries: ..., + * }, + * }, + * }, { + * // Routing via a RegExp: + * urlPattern: new RegExp('...'), + * handler: '...', + * options: { + * cacheName: '...', + * plugins: [..., ...], + * }, + * }], + * skipWaiting: ..., + * }); + * * @memberof module:workbox-webpack-plugin */ class GenerateSW { private config: GenerateSWConfig; private alreadyCalled: boolean; - // eslint-disable-next-line jsdoc/newline-after-description + /** * Creates an instance of GenerateSW. - * - * @param {Object} config The configuration to use. - * - * @param {Array} [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 and delete any precaches created by older, - * incompatible versions. - * - * @param {boolean} [config.clientsClaim=false] Whether or not the service - * worker should [start controlling](https://developers.google.com/web/fundamentals/primers/service-workers/lifecycle#clientsclaim) - * any existing clients as soon as it activates. - * - * @param {Array} [config.chunks] One or more chunk names whose corresponding - * output files should be included in the precache manifest. - * - * @param {string} [config.directoryIndex='index.html'] If a navigation request - * for a URL ending in `/` fails to match a precached URL, this value will be - * appended to the URL and that will be checked for a precache match. This - * should be set to what your web server is using for its directory index. - * - * @param {RegExp} [config.dontCacheBustURLsMatching] Assets that match this will be - * assumed to be uniquely versioned via their URL, and exempted from the normal - * HTTP cache-busting that's done when populating the precache. (As of Workbox - * v6, this option is usually not needed, as each - * [asset's metadata](https://github.com/webpack/webpack/issues/9038) is used - * to determine whether it's immutable or not.) - * - * @param {Array} [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_/, /^fbclid$/]] - * Any search parameter names that match against one of the RegExp in this array - * will be removed before looking for a precache match. This is useful if your - * users might request URLs that contain, for example, URL parameters used to - * track the source of the traffic. - * - * @param {Array} [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` 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.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.navigateFallbackDenylist] An optional array - * of regular expressions that restricts which URLs the configured - * `navigateFallback` behavior applies to. This is useful if only a subset of - * your site's URLs should be treated as being part of a - * [Single Page App](https://en.wikipedia.org/wiki/Single-page_application). If - * both `navigateFallbackDenylist` and `navigateFallbackAllowlist` are - * configured, the denylist takes precedent. - * - * @param {Array} [config.navigateFallbackAllowlist] An optional array - * of regular expressions that restricts which URLs the configured - * `navigateFallback` behavior applies to. This is useful if only a subset of - * your site's URLs should be treated as being part of a - * [Single Page App](https://en.wikipedia.org/wiki/Single-page_application). If - * both `navigateFallbackDenylist` and `navigateFallbackAllowlist` are - * configured, the denylist takes precedent. - * - * @param {boolean} [config.navigationPreload=false] Whether or not to enable - * [navigation preload](https://developers.google.com/web/tools/workbox/modules/workbox-navigation-preload) - * in the generated service worker. When set to true, you must also use - * `runtimeCaching` to set up an appropriate response strategy that will match - * navigation requests, and make use of the preloaded response. - * - * @param {boolean|Object} [config.offlineGoogleAnalytics=false] Controls - * whether or not to include support for - * [offline Google Analytics](https://developers.google.com/web/tools/workbox/guides/enable-offline-analytics). - * When `true`, the call to `workbox-google-analytics`'s `initialize()` will be - * added to your generated service worker. When set to an `Object`, that object - * will be passed in to the `initialize()` call, allowing you to customize the - * behavior. - * - * @param {Array} [config.runtimeCaching] - * - * @param {boolean} [config.skipWaiting=false] Whether to add an - * unconditional call to [`skipWaiting()`]{@link module:workbox-core.skipWaiting} - * to the generated service worker. If `false`, then a `message` listener will - * be added instead, allowing you to conditionally call `skipWaiting()` by posting - * a message containing {type: 'SKIP_WAITING'}. - * - * @param {boolean} [config.sourcemap=true] Whether to create a sourcemap - * for the generated service worker files. - * - * @param {string} [config.swDest='service-worker.js'] The asset name of the - * service worker file that will be created by this plugin. */ constructor(config: GenerateSWConfig = {}) { this.config = config; diff --git a/packages/workbox-webpack-plugin/src/inject-manifest.ts b/packages/workbox-webpack-plugin/src/inject-manifest.ts index 0329bcfec..d8f5b3353 100644 --- a/packages/workbox-webpack-plugin/src/inject-manifest.ts +++ b/packages/workbox-webpack-plugin/src/inject-manifest.ts @@ -38,87 +38,26 @@ const {RawSource} = webpack.sources || require('webpack-sources'); * [`plugins` array](https://webpack.js.org/concepts/plugins/#usage) of a * webpack config. * + * In addition to injecting the manifest, this plugin will perform a compilation + * of the `swSrc` file, using the options from the main webpack configuration. + * + * @example + * // The following lists some common options; see the rest of the documentation + * // for the full set of options and defaults. + * new InjectManifest({ + * exclude: [/.../, '...'], + * maximumFileSizeToCacheInBytes: ..., + * swSrc: '...', + * }); + * * @memberof module:workbox-webpack-plugin */ class InjectManifest { private config: WebpackInjectManifestOptions; private alreadyCalled: boolean; - // eslint-disable-next-line jsdoc/newline-after-description + /** * Creates an instance of InjectManifest. - * - * @param {Object} config The configuration to use. - * - * @param {string} config.swSrc An existing service worker file that will be - * compiled and have a precache manifest injected into it. - * - * @param {Array} [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 {boolean} [config.compileSrc=true] When `true` (the default), the - * `swSrc` file will be compiled by webpack. When `false`, compilation will - * not occur (and `webpackCompilationPlugins` can't be used.) Set to `false` - * if you want to inject the manifest into, e.g., a JSON file. - * - * @param {RegExp} [config.dontCacheBustURLsMatching] Assets that match this will be - * assumed to be uniquely versioned via their URL, and exempted from the normal - * HTTP cache-busting that's done when populating the precache. (As of Workbox - * v6, this option is usually not needed, as each - * [asset's metadata](https://github.com/webpack/webpack/issues/9038) is used - * to determine whether it's immutable or not.) - * - * @param {Array} [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.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: WebpackInjectManifestOptions) { this.config = config;