# 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 Rush](https://cloud.getrush.ai/run/fix-webpack-5-node-polyfill-errors/webpack/). Opens 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`

```json
{
  "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.

## 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

- [Migrate from node-sass to Dart Sass in a Webpack Project](https://getrush.ai/run/migrate-node-sass-to-dart-sass/webpack/)
- [Migrate a Webpack 5 Project to Vite](https://getrush.ai/run/migrate-webpack-to-vite/webpack/)

## More jobs like this: Fix a bug from an alert

- [Fix "Error: Cannot find module 'webpack-cli/bin/config-yargs'" When Starting webpack-dev-server](https://getrush.ai/run/fix-webpack-cli-config-yargs-not-found/webpack-dev-server/)
- [Fix "cannot load such file -- webrick (LoadError)" on Ruby 3](https://getrush.ai/run/fix-webrick-load-error/webrick/)
- [Fix "ImportError: cannot import name 'safe_str_cmp' from 'werkzeug.security'"](https://getrush.ai/run/fix-werkzeug-safe-str-cmp-import-error/werkzeug/)
- [Fix "ImportError: cannot import name 'url_quote' from 'werkzeug.urls'"](https://getrush.ai/run/fix-werkzeug-url-quote-import-error/werkzeug/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
