[Feature]: Allow require for pure ESM packages with --experimental-require-module

[SimpleCreations]

🚀 Feature Proposal

Allow using require for pure ESM packages. This can be either the default behavior, or enabled by reading the --experimental-require-module Node option, or by having a setting in the config (e.g. allowEsmRequire: true).

Motivation

There's an experimental --experimental-require-module flag in Node 22 and 20.17 that allows using CJS require for pure ESM packages. This is great for CJS projects that cannot migrate to ESM yet (e.g. NestJS projects), because they can use modern versions of pure ESM dependencies.

I was able to make it work by adding babel-jest to the project and configuring it to apply @babel/plugin-transform-modules-commonjs plugin to my specific pure ESM dependency. But of course it's more desirable that this works out of the box.

Example

jest.config.mjs

export default {
  testEnvironment: 'node',
  testRegex: '\\.spec.js$',
  moduleFileExtensions: ['js'],
};

package.json

{
  "name": "jest-require-esm-repro",
  "version": "1.0.0",
  "main": "index.js",
  "devDependencies": {
    "jest": "^29.7.0"
  },
  "dependencies": {
    "nanoid": "^5.0.7"
  }
}

index.js

const { nanoid } = require("nanoid");

exports.id = nanoid()

index.spec.js

const { id } = require('.');

describe('index', () => {
  test('should return ID', () =>
    expect(typeof id).toBe("string"));
})

Running the code ✅

jest-require-esm-repro % node --experimental-require-module                                      
Welcome to Node.js v22.6.0.
Type ".help" for more information.
> const { id } = require('.'); id;
'ErAKzYGR5Jkda5HfVnBKb'

Running Jest ❌

 jest-require-esm-repro % node --experimental-require-module node_modules/.bin/jest
 FAIL  ./index.spec.js
  ● Test suite failed to run

    Jest encountered an unexpected token

    Jest failed to parse a file. This happens e.g. when your code or its dependencies use non-standard JavaScript syntax, or when Jest is not configured to support such syntax.

    Out of the box Jest supports Babel, which will be used to transform your files into valid JS based on your Babel configuration.

    By default "node_modules" folder is ignored by transformers.

    Here's what you can do:
     • If you are trying to use ECMAScript Modules, see https://jestjs.io/docs/ecmascript-modules for how to enable it.
     • If you are trying to use TypeScript, see https://jestjs.io/docs/getting-started#using-typescript
     • To have some of your "node_modules" files transformed, you can specify a custom "transformIgnorePatterns" in your config.
     • If you need a custom transformation specify a "transform" option in your config.
     • If you simply want to mock your non-JS modules (e.g. binary assets) you can stub them out with the "moduleNameMapper" config option.

    You'll find more details and examples of these config options in the docs:
    https://jestjs.io/docs/configuration
    For information about custom transformations, see:
    https://jestjs.io/docs/code-transformation

    Details:

    ~/jest-require-esm-repro/node_modules/nanoid/index.js:1
    ({"Object.<anonymous>":function(module,exports,require,__dirname,__filename,jest){import { webcrypto as crypto } from 'node:crypto'
                                                                                      ^^^^^^

    SyntaxError: Cannot use import statement outside a module

    > 1 | const { nanoid } = require("nanoid");
        |                    ^
      2 |
      3 | exports.id = nanoid()
      4 |

      at Runtime.createScriptFromCode (node_modules/jest-runtime/build/index.js:1505:14)
      at Object.require (index.js:1:20)
      at Object.require (index.spec.js:1:16)

Test Suites: 1 failed, 1 total
Tests:       0 total
Snapshots:   0 total
Time:        0.14 s, estimated 1 s
Ran all test suites.

Pitch

Jest includes its own module resolution system. Lack of ESM require makes it not on par with Node's module resolution system, meaning that even if I can make the runtime code work with native Node, I have include some sort of transformations to make it work with Jest.

[github-actions]

This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 30 days.

[SimpleCreations]

Not stale

[scarracedo]

In node 23 the flag is enabled by default so require a pure ESM module is something allowed by default. Include this behavior in jest it will be very useful for projects can not be migrated to ESM

[github-actions]

This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 30 days.

[darky]

unstale

[darky]

My temporary workaround is to use ts-jest for transpilation of ESM to CommonJS on the fly, example:

jest config

{
  "jest": {
    "globals": {
      "ts-jest": {
        "tsConfig": "tsconfig.test.json"
      }
    },
    "moduleFileExtensions": [
      "js",
      "json",
      "ts"
    ],
    "roots": [
      "<rootDir>/test/"
    ],
    "testRegex": ".*\\.spec\\.ts$",
    "transform": {
      "^.+\\.(t|j)s$": [
        "ts-jest",
        {
          "isolatedModules": true
        }
      ],
      "node_modules/get-port/index.js": [
        "ts-jest",
        {
          "isolatedModules": true
        }
      ],
      "node_modules/p-do-whilst/index.js": [
        "ts-jest",
        {
          "isolatedModules": true
        }
      ],
      "node_modules/p-forever/index.js": [
        "ts-jest",
        {
          "isolatedModules": true
        }
      ]
    },
    "transformIgnorePatterns": [
      "/node_modules/(?!(get-port|p-do-whilst|p-forever)/)"
    ]
  },
}

tsconfig.test.json

{
  "compilerOptions": {
    "allowJs": true
  },
  "extends": "./tsconfig.json"
}

tsconfig.json

{
  "compilerOptions": {
    "module": "commonjs",
    "// some another options": "// some another options"
  }
}

[github-actions]

This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 30 days.

[SimpleCreations]

Not stale

[forivall]

in 22.13.0 (LTS), the flag is also now enabled by default.

[mmarinero]

I had trouble using jest after requiring an ESM-only package in Node 22.13.0. I found a similar workaround to #15275 (comment)

In my case, I had to use babel-jest to transform an ESM-only package from node_modules, and ts-jest was not handling the *.mjs source (probably some config issue on my side as it should handle it with the settings explained above).

jest.config.ts

...
  transform: {
    '^.+\\.mjs$': 'babel-jest',
  },
  transformIgnorePatterns: ['/node_modules/(?!(@acme/package)/).*/'], // Force the transform of this package inside node_modules
 ...

babel.config.js

// Needed for jest.config.ts to use babel-jest, babel.config file name seems important
module.exports = {
  presets: ['@babel/preset-env'],
};