All jobs

Fix "BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default"

An agent decides, per Node core module, whether your browser bundle needs a polyfill or an empty stub, sets resolve.fallback, and loads the bundle in a browser.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

webpack 4 quietly bundled browser versions of Node core modules such as path, buffer, crypto and stream, and injected a process object. webpack 5 does neither. A build that imports one of those modules now fails with Module not found: Error: Can't resolve 'path' followed by the BREAKING CHANGE paragraph, which offers two fixes: install a polyfill and name it in resolve.fallback, or set the module to false for an empty stub. The message cannot tell you which is right. That depends on whether the code path that uses the module ever runs in a browser, and the agent answers it by reading the code and then by loading the bundle.

aichaos/rivescript-js is a chatbot library that ships a Node build and a browser bundle from the same sources. Its webpack.config.js targets web and has node: { fs: "empty" }, the webpack 4 way to stub the filesystem. package.json has webpack at ^4.29.5 and webpack-cli at ^3.3.12. Under webpack 5 the config is rejected first, because node.fs is no longer a valid option. With that block gone, fs fails to resolve, from require("fs") in src/rivescript.js and from the fs-readdir-recursive dependency. So does path, which the same dependency imports, and that is the one that prints the BREAKING CHANGE text.

The agent traces where those modules are used. In src/rivescript.js the runtime() method returns "web" when process.browser is set and only otherwise calls require("fs"); file loading through self._node.fs and readDir happens on the Node branch. So the browser never calls into fs or path, and the right setting is resolve.fallback: { fs: false, path: false } with no polyfill added to the bundle. It removes the node block.

That same method holds the failure the build does not report. process.browser was true in webpack 4 bundles because webpack injected its process shim. webpack 5 injects nothing, so a bundle that builds cleanly throws ReferenceError: process is not defined in the page the first time runtime() runs. The agent defines process.browser as true with webpack.DefinePlugin, which lets the minifier drop the Node branch entirely. It also handles the loader: babel-loader is at ^7.1.5 with Babel 6 packages, and that loader's peer range stops at webpack 4. If npm refuses the install, the agent moves to babel-loader 8 with @babel/core and @babel/preset-env and updates .babelrc, in a separate commit. The README's note about digital envelope routines::unsupported and NODE_OPTIONS=--openssl-legacy-provider can then go, since current webpack 5 builds on current Node without that flag.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Upgrading this project to webpack 5 fails with \"Module not found: Error: Can't resolve ...\" and \"BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default\". Upgrade webpack and webpack-cli to the newest 5.x-compatible releases and run the build. For every Node core module the build cannot resolve, find each import of it in the source and in dependencies (name the dependency and the import chain), and decide whether that code runs in the browser. If it never does, set resolve.fallback for that module to false. If it does, install the standard browser polyfill and point resolve.fallback at it with require.resolve. Record each decision in a table with the evidence. Remove webpack 4 options the new schema rejects, such as node: { fs: \"empty\" }. Then search the source and the built bundle for uses of the globals webpack 4 injected: process, process.env, process.browser, Buffer, global, setImmediate. For each, either define it at build time with DefinePlugin, provide it with ProvidePlugin, or change the code, and say which and why. If a loader's peer dependencies do not allow webpack 5, upgrade that loader and what it requires in a separate commit and list the configuration files you changed for it. Run the existing tests. Then prove the bundle works: serve the output file, load it in a headless browser page, call the library's main entry point, and report any console error. Compare the bundle size before and after. If the README documents the OpenSSL legacy provider workaround, check whether the build still needs it on the newest Node LTS and update the note. Open a pull request with the table, the commands and their output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

A pull request led by a table with one row per unresolved module: where it is imported from, whether a browser code path reaches it, and the resulting resolve.fallback entry. For the library above both rows say false, and no polyfill package is added. A second table lists the injected globals found, here process.browser in one method, and the plugin line that now supplies each.

The description includes the build output, the test output and the result of loading dist/rivescript.js in a headless page: the script the agent ran there and the console log. A reviewer checks that every false in the first table is backed by an actual trace of the code, because a stubbed module that the browser does call fails at run time with an error about an empty object and no hint of the cause. They also look at the size comparison. A bundle that grew after this change usually means a polyfill was pulled in where a stub would have done. If the Babel upgrade commit is present, they review it as its own change, including the edited .babelrc.

Run it on every failed build on an upgrade branch

The upgrade usually starts as a branch that bumps webpack and then fails CI with this message. In the console, add an automation to the Project with the prompt above and a github trigger on workflow_run.failure. Rush starts a run and places the event after the saved prompt, so the agent knows which branch and commit failed. Add a sentence to the prompt telling the agent to stop with one line unless the failing log contains the BREAKING CHANGE text. Events sent by bots never fire a trigger, so when the bump comes from a dependency bot, a member starts the automation with Run now or pushes a commit to that branch.

Keep the automation's max runs per hour low. A repository with several workflows produces several failed check suites for one commit, and the events past the cap wait in line and may no longer be needed by the time they start.

The use case this job follows, with its automation and trigger: Fix a bug from an alert.

Why run it on Rush?

A bundle can pass every Node test in the repository and still be broken, because npm run test here runs the Babel output under nodeunit, where process and fs exist. The only honest check is a browser. The agent's sandbox has one, so it can serve the built file, open a page, construct the library object and read the console. That session is recorded step by step in the transcript. A reviewer sees the page load without a ReferenceError instead of taking the build's exit code as proof.

Bundler upgrades also depend on the Node version doing the build. The agent can install the oldest Node the project claims to support and the newest LTS, build on both, and report where they differ. The .travis.yml in this repository lists node, 8, 7 and 6, and the three numbered versions are too old to run webpack 5. Finding that on a clean machine is quicker than finding it after a merge.

Frequently asked questions

Should I install node-polyfill-webpack-plugin and be done?

It makes the error go away by restoring every polyfill webpack 4 had. It also adds code for modules your browser build may never call. The agent decides per module, so the bundle only carries a polyfill where a browser code path uses it. If you prefer the plugin, say so in the prompt and it will still report which polyfills are actually reached.

What is the difference between a fallback of false and a polyfill?

false resolves the import to an empty module, so require("fs") returns an object with no methods. A polyfill resolves it to a package that implements the API in browser terms, such as path-browserify. Use false when the code that would call the module is unreachable in the browser, and a polyfill when it is reached.

Why does my bundle build and then say process is not defined?

webpack 5 stopped injecting the process shim along with the module polyfills, and that is a run-time failure the build cannot see. DefinePlugin can replace specific expressions such as process.env.NODE_ENV or process.browser at build time, and ProvidePlugin with the process/browser package restores the whole object when a dependency needs it.

The unresolved module is imported by a dependency, not by my code. Does that change anything?

The decision is the same and the evidence is harder to get. The agent prints the import chain from your entry point to the dependency's require, then checks whether a newer version of that dependency has a browser field or dropped the import. It prefers upgrading the dependency over stubbing around it and tells you which it did.

More webpack jobs

More jobs like this: Fix a bug from an alert

Keep reading