Cleanup of Workbox build examples (#2222)

* Cleanup of build examples * Update site/en/docs/workbox/modules/workbox-webpack-plugin/index.md Co-authored-by: Jeremy Wagner <malchata@users.noreply.github.com> * Update site/en/docs/workbox/modules/workbox-cli/index.md Co-authored-by: Jeremy Wagner <malchata@users.noreply.github.com> * Update site/en/docs/workbox/modules/workbox-cli/index.md Co-authored-by: Jeremy Wagner <malchata@users.noreply.github.com> * Update site/en/docs/workbox/modules/workbox-build/index.md Co-authored-by: Jeremy Wagner <malchata@users.noreply.github.com> * Update site/en/docs/workbox/modules/workbox-build/index.md Co-authored-by: Jeremy Wagner <malchata@users.noreply.github.com> * Update site/en/docs/workbox/modules/workbox-webpack-plugin/index.md Co-authored-by: Jeremy Wagner <malchata@users.noreply.github.com> * Update site/en/docs/workbox/modules/workbox-build/index.md Co-authored-by: Jeremy Wagner <malchata@users.noreply.github.com> Co-authored-by: Jeremy Wagner <malchata@users.noreply.github.com>
GoogleChrome · Mar 3, 2022 · b71d5b6 · b71d5b6
1 parent cbdfba2
commit b71d5b6
Show file tree

Hide file tree

Showing 3 changed files with 135 additions and 109 deletions.
diff --git a/site/en/docs/workbox/modules/workbox-build/index.md b/site/en/docs/workbox/modules/workbox-build/index.md
@@ -2,9 +2,9 @@
 layout: 'layouts/doc-post.njk'
 title: workbox-build
 date: 2018-01-31
-updated: 2020-01-17
+updated: 2022-03-13
 description: >
-  A module that can generate a service worker, inject a precache manifest, or create a local copy the Workbox libraries.
+  A module that can generate a service worker, inject a precache manifest into existing code, or create a precache manifest.
 ---
 
 The `workbox-build` module integrates into a node-based build process and can generate an entire service worker, or just generate a list of assets to precache that could be used within an existing service worker.
@@ -15,17 +15,17 @@ The two modes that most developers will use are `generateSW` and `injectManifest
 
 ### `generateSW`
 
-The `generateSW` mode creates a service worker file for you, and writes it out to disk.
+The `generateSW` mode creates a service worker file for you, customized via configuration options, and writes it out to disk.
 
 #### When to use `generateSW`
 
 - You want to precache files.
-- You have simple runtime configuration needs (e.g. the configuration allows you to define routes and strategies).
+- You have simple runtime caching needs.
 
 #### When NOT to use `generateSW`
 
-- You want to use other Service Worker features (i.e. Web Push).
-- You want to import additional scripts or add additional logic.
+- You want to use other Service Worker features (i.e. [Web Push](https://developer.mozilla.org/docs/Web/API/Push_API)).
+- You want to import additional scripts, or add additional logic for custom caching strategies.
 
 ### `injectManifest`
 
@@ -35,64 +35,98 @@ The `injectManifest` mode will generate a list of URLs to precache, and add that
 
 - You want more control over your service worker.
 - You want to precache files.
-- You have more complex needs in terms of routing.
-- You would like to use your service worker with other API's (e.g. Web Push).
+- You need to customize routing and strategies.
+- You would like to use your service worker with other platform features (e.g. [Web Push](https://developer.mozilla.org/docs/Web/API/Push_API)).
 
 #### When NOT to use `injectManifest`
 
 - You want the easiest path to adding a service worker to your site.
 
 ## `generateSW` Mode
 
-You can use the `generateSW` mode within a node-based build script like so:
+You can use the `generateSW` mode within a node-based build script, using the most common [configuration options](/docs/workbox/reference/workbox-build/#type-GenerateSWOptions), like so:
 
 ```js
 // Inside of build.js:
 const {generateSW} = require('workbox-build');
 
-const swDest = 'build/sw.js';
+// These are some common options, and not all are required.
+// Consult the docs for more info.
 generateSW({
-  swDest,
-  // Other configuration options...
-}).then(({count, size}) => {
-  console.log(
-    `Generated ${swDest}, which will precache ${count} files, totaling ${size} bytes.`
-  );
+  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: '...',
+}).then(({count, size, warnings}) => {
+  if (warnings.length > 0) {
+    console.warn(
+      'Warnings encountered while generating a service worker:'
+      warnings.join('\n')
+    );
+  }
+
+  console.log(`Generated a service worker, which will precache ${count} files, totaling ${size} bytes.`);
 });
 ```
 
-This will generate a service worker with precaching setup for all of the files picked up by your configuration.
+This will generate a service worker with precaching setup for all of the files picked up by your configuration, and the runtime caching rules provided.
 
-### Full `generateSW` Config
-
-A full set of configuration options can be found on [this reference page](/docs/workbox/reference/workbox-build/#method-generateSW).
+A full set of configuration options can be found [in the reference documentation](/docs/workbox/reference/workbox-build/#type-GenerateSWOptions).
 
 ## `injectManifest` Mode
 
-You can use the `injectManifest` mode within a node-based build script like so:
+You can use the `injectManifest` mode within a node-based build script, using the most common [configuration options](/docs/workbox/reference/workbox-build/#type-InjectManifestOptions), like so:
 
 ```js
 // Inside of build.js:
 const {injectManifest} = require('workbox-build');
 
-const swSrc = 'src/sw.js';
-const swDest = 'build/sw.js';
+// These are some common options, and not all are required.
+// Consult the docs for more info.
 injectManifest({
-  swSrc,
-  swDest,
-  // Other configuration options...
-}).then(({count, size}) => {
-  console.log(
-    `Generated ${swDest}, which will precache ${count} files, totaling ${size} bytes.`
-  );
+  dontCacheBustURLsMatching: [new RegExp('...')],
+  globDirectory: '...',
+  globPatterns: ['...', '...'],
+  maximumFileSizeToCacheInBytes: ...,
+  swDest: '...',
+  swSrc: '...',
+}).then(({count, size, warnings}) => {
+  if (warnings.length > 0) {
+    console.warn(
+      'Warnings encountered while injecting the manifest:'
+      warnings.join('\n')
+    );
+  }
+
+  console.log(`Injected a manifest which will precache ${count} files, totaling ${size} bytes.`);
 });
 ```
 
 This will create a precache manifest based on the files picked up by your configuration and inject it into your existing service worker file.
 
-### Full `injectManifest` Config
-
-A full set of configuration options can be found on [this reference page](/docs/workbox/reference/workbox-build/#method-injectManifest).
+A full set of configuration options can be found [in the reference documentation](/docs/workbox/reference/workbox-build/#type-InjectManifestOptions).
 
 ## Additional modes
 
@@ -102,18 +136,29 @@ We expect that `generateSW` or `injectManifest` will suit most developers' needs
 
 This is conceptually similar to the `injectManifest` mode, but instead of adding the manifest into the source service worker file, it returns the array of manifest entries, along with information about the number of entries and total size.
 
-You can use the `getManifest` mode within a node-based build script like so:
+You can use the `injectManifest` mode within a node-based build script, using the most common [configuration options](/docs/workbox/reference/workbox-build/#type-GetManifestOptions), like so:
 
 ```js
 // Inside of build.js:
 const {getManifest} = require('workbox-build');
 
+// These are some common options, and not all are required.
+// Consult the docs for more info.
 getManifest({
-  // Configuration options...
-}).then(({manifestEntries, count, size}) => {
+  dontCacheBustURLsMatching: [new RegExp('...')],
+  globDirectory: '...',
+  globPatterns: ['...', '...'],
+  maximumFileSizeToCacheInBytes: ...,
+}).then(({manifestEntries, count, size, warnings}) => {
+  if (warnings.length > 0) {
+    console.warn(
+      'Warnings encountered while getting the manifest:'
+      warnings.join('\n')
+    );
+  }
+
   // Do something with the manifestEntries, and potentially log count and size.
 });
 ```
 
-A full set of configuration options can be found on
-[this reference page](/docs/workbox/reference/workbox-build/#method-getManifest).
+A full set of configuration options can be found [in the reference documentation](/docs/workbox/reference/workbox-build/#type-GetManifestOptions).
diff --git a/site/en/docs/workbox/modules/workbox-cli/index.md b/site/en/docs/workbox/modules/workbox-cli/index.md
@@ -2,7 +2,7 @@
 layout: 'layouts/doc-post.njk'
 title: workbox-cli
 date: 2017-11-27
-updated: 2020-01-17
+updated: 2022-03-03
 description: >
   Generate a service worker, inject a precache manifest, or create a local copy the Workbox libraries from the command line.
 ---
@@ -68,12 +68,12 @@ are recommended to use `generateSW` mode.
 #### When to use `generateSW`
 
 - You want to precache files.
-- You have simple runtime configuration needs (e.g. the configuration allows you to define routes and strategies).
+- You have simple runtime caching needs.
 
 #### When NOT to use `generateSW`
 
-- You want to use other Service Worker features (i.e. Web Push).
-- You want to import additional scripts or add additional logic.
+- You want to use other Service Worker features (i.e. [Web Push](https://developer.mozilla.org/docs/Web/API/Push_API)).
+- You want to import additional scripts, or add additional logic for custom caching strategies.
 
 ### `injectManifest`
 
@@ -96,14 +96,14 @@ npx workbox injectManifest path/to/config.js
 
 #### When to use `injectManifest`
 
-You want more control over your service worker.
-You want to precache files.
-You have more complex needs in terms of routing.
-You would like to use your service worker with other API's (e.g. Web Push).
+- You want more control over your service worker.
+- You want to precache files.
+- You need to customize routing and strategies.
+- You would like to use your service worker with other platform features (e.g. [Web Push](https://developer.mozilla.org/docs/Web/API/Push_API)).
 
 #### When NOT to use `injectManifest`
 
-You want the easiest path to adding a service worker to your site.
+- You want the easiest path to adding a service worker to your site.
 
 ### `copyLibraries`
 
@@ -174,10 +174,8 @@ automatically by `workbox wizard` or tweaked manually.
 
 ### Options used by `generateSW`
 
-A full set of configuration options can be found on
-[this reference page](/docs/workbox/reference/workbox-build/#method-generateSW).
+A full set of configuration options can be found [in the reference documentation](/docs/workbox/reference/workbox-build/#type-GenerateSWOptions).
 
 ### Options used by `injectManifest`
 
-A full set of configuration options can be found on
-[this reference page](/docs/workbox/reference/workbox-build/#method-injectManifest).
+A full set of configuration options can be found [in the reference documentation](/docs/workbox/reference/workbox-build/#type-InjectManifestOptions).