CJS build has undeclared ESM-only dependencies, breaking use in CommonJS projects

[markedwards]

mockttp 4.x ships a CommonJS build (dist/) but depends on packages that are pure ESM-only, including at least get-port and milliparsec.

This causes a hard crash when mockttp is loaded in a CommonJS context:

Error: require() of ES Module node_modules/.pnpm/get-port@7.2.0/node_modules/get-port/index.js
from .../mockttp/dist/server/mockttp-server.js not supported.

Environment:

mockttp: 4.3.0
Node.js: 24.13
Package manager: pnpm (monorepo)
Project type: Next.js, no "type": "module" in package.json

How to reproduce:

Load mockttp in any CommonJS Node.js context — specifically one that doesn't have ESM interop handling, such as the VSCode Playwright extension's test runner process.

Note: this does not surface when running tests via the CLI, because Next.js/the test runner handles ESM interop transparently. It only becomes visible in plain CommonJS contexts.

Expected behaviour:

A package that ships a CJS build should either:

• Only depend on CJS-compatible packages, or
• Ship a proper dual CJS/ESM build and declare both in package.json exports, or
• Use dynamic import() in the CJS build where ESM dependencies are required

Actual behaviour:

The CJS build hard-crashes with a require() of ESM error. Attempting to override get-port to an older version via pnpm overrides surfaces additional ESM-only dependencies (milliparsec), suggesting this is a systemic issue across multiple dependencies rather than a single transitive dependency problem.

[pimterry]

Hmm, interesting. Officially that's intended - since v4 the engines field in package.json says we only support Node v20+, and all those actively supported Node versions support this just fine nowadays. We do test in the latest version of all actively supported Node release lines (v20, v22, v24, v25) and this works fine there without Next.js or special test runners setups. If you launch normal Node and import Mockttp it should work just fine.

I'm not sure how VSCode Playwright extension's test runner process works, but if it's running the Mockttp backend it must be some Node version (we use lots of Node-only APIs for HTTP processing). Can you work out which Node version it's using? This might just be a configuration issue where you're using an old version of Node there on your machine, and updating to the latest v20 would fix it.

[markedwards]

This is running in a docker container with only Node 24.13 available.

[pimterry]

Mockttp works in Node 24.13 with no problems:

➜ docker run --rm -it node:24.13 /bin/bash
root@780f903e2612:/# cd /tmp
root@780f903e2612:/tmp# npm install mockttp

added 190 packages in 6s

27 packages are looking for funding
  run `npm fund` for details
npm notice
npm notice New minor version of npm available! 11.8.0 -> 11.13.0
npm notice Changelog: https://github.com/npm/cli/releases/tag/v11.13.0
npm notice To update run: npm install -g npm@11.13.0
npm notice
root@780f903e2612:/tmp# node
Welcome to Node.js v24.13.1.
Type ".help" for more information.
> require('mockttp')
# Imports with no errors

[markedwards]

Yes, we run playwright with it in CI and via cli. But it breaks the Playwright VSCode extension due to this import issue, running in the exact same dev container.

It's difficult to diagnose why it's breaking, but it's not a difference of runtime environment.

[pimterry]

This must be related to the Node version you have installed. This is how that extension finds Node: https://github.com/microsoft/playwright-vscode/blob/1416b2a1f2f046a22e9ae3343e9ae1f5f4459f0b/src/utils.ts#L95-L118. It looks in your $PATH, and then falls back to creating a shell to try to delegate to the default node used by nvm and similar. I think most likely it's somehow finding an old version of Node on your system and that's causing the problem.

There's some logging in that extension you can look at, or you can just try logging process.version inside your test directly while running it with the extension (before the failing require runs) to confirm which version it is, and process.execPath to find where that is on your machine.

[markedwards]

This appears to be tied to some weird behavior in Cursor. I am still digging to fully prove/understand it and will update here when done. Thanks for the info!