Webpack 5 Headache

By Sindre Sorhus

Sindre Sorhus

Most packages on npm are mainly made with Node.js in mind. However, thanks to automatic polyfilling, most of them have for years worked fine in the browser too. The problem is that Webpack created convenience by automatically polyfilling and then now suddenly took it away. If they never had polyfilled, this would not be an issue, but developers now expect packages on npm to just work in the browser after being bundled.

While I realize Webpack is an important tool in the JavaScript community, I have mixed feelings about it personally, because it has caused me great amounts of grief as a package maintainer. Users think every Webpack tool/config problem is a problem with a specific package and opens an issue asking for support on the package instead of Webpack. In the past year alone, I’ve had to deal with hundreds of Webpack issues on my repos.

With the removal of automatic polyfilling, this is just going to get worse, so I’m going to clearly outline my stance on this:

  • My packages are mainly made for Node.js. Many of them work in the browsers automatically (meaning they don’t use any Node.js APIs). Some require Node.js APIs, and with Webpack 5, it’s up to you to polyfill them.
  • I am not going to add polyfills to my packages. Polyfills add bloat and bugs and I don’t want Node.js users to be inconvenienced by this.
  • I am not going to do Webpack support. I’ve been pretty lenient in the past and answered most Webpack support questions, but it takes a lot of my time that I could have spent on more important things. I will instead refer users to the Webpack support channels.

The main reason I love Node.js is that I don’t have to deal with the awfulness that is JS front-end tooling.

Honestly, Webpack not polyfilling does make sense in theory. I just think they did it too early and with too little consideration about its effects on the ecosystem. I imagine this change would have been much easier to do in some years when a lot more Node.js package are ESM-only and Node.js supports more browser APIs.

This sucks!

I agree. Go complain on the Webpack issue tracker. They caused this.

How can I manually polyfill things now?

This is what the Webpack blog post says:

MIGRATION: resolve.alias and ProvidePlugin. Errors will give hints. (Refer to node-libs-browser for polyfills & mocks used in v4)

What can I do to help improve the situation long-term?

You can help make Node.js and browsers more unified. For example, Node.js has util.promisify, which is commonly used. I don’t understand why such an essential method is not also available in browsers. In turn, browsers have APIs that Node.js should have. For example, fetch, Web Streams (The Node.js stream module is awful), Web Crypto (I’ve heard rumors this one is coming), Websockets, etc.