Skip to content

Commit 433b515

Browse files
jeffposnickphilipwalton
jeffposnick
authored and
philipwalton
committed
Update to the build libs JSDoc (#2320)
* WIP. * WIP. * WIP * RuntimeCachingEntry * injectManifest JSDocs * getManifest JSDocs * workbox-cli update * GenerateSW (and random typos) * InjectManifest * Cleanup/reordering * Alphabetizing * Linting * Updates to use the JSDoc module syntax * Move off of d.g.c URLs * Typo fix * module-workbox-streams
1 parent f2cf7f6 commit 433b515

File tree

11 files changed

+625
-29
lines changed

11 files changed

+625
-29
lines changed

‎packages/workbox-build/src/_types.js‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,84 @@ import './_version.mjs';
2626
*
2727
* @memberof module:workbox-build
2828
*/
29+
30+
/**
31+
* @typedef {Object} RuntimeCachingEntry
32+
*
33+
* @property {string|module:workbox-routing~handlerCallback} handler
34+
* Either the name of one of the [built-in strategy classes]{@link module:workbox-strategies},
35+
* or custom handler callback to use when the generated route matches.
36+
*
37+
* @property {string|RegExp|module:workbox-routing~matchCallback} urlPattern
38+
* The value that will be passed to [`registerRoute()`]{@link module:workbox-routing.registerRoute},
39+
* used to determine whether the generated route will match a given request.
40+
*
41+
* @property {string} [method='GET'] The
42+
* [HTTP method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) that
43+
* will match the generated route.
44+
*
45+
* @property {Object} [options]
46+
*
47+
* @property {Object} [options.backgroundSync]
48+
*
49+
* @property {string} [options.backgroundSync.name] The `name` property to use
50+
* when creating the
51+
* [`BackgroundSyncPlugin`]{@link module:workbox-background-sync.BackgroundSyncPlugin}.
52+
*
53+
* @property {Object} [options.backgroundSync.options] The `options` property
54+
* to use when creating the
55+
* [`BackgroundSyncPlugin`]{@link module:workbox-background-sync.BackgroundSyncPlugin}.
56+
*
57+
* @property {Object} [options.broadcastUpdate]
58+
*
59+
* @property {string} [options.broadcastUpdate.channelName] The `channelName`
60+
* property to use when creating the
61+
* [`BroadcastCacheUpdatePlugin`]{@link module:workbox-broadcast-update.BroadcastUpdatePlugin}.
62+
*
63+
* @property {Object} [options.broadcastUpdate.options] The `options` property
64+
* to use when creating the
65+
* [`BroadcastCacheUpdatePlugin`]{@link module:workbox-broadcast-update.BroadcastUpdatePlugin}.
66+
*
67+
* @property {Object} [options.cacheableResponse]
68+
*
69+
* @property {Object} [options.cacheableResponse.headers] The `headers` property
70+
* to use when creating the
71+
* [`CacheableResponsePlugin`]{@link module:workbox-cacheable-response.CacheableResponsePlugin}.
72+
*
73+
* @property {Array<number>} [options.cacheableResponse.statuses] `statuses`
74+
* property to use when creating the
75+
* [`CacheableResponsePlugin`]{@link module:workbox-cacheable-response.CacheableResponsePlugin}.
76+
*
77+
* @property {string} [options.cacheName] The `cacheName` to use when
78+
* constructing one of the
79+
* [Workbox strategy classes]{@link module:workbox-strategies}.
80+
*
81+
* @property {Object} [options.fetchOptions] The `fetchOptions` property value
82+
* to use when constructing one of the
83+
* [Workbox strategy classes]{@link module:workbox-strategies}.
84+
*
85+
* @property {Object} [options.expiration]
86+
*
87+
* @property {number} [options.expiration.maxAgeSeconds] The `maxAgeSeconds`
88+
* property to use when creating the
89+
* [`ExpirationPlugin`]{@link module:workbox-expiration.ExpirationPlugin}.
90+
*
91+
* @property {number} [options.expiration.maxEntries] The `maxAgeSeconds`
92+
* property to use when creating the
93+
* [`ExpirationPlugin`]{@link module:workbox-expiration.ExpirationPlugin}.
94+
*
95+
* @property {Object} [options.matchOptions] The `matchOptions` property value
96+
* to use when constructing one of the
97+
* [Workbox strategy classes]{@link module:workbox-strategies}.
98+
*
99+
* @property {number} [options.networkTimeoutSeconds] The
100+
* `networkTimeoutSeconds` property value to use when creating a
101+
* [`NetworkFirst`]{@link module:workbox-strategies.NetworkFirst} strategy.
102+
*
103+
* @property {Array<Object>} [options.plugins]
104+
* One or more [additional plugins](https://developers.google.com/web/tools/workbox/guides/using-plugins#custom_plugins)
105+
* to apply to the handler. Useful when you want a plugin that doesn't have a
106+
* "shortcut" configuration.
107+
*
108+
* @memberof module:workbox-build
109+
*/

‎packages/workbox-build/src/generate-sw.js‎

Lines changed: 159 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ const validate = require('./lib/validate-options');
1515
const writeServiceWorkerUsingDefaultTemplate =
1616
require('./lib/write-sw-using-default-template');
1717

18+
// eslint-disable-next-line jsdoc/newline-after-description
1819
/**
1920
* This method creates a list of URLs to precache, referred to as a "precache
2021
* manifest", based on the options you provide.
@@ -25,8 +26,164 @@ const writeServiceWorkerUsingDefaultTemplate =
2526
* Based on the precache manifest and the additional configuration, it writes
2627
* a ready-to-use service worker file to disk at `swDest`.
2728
*
28-
* @param {Object} config Please refer to the
29-
* [configuration guide](https://developers.google.com/web/tools/workbox/modules/workbox-build#full_generatesw_config).
29+
* @param {Object} config The configuration to use.
30+
*
31+
* @param {string} config.globDirectory The local directory you wish to match
32+
* `globPatterns` against. The path is relative to the current directory.
33+
*
34+
* @param {string} config.swDest The path and filename of the service worker file
35+
* that will be created by the build process, relative to the current working
36+
* directory. It must end in '.js'.
37+
*
38+
* @param {Array<ManifestEntry>} [config.additionalManifestEntries] A list of
39+
* entries to be precached, in addition to any entries that are generated as
40+
* part of the build configuration.
41+
*
42+
* @param {Array<string>} [config.babelPresetEnvTargets=['chrome >= 56']]
43+
* The [targets](https://babeljs.io/docs/en/babel-preset-env#targets) to pass to
44+
* `babel-preset-env` when transpiling the service worker bundle.
45+
*
46+
* @param {string} [config.cacheId] An optional ID to be prepended to cache
47+
* names. This is primarily useful for local development where multiple sites
48+
* may be served from the same `http://localhost:port` origin.
49+
*
50+
* @param {boolean} [config.cleanupOutdatedCaches=false] Whether or not Workbox
51+
* should attempt to identify an delete any precaches created by older,
52+
* incompatible versions.
53+
*
54+
* @param {boolean} [config.clientsClaim=false] Whether or not the service
55+
* worker should [start controlling](https://developers.google.com/web/fundamentals/primers/service-workers/lifecycle#clientsclaim)
56+
* any existing clients as soon as it activates.
57+
*
58+
* @param {string} [config.directoryIndex='index.html'] If a navigation request
59+
* for a URL ending in `/` fails to match a precached URL, this value will be
60+
* appended to the URL and that will be checked for a precache match. This
61+
* should be set to what your web server is using for its directory index.
62+
*
63+
* @param {RegExp} [config.dontCacheBustURLsMatching] Assets that match this will be
64+
* assumed to be uniquely versioned via their URL, and exempted from the normal
65+
* HTTP cache-busting that's done when populating the precache. While not
66+
* required, it's recommended that if your existing build process already
67+
* inserts a `[hash]` value into each filename, you provide a RegExp that will
68+
* detect that, as it will reduce the bandwidth consumed when precaching.
69+
*
70+
* @param {boolean} [config.globFollow=true] Determines whether or not symlinks
71+
* are followed when generating the precache manifest. For more information, see
72+
* the definition of `follow` in the `glob`
73+
* [documentation](https://github.com/isaacs/node-glob#options).
74+
*
75+
* @param {Array<string>} [config.globIgnores=['node_modules/**']]
76+
* A set of patterns matching files to always exclude when generating the
77+
* precache manifest. For more information, see the definition of `ignore` in the `glob`
78+
* [documentation](https://github.com/isaacs/node-glob#options).
79+
*
80+
* @param {Array<string>} [config.globPatterns=['**.{js,css,html}']]
81+
* Files matching any of these patterns will be included in the precache
82+
* manifest. For more information, see the
83+
* [`glob` primer](https://github.com/isaacs/node-glob#glob-primer).
84+
*
85+
* @param {boolean} [config.globStrict=true] If true, an error reading a directory when
86+
* generating a precache manifest will cause the build to fail. If false, the
87+
* problematic directory will be skipped. For more information, see the
88+
* definition of `strict` in the `glob`
89+
* [documentation](https://github.com/isaacs/node-glob#options).
90+
*
91+
* @param {Array<RegExp>} [config.ignoreURLParametersMatching=[/^utm_/]]
92+
* Any search parameter names that match against one of the RegExp in this array
93+
* will be removed before looking for a precache match. This is useful if your
94+
* users might request URLs that contain, for example, URL parameters used to
95+
* track the source of the traffic.
96+
*
97+
* @param {Array<string>} [config.importScripts] A list of JavaScript files that
98+
* should be passed to [`importScripts()`](https://developer.mozilla.org/en-US/docs/Web/API/WorkerGlobalScope/importScripts)
99+
* inside the generated service worker file. This is useful when you want to
100+
* let Workbox create your top-level service worker file, but want to include
101+
* some additional code, such as a push event listener.
102+
*
103+
* @param {boolean} [config.inlineWorkboxRuntime=false] Whether the runtime code
104+
* for the Workbox library should be included in the top-level service worker,
105+
* or split into a separate file that needs to be deployed alongside the service
106+
* worker. Keeping the runtime separate means that users will not have to
107+
* re-download the Workbox code each time your top-level service worker changes.
108+
*
109+
* @param {Array<ManifestTransform>} [config.manifestTransforms] One or more
110+
* functions which will be applied sequentially against the generated manifest.
111+
* If `modifyURLPrefix` or `dontCacheBustURLsMatching` are also specified, their
112+
* corresponding transformations will be applied first.
113+
*
114+
* @param {number} [config.maximumFileSizeToCacheInBytes=2097152] This value can be
115+
* used to determine the maximum size of files that will be precached. This
116+
* prevents you from inadvertently precaching very large files that might have
117+
* accidentally matched one of your patterns.
118+
*
119+
* @param {string} [config.mode='production'] If set to 'production', then an
120+
* optimized service worker bundle that excludes debugging info will be
121+
* produced. If not explicitly configured here, the `process.env.NODE_ENV` value
122+
* will be used, and failing that, it will fall back to `'production'`.
123+
*
124+
* @param {Object<string, string>} [config.modifyURLPrefix] A mapping of prefixes
125+
* that, if present in an entry in the precache manifest, will be replaced with
126+
* the corresponding value. This can be used to, for example, remove or add a
127+
* path prefix from a manifest entry if your web hosting setup doesn't match
128+
* your local filesystem setup. As an alternative with more flexibility, you can
129+
* use the `manifestTransforms` option and provide a function that modifies the
130+
* entries in the manifest using whatever logic you provide.
131+
*
132+
* @param {string} [config.navigateFallback] If specified, all
133+
* [navigation requests](https://developers.google.com/web/fundamentals/primers/service-workers/high-performance-loading#first_what_are_navigation_requests)
134+
* for URLs that aren't precached will be fulfilled with the HTML at the URL
135+
* provided. You must pass in the URL of an HTML document that is listed in your
136+
* precache manifest. This is meant to be used in a Single Page App scenario, in
137+
* which you want all navigations to use common [App Shell HTML](https://developers.google.com/web/fundamentals/architecture/app-shell).
138+
*
139+
* @param {Array<RegExp>} [config.navigateFallbackBlacklist] An optional array
140+
* of regular expressions that restricts which URLs the configured
141+
* `navigateFallback` behavior applies to. This is useful if only a subset of
142+
* your site's URLs should be treated as being part of a
143+
* [Single Page App](https://en.wikipedia.org/wiki/Single-page_application). If
144+
* both `navigateFallbackBlacklist` and `navigateFallbackWhitelist` are
145+
* configured, the blacklist takes precedent.
146+
*
147+
* @param {Array<RegExp>} [config.navigateFallbackWhitelist] An optional array
148+
* of regular expressions that restricts which URLs the configured
149+
* `navigateFallback` behavior applies to. This is useful if only a subset of
150+
* your site's URLs should be treated as being part of a
151+
* [Single Page App](https://en.wikipedia.org/wiki/Single-page_application). If
152+
* both `navigateFallbackBlacklist` and `navigateFallbackWhitelist` are
153+
* configured, the blacklist takes precedent.
154+
*
155+
* @param {boolean} [config.navigationPreload=false] Whether or not to enable
156+
* [navigation preload](https://developers.google.com/web/tools/workbox/modules/workbox-navigation-preload)
157+
* in the generated service worker. When set to true, you must also use
158+
* `runtimeCaching` to set up an appropriate response strategy that will match
159+
* navigation requests, and make use of the preloaded response.
160+
*
161+
* @param {boolean|Object} [config.offlineGoogleAnalytics=false] Controls
162+
* whether or not to include support for
163+
* [offline Google Analytics](https://developers.google.com/web/tools/workbox/guides/enable-offline-analytics).
164+
* When `true`, the call to `workbox-google-analytics`'s `initialize()` will be
165+
* added to your generated service worker. When set to an `Object`, that object
166+
* will be passed in to the `initialize()` call, allowing you to customize the
167+
* behavior.
168+
*
169+
* @param {Array<RuntimeCachingEntry>} [config.runtimeCaching]
170+
*
171+
* @param {boolean} [config.skipWaiting=false] Whether to add an
172+
* unconditional call to [`skipWaiting()`]{@link module:workbox-core.skipWaiting}
173+
* to the generated service worker. If `false`, then a `message` listener will
174+
* be added instead, allowing you to conditionally call `skipWaiting()`.
175+
*
176+
* @param {boolean} [config.sourcemap=true] Whether to create a sourcemap
177+
* for the generated service worker files.
178+
*
179+
* @param {Object} [config.templatedURLs] If a URL is rendered based on some
180+
* server-side logic, its contents may depend on multiple files or on some other
181+
* unique string value. The keys in this object are server-rendered URLs. If the
182+
* values are an array of strings, they will be interpreted as `glob` patterns,
183+
* and the contents of any files matching the patterns will be used to uniquely
184+
* version the URL. If used with a single string, it will be interpreted as
185+
* unique versioning information that you've generated for a given URL.
186+
*
30187
* @return {Promise<{count: number, filePaths: Array<string>, size: number, warnings: Array<string>}>}
31188
* A promise that resolves once the service worker and related files
32189
* (indicated by `filePaths`) has been written to `swDest`. The `size` property

‎packages/workbox-build/src/get-manifest.js‎

Lines changed: 74 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -10,19 +10,85 @@ const getFileManifestEntries = require('./lib/get-file-manifest-entries');
1010
const getManifestSchema = require('./options/schema/get-manifest');
1111
const validate = require('./lib/validate-options');
1212

13+
// eslint-disable-next-line jsdoc/newline-after-description
1314
/**
1415
* This method returns a list of URLs to precache, referred to as a "precache
1516
* manifest", along with details about the number of entries and their size,
1617
* based on the options you provide.
1718
*
18-
* @param {Object} config Please refer to the
19-
* [configuration guide](https://developers.google.com/web/tools/workbox/modules/workbox-build#getmanifest_mode).
20-
* @return {Promise<{manifestEntries: Array<ManifestEntry>,
21-
* count: number, size: number, warnings: Array<string>}>} A promise that
22-
* resolves once the precache manifest is determined. The `size` property
23-
* contains the aggregate size of all the precached entries, in bytes, the
24-
* `count` property contains the total number of precached entries, and the
25-
* `manifestEntries` property contains all the `ManifestEntry` items. Any
19+
* @param {Object} config The configuration to use.
20+
*
21+
* @param {string} config.globDirectory The local directory you wish to match
22+
* `globPatterns` against. The path is relative to the current directory.
23+
*
24+
* @param {Array<ManifestEntry>} [config.additionalManifestEntries] A list of
25+
* entries to be precached, in addition to any entries that are generated as
26+
* part of the build configuration.
27+
*
28+
* @param {RegExp} [config.dontCacheBustURLsMatching] Assets that match this will be
29+
* assumed to be uniquely versioned via their URL, and exempted from the normal
30+
* HTTP cache-busting that's done when populating the precache. While not
31+
* required, it's recommended that if your existing build process already
32+
* inserts a `[hash]` value into each filename, you provide a RegExp that will
33+
* detect that, as it will reduce the bandwidth consumed when precaching.
34+
*
35+
* @param {boolean} [config.globFollow=true] Determines whether or not symlinks
36+
* are followed when generating the precache manifest. For more information, see
37+
* the definition of `follow` in the `glob`
38+
* [documentation](https://github.com/isaacs/node-glob#options).
39+
*
40+
* @param {Array<string>} [config.globIgnores=['node_modules/**']]
41+
* A set of patterns matching files to always exclude when generating the
42+
* precache manifest. For more information, see the definition of `ignore` in the `glob`
43+
* [documentation](https://github.com/isaacs/node-glob#options).
44+
*
45+
* @param {Array<string>} [config.globPatterns=['**.{js,css,html}']]
46+
* Files matching any of these patterns will be included in the precache
47+
* manifest. For more information, see the
48+
* [`glob` primer](https://github.com/isaacs/node-glob#glob-primer).
49+
*
50+
* @param {boolean} [config.globStrict=true] If true, an error reading a directory when
51+
* generating a precache manifest will cause the build to fail. If false, the
52+
* problematic directory will be skipped. For more information, see the
53+
* definition of `strict` in the `glob`
54+
* [documentation](https://github.com/isaacs/node-glob#options).
55+
*
56+
* @param {Array<ManifestTransform>} [config.manifestTransforms] One or more
57+
* functions which will be applied sequentially against the generated manifest.
58+
* If `modifyURLPrefix` or `dontCacheBustURLsMatching` are also specified, their
59+
* corresponding transformations will be applied first.
60+
*
61+
* @param {number} [config.maximumFileSizeToCacheInBytes=2097152] This value can be
62+
* used to determine the maximum size of files that will be precached. This
63+
* prevents you from inadvertently precaching very large files that might have
64+
* accidentally matched one of your patterns.
65+
*
66+
* @param {string} [config.mode='production'] If set to 'production', then an
67+
* optimized service worker bundle that excludes debugging info will be
68+
* produced. If not explicitly configured here, the `process.env.NODE_ENV` value
69+
* will be used, and failing that, it will fall back to `'production'`.
70+
*
71+
* @param {Object<string, string>} [config.modifyURLPrefix] A mapping of prefixes
72+
* that, if present in an entry in the precache manifest, will be replaced with
73+
* the corresponding value. This can be used to, for example, remove or add a
74+
* path prefix from a manifest entry if your web hosting setup doesn't match
75+
* your local filesystem setup. As an alternative with more flexibility, you can
76+
* use the `manifestTransforms` option and provide a function that modifies the
77+
* entries in the manifest using whatever logic you provide.
78+
*
79+
* @param {Object} [config.templatedURLs] If a URL is rendered based on some
80+
* server-side logic, its contents may depend on multiple files or on some other
81+
* unique string value. The keys in this object are server-rendered URLs. If the
82+
* values are an array of strings, they will be interpreted as `glob` patterns,
83+
* and the contents of any files matching the patterns will be used to uniquely
84+
* version the URL. If used with a single string, it will be interpreted as
85+
* unique versioning information that you've generated for a given URL.
86+
*
87+
* @return {Promise<{count: number, filePaths: Array<string>, size: number, warnings: Array<string>}>}
88+
* A promise that resolves once the service worker and related files
89+
* (indicated by `filePaths`) has been written to `swDest`. The `size` property
90+
* contains the aggregate size of all the precached entries, in bytes, and the
91+
* `count` property contains the total number of precached entries. Any
2692
* non-fatal warning messages will be returned via `warnings`.
2793
*
2894
* @memberof module:workbox-build

0 commit comments

Comments
 (0)