How to fix ts-node: ERR_REQUIRE_ESM in TypeScript

TypeScriptINTERMEDIATEMEDIUM

This error occurs when ts-node tries to load an ES module (ESM) using CommonJS require(). It happens when mixing module systems, typically when a package uses ESM exports but your tsconfig.json or runtime expects CommonJS. The fix involves aligning module systems across your configuration.

What this error means

The ERR_REQUIRE_ESM error is thrown by ts-node when it attempts to use Node.js's require() function to load a module that is an ES Module (ESM). This happens because: 1. **Module System Mismatch**: Node.js has two module systems: CommonJS (using require()) and ES Modules (using import/export). They are not directly compatible. 2. **Package.json Type**: Many modern npm packages now use "type": "module" in their package.json, making them ES Modules by default. 3. **ts-node Configuration**: By default, ts-node uses CommonJS. When it encounters an ESM package, require() fails with this error. 4. **TypeScript Compiler Options**: Your tsconfig.json might be set to "module": "commonjs" while dependencies use ESM. The error typically appears when: - Importing a library that recently switched to ESM - Using TypeScript with mixed module systems - Running tests or scripts with ts-node in a project with ESM dependencies

How to fix "ts-node: ERR_REQUIRE_ESM"

1Check your tsconfig.json module setting

First, verify your TypeScript configuration. Open tsconfig.json and check the "module" field:

json

{
  "compilerOptions": {
    "module": "commonjs",  // This might need to change
    // ... other options
  }
}

If you need to use ESM, change it to:

json

{
  "compilerOptions": {
    "module": "ESNext",  // or "ES2020", "ES2022"
    // ... other options
  }
}

For CommonJS projects, keep "module": "commonjs" but ensure proper ESM interop.

2Update package.json with proper type field

Add or modify the "type" field in your package.json:

For ESM projects:

json

{
  "type": "module",
  "scripts": {
    "start": "node --loader ts-node/esm ./src/index.ts"
  }
}

For CommonJS projects:

json

{
  "type": "commonjs",
  "scripts": {
    "start": "ts-node ./src/index.ts"
  }
}

If you're mixing module systems, you might need additional configuration.

3Configure ts-node for ESM support

If using ESM, update your ts-node configuration. Create or update tsconfig.json:

json

{
  "ts-node": {
    "esm": true,
    "experimentalSpecifierResolution": "node"
  },
  "compilerOptions": {
    "module": "ESNext"
  }
}

Or use command-line flags:

bash

# For ESM
ts-node --esm --experimental-specifier-resolution=node index.ts

# Or with loader
node --loader ts-node/esm index.ts

4Use dynamic import() for ESM packages

If you need to import an ESM package in a CommonJS file, use dynamic import():

typescript

// Instead of:
// import { something } from 'esm-package';

// Use dynamic import:
const { something } = await import('esm-package');

// Or wrap in async function
async function useEsmPackage() {
  const esmModule = await import('esm-package');
  return esmModule.something();
}

Note: Dynamic imports return Promises, so you need to handle them asynchronously.

5Update file extensions for ESM

ESM requires specific file extensions. Rename your files:

- Change .ts to .mts for ESM TypeScript files
- Change .js to .mjs for ESM JavaScript files
- Or keep extensions but ensure package.json has "type": "module"

Example structure:

bash

src/
├── index.mts          # ESM TypeScript
├── utils.mts
└── commonjs/
    └── legacy.cjs    # CommonJS JavaScript

Update imports to use full extensions:

typescript

import { helper } from './utils.mjs';  // Not './utils'

6Configure Jest or test runners for ESM

If tests fail, update Jest configuration in package.json or jest.config.js:

javascript

// jest.config.js
export default {
  preset: 'ts-jest/presets/default-esm',
  extensionsToTreatAsEsm: ['.ts'],
  moduleNameMapper: {
    '^(\.{1,2}/.*)\.js$': '$1',
  },
  transform: {
    '^.+\.tsx?$': [
      'ts-jest',
      {
        useESM: true,
      },
    ],
  },
};

Or use ts-jest with ESM:

bash

npm install --save-dev ts-jest @types/jest
npx ts-jest config:init

How to fix ts-node: ERR_REQUIRE_ESM in TypeScript

What this error means

Typical symptoms

Common causes

How to fix "ts-node: ERR_REQUIRE_ESM"

Advanced notes

Related errors

Official resources & further reading