workbox-webpack-plugin v5 interface

[jeffposnick]

Background

The team is planning on addressing the various issues and pain points raised against the workbox-webpack-plugin with a number of breaking changes to the interface and behavior in an upcoming v4.0.0 release.

We're looking to gather feedback from the community prior to starting on the implementation, so please feel free to reply if you've got any concerns.

Open issues

These are categorized, but not prioritized, based on the open issues. It gives a good overview of the general areas in which feedback has been concentrated.

We won't be able to address all of these issues in the initial v4.0.0 release. Our goal is to address many of them that require an incompatible API surface or a significant change in behavior in at once, to minimize the number of major releases with breaking changes.

Filesystem paths

• workbox-webpack-plugin - InjectManifest links to manifest relative to webpack root, not the swDest (workbox-webpack-plugin - InjectManifest links to manifest relative to webpack root, not the swDest #1543)
• Warn when swDest is set to the webpack output directory (Warn when swDest is set to the webpack output directory #1363)

URL paths

• InjectManifest Plugin: Generate manifest url based on config instead of webpack public path (InjectManifest Plugin: Generate manifest url based on config instead of webpack public path #1565)
• manifest file generated by workbox-webpack-plugin has wrong public path when using file-loader (manifest file generated by workbox-webpack-plugin has wrong public path when using file-loader #1564)

Asset pipeline

• workbox-webpack-plugin - chunks option in conflict with precaching index.html (workbox-webpack-plugin - chunks option in conflict with precaching index.html #1556)
• Precache manifest inaccurate for ExtractTextPlugin output (Precache manifest inaccurate for ExtractTextPlugin output #1529)
• CSS with contenthash should not be revisioned (CSS with contenthash should not be revisioned #1454)
• importWorkboxFrom: 'local' bypasses the webpack asset pipeline (importWorkboxFrom: 'local' bypasses the webpack asset pipeline #1338)
• Fail the Webpack build if a chunk doesn't exist (Fail the Webpack build if a chunk doesn't exist #1287)
• Precaching the generated WebpackPwaManifest manifest asset (Precaching the generated WebpackPwaManifest manifest asset #1588)
• Precache manifest missing entries when recompiled via webpack --watch (Precache manifest missing entries when recompiled via webpack --watch #1790)

Parity with "glob" configuration

• templatedUrls option fails if no globDirectory provided (templatedUrls option fails if no globDirectory provided #1418)
• [workbox-webpack-plugin] proposal to add support Webpack assets in templatedUrls option ([workbox-webpack-plugin] proposal to add support Webpack assets in templatedUrls option #1384)
• dontCacheBustUrlsMatching ignored in Workbox v3? (dontCacheBustUrlsMatching ignored in Workbox v3? #1373)
• [workbox-webpack-plugin] v3 Entries array passed to manifestTransforms is empty ([workbox-webpack-plugin] v3 Entries array passed to manifestTransforms is empty #1227)

Developer experience

• InjectManifest Plugin doesn't compile the serviceworker with webpack (InjectManifest Plugin doesn't compile the serviceworker with webpack #1513)
• [Feature] Add ability to specify [hash] in navigationFallback ([Feature] Add ability to specify [hash] in navigationFallback #1506)
• The workbox-webpack-plugin generate an error url in the precache-manifest.js file (The workbox-webpack-plugin generate an error url in the precache-manifest.js file #1493)
• GenerateManifest in workbox-webpack-plugin (GenerateManifest in workbox-webpack-plugin #1485)
• Webpack plugin causes massive prolonged spike in CPU and Memory (Webpack plugin causes massive prolonged spike in CPU and Memory #1475)
• New webpack plugin config option to specify hash length (New webpack plugin config option to specify hash length #1458)
• Use webpack's performance.hints for reporting non-fatal errors (Use webpack's performance.hints for reporting non-fatal errors #1380)
• Integration with the webpack DllPlugin (Integration with the webpack DllPlugin #1348)
• accept chunk names in importScripts (workbox-webpack-plugin: accept chunk names in importScripts #1752)

Proposed v5 plugin interface

This interface will apply to both InjectManifest and GenerateSW. (swSrc is the only option that's limited to InjectManifest.)

I'll keep this example up-to-date as folks add feedback to the issue thread.

new InjectManifest or GenerateSW ({
  // Same as in v3:
  swDest,
  importWorkboxFrom,
  importsDirectory,
  precacheManifestFilename,
  skipWaiting,
  clientsClaim,
  runtimeCaching,
  navigateFallback,
  navigateFallbackBlacklist,
  navigateFallbackWhitelist,
  importScripts,
  ignoreUrlParametersMatching,
  directoryIndex,
  cacheId,
  maximumFileSizeToCacheInBytes,
  // InjectManifest only:
  swSrc,

  // Newly changed in v4:
  webpackAssets: {
    // Moved to be under a webpackAssets parent:
    chunks,
    excludeChunks,
    include,
    exclude,

    // The next two are the same as the v3 options,
    // but now only apply to webpack assets.
    modifyUrlPrefix,
    manifestTransforms,

    // Maps a static URL to one or more webpack assets. E.g.
    // {
    //   '/shell': {
    //     chunks: ['chunk1'],
    //     include: [/*.js/],
    //   }
    // }
    templatedUrls,

    // Array defaulting to ['[hash]'].
    // You can add any RegExp, or options along the lines of
    // https://github.com/webpack/loader-utils#interpolatename
    dontCacheBustUrlsMatching,
  },

  fileSystemAssets: {
    // Same as in v3, but moved to be under a fileSystemAssets parent.
    globDirectory,
    globFollow,
    globIgnores,
    globPatterns,
    globStrict,

    // The next four behave the same as the v3 options,
    // but explicitly only apply to file system assets.
    modifyUrlPrefix,
    manifestTransforms,
    templatedUrls,
    dontCacheBustUrlsMatching,
  },

  // Removed as top-level options in v4:
  /*
    dontCacheBustUrlsMatching,
    templatedUrls,
    globDirectory,
    globFollow,
    globIgnores,
    globPatterns,
    globStrict,
    modifyUrlPrefix,
    manifestTransforms,
    chunks,
    excludeChunks,
    include,
    exclude,
  */
});

[piehei]

Hmm. Not sure what I should be looking for.

Is some functionality going to be removed? Or is this """just""" an API breaking change?

[jeffposnick]

There's some new functionality (making it so that options like manifestTransforms and templatedUrls can apply to webpack assets) as well as breaking changes (moving the top-level options like templatedUrls, etc. so that they're sub-options of either fileSystemAssets or webpackAssets).

It's a combination of the new interface (any naming concerns, etc.) along with the list of issues that are on our radar that we're looking for feedback on.

[developit]

webpackAssets is a welcome addition Jeff!

[joaovieira]

Yes! Just came to the issues to "complain" about the fact modifyUrlPrefix, manifestTransforms and dontCacheBustUrlsMatching only run on glob assets, so I'm very pleased to see this!

Here's my use case. Following is a simplified Next.js precache manifest (based on the webpack emitted files):

self.__precacheManifest = [
  {
    "revision": "29c0a6405b762b2ed86f",
    "url": "static/style-3518e9dc77a50a7a733511fc53c5f981.css"
  },
  {
    "url": "static/commons/main-29c0a6405b762b2ed86f.js"
  },
  {
    "revision": "8d205d627155bcada52d",
    "url": "bundles/pages/signin.js"
  },
  {
    "revision": "7df5921f82befca27ca2",
    "url": "bundles/pages/index.js"
  },
  {
    "revision": "cd541d001d7a4e98c326",
    "url": "bundles/pages/_error.js"
  },
  {
    "revision": "f254703bdcbdcd928292",
    "url": "bundles/pages/_app.js"
  },
  {
    "revision": "88201f6df194e5ca3129373100147939",
    "url": "build-manifest.json"
  }
];

Problem 1:

As you see, some of the assets are already hashed, so I'd like to not revision those. Some others are not hashed at build time, but are served/exported with a hash in the url. E.g. bundles/pages/index.js is served as _next/ad684ad8-91d3-4809-bd83-0039c7d22a3e/page/index.js. As such, I'd like to use:

dontCacheBustUrlsMatching: /$(bundles\/pages|static)/

Problem 2:

As hinted above, files are served on different paths than their location in the filesystem. E.g. the static folder is served as _next/static. As such, I'd like to use:

modifyUrlPrefix: {
  'bundles/pages': join(assetPrefix, `/_next/${buildId}/page`),
   chunks: join(assetPrefix, '/_next/webpack/chunks'),
   static: join(assetPrefix, '/_next/static'),
}

Problem 3 and 4:

build-manifest.json is emitted but it's not even served and does not need to be in the precache manifest. I'd like to filter it out.

I want to use the Next.js buildId as the revision number for every revisioned entry.

As such, I'd like to use:

manifestTransforms: [
  originalManifest => {
    const manifest = originalManifest
      .filter(entry => entry.url !== 'build-manifest.json')
      .map(({ url, revision }) => ({ url, revision: revision && buildId }));
    return { manifest };
  },
]

This seemed a very reasonable use case and was happy to see workbox supported all these options, until I found out the webpack plugin didn't :)

Hope this helps.

[zoellner]

Came here after looking at #1513
Can you explain a bit how this is going to resolve that issue? I.e. how can I have a src/sw/main.js file that let's say is using a whole bunch of imports and is currently being compiled with a separate process to .tmp/sw.js to be the swSrc without the separate compile process?

[jeffposnick]

After chatting with @developit a bit, we might end up going with an approach that eliminated the fileSystemAssets set of config options entirely, and relied on folks using https://github.com/webpack-contrib/copy-webpack-plugin (potentially with emit turned off) to pull in assets that wouldn't "normally" be part of their webpack asset pipeline.

We wanted to float that idea here and see if there were strong feelings one way or another.

[jeffposnick]

Interested parties who have been following this issue should take a look at @developit's proposal, detailed at #1854, which addresses a few of the issues outlined in this meta-issue.

[jeffposnick]

This should be addressed by the current Workbox v5.0.0 alpha.