gatsby-plugin-offline: About options of merge behaviour of workboxConfig.runtimeCaching. (Optios of runtimeCachingMergeStrategy)

[shinshin86]

Description

I'm using gatsby-plugin-offline and I was confused by the merge behavior at first.
I'm not going to write into what I was confused about, because it's the same thing that is talked about in this issue.

#28289

What do you think about incorporating the content of "Proposal A" proposed in this issue (issues/28289) to improve the usability of gatsby-plugin-offline?
I think it will improve the usability of the plugin because it will give users more options without changing the existing behavior.

This is what Proposal A is about.
(The content of issues/28289 is quoted here.)

---

Give the user an option where one can define how workboxConfig.runtimeCaching should be merged (e.g. "merge" (current behaviour), "replace", or "append" (maybe even "prepend")) + exporting the default handlers object from the module, so that user can require it and doesn't have to copy the code into his own config.

Usages would the look like:

Append a custom handler

    {
      resolve: `gatsby-plugin-offline`,
      options: {
        runtimeCachingMergeStrategy: "append", // new option
        workboxConfig: {
          runtimeCaching: [
            {
              urlPattern: /some\/path\/that\/needs\/to\/always\/get\/fetched\/from\/the\/network/,
              handler: `NetworkFirst`,
            },
          ],
        },
      },
    },

Result:

{
    runtimeCaching: [
       {
          // Use cacheFirst since these don't need to be revalidated (same RegExp
          // and same reason as above)
          urlPattern: /(\.js$|\.css$|static\/)/,
          handler: `CacheFirst`,
       },
      {
        // page-data.json files, static query results and app-data.json
        // are not content hashed
        urlPattern: /^https?:.*\/page-data\/.*\.json/,
        handler: `StaleWhileRevalidate`,
      },
      {
        // Add runtime caching of various other page resources
        urlPattern: /^https?:.*\.(png|jpg|jpeg|webp|svg|gif|tiff|js|woff|woff2|json|css)$/,
        handler: `StaleWhileRevalidate`,
      },
      {
        // Google Fonts CSS (doesn't end in .css so we need to specify it)
        urlPattern: /^https?:\/\/fonts\.googleapis\.com\/css/,
        handler: `StaleWhileRevalidate`,
      },
     {
         urlPattern: /some\/path\/that\/needs\/to\/always\/get\/fetched\/from\/the\/network/,
         handler: `NetworkFirst`,
      },
    ],
}

Defining your own handlers

    {
      resolve: `gatsby-plugin-offline`,
      options: {
        runtimeCachingMergeStrategy: "replace", // new option
        workboxConfig: {
          runtimeCaching: [
            {
              urlPattern: /only-this-path-should-be-cached/,
              handler: `CacheFirst`,
            },
          ],
        },
      },
    },

Result:

{
    runtimeCaching: [
       {
          urlPattern: /only-this-path-should-be-cached/,
          handler: `CacheFirst`,
       },
    ],
}

Modifing default handlers

const { defaultRuntimeCachingHandlers } = require('gatsby-plugin-offline/constants');
//...
    {
      resolve: `gatsby-plugin-offline`,
      options: {
        runtimeCachingMergeStrategy: "replace", // new option
        workboxConfig: {
          runtimeCaching: [
            ...defaultRuntimeCachingHandlers.map((handler) => {
               // some logic to detect the  handler we want to modify/replace
               if (!handler.urlPattern.test('https://www.example.org/some.png') {
                   return handler;
               }

               // for example, modifing the 3rd default handler to also cache .wasm files + add some options
               return {
                   ...handler,
                   urlPattern: /^https?:.*\.(png|jpg|jpeg|webp|svg|gif|tiff|js|woff|woff2|json|css|wasm)$/,
                   handler: `NetworkFirst`,
                   options: {
                      networkTimeoutSeconds: 1.5,
                   },
               }
           }),
          ],
        },
      },
    },

Result:

{
    runtimeCaching: [
       {
          // Use cacheFirst since these don't need to be revalidated (same RegExp
          // and same reason as above)
          urlPattern: /(\.js$|\.css$|static\/)/,
          handler: `CacheFirst`,
       },
      {
        // page-data.json files, static query results and app-data.json
        // are not content hashed
        urlPattern: /^https?:.*\/page-data\/.*\.json/,
        handler: `StaleWhileRevalidate`,
      },
      {
        // **** MODIFIED HANDLER ****
        // Add runtime caching of various other page resources
        urlPattern: /^https?:.*\.(png|jpg|jpeg|webp|svg|gif|tiff|js|woff|woff2|json|css|wasm)$/,
        handler: `NetworkFirst`,
        options: {
             networkTimeoutSeconds: 1.5,
        },
      },
      {
        // Google Fonts CSS (doesn't end in .css so we need to specify it)
        urlPattern: /^https?:\/\/fonts\.googleapis\.com\/css/,
        handler: `StaleWhileRevalidate`,
      },
    ],
}

I think for this approach, a default value for runtimeCachingMergeStrategy of "append" would be the most intuitive for users. However, a default value of "merge" would preserve the current behaviour

---

I am trying to create a pull request to add this option.
If you have any comments, please let me know.

@kije I am trying to add an option based on your Proposal A.
Please let me know if you have any comments.

[shinshin86]

I modified the description a bit.

I'm thinking of creating a file called constants.js and adding defaultRuntimeCachingHandlers to it so that the default runtimeCaching settings can be referenced externally.

If this approach is not desirable, I would appreciate it if you could let me know.

[kije]

@shinshin86 FYI this might be obsolete if #31542 gets accepted. With the new version of gatsby-plugin-offline, route handlers will need to be registered via code instead of a runtimeCaching option.

This also allows for somewhat more flexibility, as a user of the plugin can decide to include the default handlers