feat(gatsby-plugin-offline): Allow appending custom scripts to sw.js

packages/gatsby-plugin-offline/README.md

@@ -19,13 +19,80 @@ in the service worker.
 plugins: [`gatsby-plugin-offline`]
 ```
 
-## Overriding options
+## Available options
 
-When adding this plugin to your `gatsby-config.js`, you can pass in options to
-override the default [Workbox](https://developers.google.com/web/tools/workbox/modules/workbox-build) config.
+As of `gatsby-plugin-offline` 3.0.0, the following options are available:
 
-The default config is as follows. Warning: you can break the offline support by
-changing these options, so tread carefully.
+- `workboxConfig` allows you to override the default Workbox options - see [Overriding Workbox configuration](#overriding-workbox-configuration)
+- `injectScript` lets you specify a file to be injected into the end of the generated service worker (`sw.js`)
+
+For example:
+
+```javascript:title=gatsby-config.js
+plugins: [
+  {
+    resolve: `gatsby-plugin-offline`,
+    options: {
+      workboxConfig: {
+        importWorkboxFrom: `cdn`,
+      },
+      injectScript: `src/custom-sw-code.js`,
+    },
+  },
+]
+```
+
+```javascript:title=src/custom-sw-code.js
+// show a notification after 15 seconds (the notification
+// permission must be granted first)
+setTimeout(() => {
+  self.registration.showNotification("Hello, world!")
+}, 15000)
+
+// register a custom navigation route
+const customRoute = new workbox.routing.NavigationRoute(({ event }) => {
+  // ...
+})
+workbox.routing.registerRoute(customRoute)
+```
+
+## Upgrading from 2.x
+
+To upgrade from 2.x to 3.x, move any existing options into the `workboxConfig` option. If you haven't specified any options, you have nothing to do.
+
+For example, here is a 2.x config:
+
+```javascript
+plugins: [
+  {
+    resolve: `gatsby-plugin-offline`,
+    options: {
+      importWorkboxFrom: `cdn`,
+    },
+  },
+]
+```
+
+Here is the equivalent 3.x config:
+
+```javascript
+plugins: [
+  {
+    resolve: `gatsby-plugin-offline`,
+    options: {
+      workboxConfig: {
+        importWorkboxFrom: `cdn`,
+      },
+    },
+  },
+]
+```
+
+## Overriding Workbox configuration
+
+When adding this plugin to your `gatsby-config.js`, you can use the option `workboxConfig` to override the default Workbox config. To see the full list of options, see [this article on Google Developers](https://developers.google.com/web/tools/workbox/modules/workbox-build#full_generatesw_config).
+
+The default `workboxConfig` is as follows. Note that some of these options are configured automatically, e.g. `globPatterns`. If you're not sure about what all of these options mean, it's best to leave them as-is - otherwise, you may end up causing errors on your site, causing old files to be remain cached, or even breaking offline support.
 
 ```javascript
 const options = {

packages/gatsby-plugin-offline/src/gatsby-node.js

@@ -105,11 +105,10 @@ exports.onPostBuild = (args, pluginOptions) => {
     clientsClaim: true,
   }
 
-  // pluginOptions.plugins is assigned automatically when the user hasn't
-  // specified custom options - Workbox throws an error with unsupported
-  // parameters, so delete it.
-  delete pluginOptions.plugins
-  const combinedOptions = _.defaults(pluginOptions, options)
+  const combinedOptions = {
+    ...options,
+    ...pluginOptions.workboxConfig,
+  }
 
   const idbKeyvalFile = `idb-keyval-iife.min.js`
   const idbKeyvalSource = require.resolve(`idb-keyval/dist/${idbKeyvalFile}`)
@@ -125,8 +124,13 @@ exports.onPostBuild = (args, pluginOptions) => {
       const swAppend = fs
         .readFileSync(`${__dirname}/sw-append.js`, `utf8`)
         .replace(/%pathPrefix%/g, pathPrefix)
-
       fs.appendFileSync(`public/sw.js`, `\n` + swAppend)
+
+      if (pluginOptions.injectScript) {
+        const userAppend = fs.readFileSync(pluginOptions.injectScript, `utf8`)
+        fs.appendFileSync(`public/sw.js`, `\n` + userAppend)
+      }
+
       console.log(
         `Generated ${swDest}, which will precache ${count} files, totaling ${size} bytes.`
       )