What the agent does
The error names the line: require() of ES Module .../node_modules/chalk/source/index.js from .../cli.js not supported. It appears after a routine bump because chalk 5 and later ship only as ES modules, and a CommonJS file cannot require one on older Node releases. The agent reads the project before choosing a fix. In a command-line tool like KuroLabs/stegcloak, package.json has no type field, so every .js file is CommonJS; cli.js requires chalk, ora, inquirer and clipboardy; the ranges are ^4.0.0, ^4.0.4, ^7.1.0 and ^2.3.0; and engines says Node >=8.0.0. All four packages have since gone ESM-only in a later major, so an upgrade of any of them hits the same wall.
Then it reproduces the failure on more than one Node version, because the symptom depends on the version. With chalk raised to 5, node cli.js --help on Node 18 and on Node 20.10 stops at line 11 with ERR_REQUIRE_ESM. On Node 22 the same command prints the help text, since recent Node can require an ES module. The breakage has moved, not gone: require('chalk') now returns the module's namespace object, whose default property is the chalk function, so chalk.yellow is undefined, and stegcloak hide with the password supplied through the environment dies at its first coloured message with TypeError: chalk.yellow is not a function. A check that only starts the program passes on Node 22 and the tool is still broken.
The agent tests each candidate fix on each version and puts the results in a table. Appending .default to the require works on Node 20.19 and 22 and still throws ERR_REQUIRE_ESM on 18 and 20.10. A dynamic import('chalk') inside an async function works on all four, at the cost of making the start of cli.js asynchronous. Converting the package to ES modules with "type": "module" fixes it everywhere but also changes stegcloak.js, which is the library's main entry and is required by other people's CommonJS code. Staying on chalk 4.1.2, which still declares Node >=10, needs no code change. Replacing chalk with styleText from node:util removes the dependency, but that function is missing on Node 18 and 20.10.
The choice follows from engines. A project that promises Node 8 cannot take chalk 5 in any form, so for stegcloak as it stands the agent keeps the four packages on their last CommonJS majors, updates them within those majors, and says which engines value each alternative would require, so the next automated major bump can be declined with a reason. If the request says the supported floor may rise, it applies the matching fix instead and updates engines in the same change. The project has no test script, so the agent adds a smoke test that runs hide and reveal with the password taken from the STEGCLOAK_PASSWORD variable, which cli.js already reads, and checks that the revealed text equals the input.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "This project fails with 'Error [ERR_REQUIRE_ESM]: require() of ES Module' after a dependency upgrade, or will when its dependencies are upgraded. Read package.json (type, main, bin, exports, engines), the lock file and the entry files. List every dependency whose latest major is ESM-only, with its current range, the last version that supports require, and the engines.node of the latest release (use npm view). For each one that the upgrade touches, reproduce the failure and quote it. Run the entry point on every Node major the engines field and CI allow, plus the current LTS, and do not stop at --help: run a command that reaches the upgraded package's API, because newer Node can load the module and fail later with a TypeError. Test these fixes on each Node version and report the results as a table: reading .default from the require; dynamic import() inside an async function; converting the package to ES modules; staying on the last CommonJS major; replacing the package with a built-in such as util.styleText. Choose the fix that works on every Node version the engines field promises. If none does without raising the floor, keep the last CommonJS major, add an ignore rule for the next major if the repository has an update bot configuration, and state what each alternative would need. Do not change the module type of a file other packages import unless asked. Add a smoke test for the command-line entry point if the project has no tests, using any non-interactive input the program already supports. Open a pull request.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- 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.
- 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.
- 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 with the results table at the top: one row per fix, one column per Node version, each cell either the output or the first line of the error. Under it, the decision and the reason in one sentence tied to the engines field. For stegcloak in its current state the diff is small: newer versions of the four packages within their current majors in package.json and the lock file, a smoke test and a test script that runs it in place of the placeholder that prints an error and exits 1.
The reviewer checks the table against their own support policy. If nobody runs the tool on Node below 20.19 any more, the better outcome is to raise engines and take the newer packages, and the description says which row to pick and what else changes with it. They also check that the smoke test exercises a coloured code path and not only startup, since that is the difference between catching this bug and missing it on newer Node.
Run it on every Linear issue labelled esm-upgrade
ESM-only releases arrive one package at a time, and each tends to become a ticket: an update pull request fails, someone files the error, and it waits. Give that ticket a label and let the label start the work. Create an automation in the Project that holds the repository, save this prompt, and add a linear trigger with labels set to esm-upgrade. The trigger needs a Linear connection for the member the automation runs as, made in the console under Settings → Connections.
When a person in your Rush org adds the label, a run starts with the saved prompt, and the issue is placed after it as the event. The prompt is the only instruction, so word it to treat the issue text as a description of which package failed and nothing more. A label added by an app integration does not fire the trigger. The pull request link comes back on the session, and the automation's max runs per hour keeps a bulk relabel from starting dozens at once.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
The answer depends on Node versions most developers do not have installed side by side. Whether .default works, whether styleText exists, whether the error is thrown at load or three commands later: each differs between 18, 20.10, 20.19 and 22. The run installs those versions in its own sandbox and executes the real entry point on each, and the transcript keeps every command with its output, so the table in the pull request can be traced cell by cell.
It also guards against the false fix. On a current laptop the upgraded tool starts, prints its help and looks fine. Running a command that reaches the package's API, on the oldest Node the project claims to support, is what shows the truth, and that is tedious enough by hand that it is usually skipped.
Frequently asked questions
Why did this start after a minor dependency update?
Usually it was a major update of a transitive or direct dependency that became ESM-only, such as chalk 4 to 5, pulled in by a broad version range or an update bot. The code did not change; the package stopped shipping a CommonJS build. The error message names the file that was required and the file that required it.
Does Node 22 fix ERR_REQUIRE_ESM by itself?
It removes the error at load time, because recent Node releases can require an ES module. But the value you get back is the module namespace, so a default export sits under .default. Code written as const chalk = require('chalk') then fails later with chalk.red is not a function. Either read .default or use import.
Is it fine to stay on chalk 4?
Yes, for a CommonJS project that must support older Node. chalk 4.1.2 works with require and declares Node 10 and up. The cost is that you stop receiving new majors, so revisit the choice when you raise your minimum Node version or move the project to ES modules.
Can I use dynamic import() in a CommonJS file?
Yes. await import('chalk') works in CommonJS on Node 18, 20 and 22 alike, but only inside an async function, since CommonJS has no top-level await. That often means wrapping the program's entry point in an async main and loading the ESM-only packages there.
Should I convert the whole project to ES modules?
It is the cleanest end state for an application. For a library, check who imports you first: setting "type": "module" changes how every .js file in the package is loaded, including the main entry that other CommonJS projects require. The agent does not make that change unless the request asks for it.
More jobs like this: Upgrade dependencies weekly
- Fix "TypeError: expressValidator is not a function" After Upgrading express-validator (express-validator)
- Fix "AttributeError: 'FigureCanvasAgg' object has no attribute 'tostring_rgb'" (Matplotlib)
- Fix "AttributeError: 'Graph' object has no attribute 'node'" in NetworkX (NetworkX)
- Fix grpc.WithInsecure Is Deprecated (SA1019) in a Go gRPC Service (gRPC-Go)
- Fix "npm warn deprecated gulp-util: gulp-util is deprecated" in a Gulp Build (Gulp)
- Fix "ImportError: cannot import name 'contextfilter' from 'jinja2'" (Jinja2)