Frontend fails to start on first `reflex run` due to Error [ERR_REQUIRE_ESM] (React Router / p-map interop)

[amir-codes-here]

Problem Summary

Running reflex run on a new Reflex project fails immediately during frontend startup.
The generated frontend attempts to require() an ES-module-only dependency (p-map), which causes Node to throw ERR_REQUIRE_ESM and Vite exits with code 1.

This appears to come from @react-router/dev in the generated .web folder, which still uses CommonJS require() for p-map, but p-map installs as ESM (v5.x) on modern Node versions (e.g., Node 22).

Environment

OS: Windows 10 (64-bit) (WSL not used)

Reflex version: 0.8.19

Node version: 22.8.0

npm version: 10.8.2

Fresh project: yes (error happens on a brand-new Reflex project before any code changes)

Steps to Reproduce the Error

1. Install reflex

pip install reflex

2. Initialize reflex project (choose blank app template option)

reflex init

3. Attempt to run

reflex run

4. Frontend build fails with exit code 1.

Actual Behavior (Full Error)

Starting frontend failed with exit code 1
$ react-router dev --host
failed to load config from .web/vite.config.js
Error [ERR_REQUIRE_ESM]: require() of ES Module 
.web/node_modules/p-map/index.js from 
.web/node_modules/@react-router/dev/dist/vite.js not supported.

Instead change the require of index.js in 
.web/node_modules/@react-router/dev/dist/vite.js to a dynamic import() 
which is available in all CommonJS modules.
    at Object.<anonymous> (.web/node_modules/@react-router/dev/dist/vite.js:62:28) 
{
  code: 'ERR_REQUIRE_ESM'
}

error: script "dev" exited with code 1

Additional Notes

• This happens because p-map starting from v5 is ESM-only, so require("p-map") no longer works under modern Node versions (Node 18+).

• The file causing the crash is inside .web/node_modules/@react-router/dev/dist/vite.js.

• Manually replacing require("p-map") with await import("p-map") or pinning p-map@4 via overrides works, but these are temporary workarounds because .web/ is regenerated. Besides, this shouldn't be happening at the first place. Solving these problems is frustrating for beginners.

• Downgrading to Node 20 probably avoids the issue because some dependency resolutions differ and CJS p-map is installed instead. Although requiring users to downgrade to Node 20 is not a sustainable solution, as modern environments (including Node 22+) are becoming the default, and a web framework should remain compatible with current LTS and latest Node releases without forcing developers to regress their tooling.

Request / Proposal

• Consider pinning a CJS-compatible version of p-map in the generated frontend dependencies.

• Alternatively, patch the Reflex template to ensure that @react-router/dev is used in a version that no longer uses CJS require() for ESM-only packages.

• Or provide a guard/warning for unsupported Node versions (Node 22+).

[adhami3310]

i'm not hitting this issue, would you try installing an older version of p-map inside of .web? i want to verify it's the recent release of p-map that has the issue

[patricksurry]

new user trying reflex; I just ran into this. downgrading node v21 to v20 worked for me.

[adhami3310]

node v21 has reached EOL