Understanding esModuleInterop and allowSyntheticDefaultImports in TypeScript

By the end of this page, you will understand why TypeScript sometimes struggles with imports from CommonJS modules, what allowSyntheticDefaultImports changes in type checking, what esModuleInterop changes in emitted JavaScript, and why these options are commonly enabled together in real projects.

TypeScript sits between your source code and the JavaScript module system you are targeting. The confusion here comes from the fact that there are two different module styles in the JavaScript ecosystem:

• ES Modules (ESM)
  • Use export and import
  • Example:

export default function greet() {
  console.log("Hello")
}

import greet from "./greet"

• CommonJS (CJS)
  • Use module.exports and require
  • Example:

module.exports = function greet() {
  console.log("Hello")
}

Think of ES Modules and CommonJS as two different plug shapes.

• ES Modules are one plug type
• CommonJS modules are another plug type

Your TypeScript code wants to use a modern ES module-style plug:

import thing from "package"

But the actual package might be exporting itself in a CommonJS shape.

allowSyntheticDefaultImports

This is like saying:

"It's okay to pretend this plug fits while we are checking the blueprint."

It makes the code look acceptable to TypeScript.

esModuleInterop

This is like adding a real adapter so the plug actually fits when the code runs.

So a simple way to remember it is:

• allowSyntheticDefaultImports = "let me write it"
• esModuleInterop = "make it work more reliably"

That is why esModuleInterop is usually the better setting when you are importing CommonJS packages using default-import syntax.

Core idea

Here is a CommonJS module:

// math.js
module.exports = function add(a, b) {
  return a + b
}

CommonJS usage

const add = require("./math")
console.log(add(2, 3))

ES module-style usage in TypeScript

import add from "./math"
console.log(add(2, 3))

Whether that TypeScript import is allowed and works correctly depends on your compiler settings.

Example 1: allowSyntheticDefaultImports

{
  "compilerOptions": 
     
     
  

Consider this TypeScript code:

import path from "path"

const result = path.join("src", "index.ts")
console.log(result)

Assume module is set to commonjs.

What happens conceptually with esModuleInterop: true

Step 1: You write a default import

import path from "path"

You are saying: "Give me the module's default export and call it path."

Step 2: TypeScript checks the module

The path module is not written as a normal ES module with export default.

Without compatibility settings, TypeScript may complain because the module shape does not match a true default export.

Step 3: esModuleInterop allows compatibility

TypeScript treats the CommonJS module in a way that supports this style of import.

Importing popular npm packages

Many packages in the Node.js ecosystem were historically published as CommonJS modules.

Examples developers often import with esModuleInterop enabled:

import express from "express"
import cors from "cors"
import dotenv from "dotenv"

This style is shorter and more familiar than older interop patterns.

Working in Node.js backends

In backend TypeScript apps, especially older CommonJS-based projects, these settings make it easier to use packages from npm without constantly switching import styles.

Migrating JavaScript projects to TypeScript

If a codebase already uses Babel or default-import syntax everywhere, enabling esModuleInterop makes migration smoother.

Using type definitions from DefinitelyTyped

Some type definition packages were written with compatibility assumptions in mind. These flags help TypeScript work more smoothly with those packages.

Consistent developer experience

Teams often choose esModuleInterop: true so developers can use one predictable import style across many dependencies, even if those dependencies were authored in different module formats.

In real projects, developers usually do not think about these flags every day. They just want imports to be clear and reliable.

Common pattern: enable esModuleInterop

A very common setup is:

{
  "compilerOptions": {
    "module": "commonjs",
    "esModuleInterop": true,
    "strict": true
  }
}

Because esModuleInterop also enables allowSyntheticDefaultImports, teams usually set only the first one.

Why teams prefer it

• cleaner imports
• less confusion when using npm packages
• better compatibility with examples from documentation and tutorials
• easier migration from Babel-based JavaScript projects

In library code vs application code

• Application code often enables esModuleInterop for convenience.
• Library code may be more careful, especially if the library must support multiple module systems and produce clean public typings.

1. Thinking both options do the same thing

They are related, but not identical.

• allowSyntheticDefaultImports affects type checking only
• esModuleInterop affects runtime emit behavior and also enables allowSyntheticDefaultImports

2. Assuming allowSyntheticDefaultImports makes runtime code work

Broken expectation:

import somePackage from "some-package"

If only allowSyntheticDefaultImports is enabled, TypeScript may accept the code, but the emitted JavaScript may still not behave correctly at runtime.

How to avoid it:

• Prefer esModuleInterop when using default imports from CommonJS modules

3. Confusing default export with "main thing exported"

In CommonJS, this is valid:

module.exports = function () {
  console.()
}

vs

{
  "compilerOptions": {
    "module": "commonjs",
    "esModuleInterop": true
  }
}

Quick rules

• allowSyntheticDefaultImports: true

  • allows default-import syntax during type checking
  • does not change emitted JavaScript

• esModuleInterop: true

  • changes emitted JavaScript for better CommonJS interop
  • automatically enables allowSyntheticDefaultImports

Easy memory trick

• allowSyntheticDefaultImports = allow the syntax
• esModuleInterop = allow the syntax and help it work at runtime

Common examples

With interop

 express  

What does esModuleInterop do in TypeScript?

It helps TypeScript work more smoothly with CommonJS modules when you use ES module import syntax such as import x from "pkg".

Does esModuleInterop automatically enable allowSyntheticDefaultImports?

Yes. Enabling esModuleInterop also enables allowSyntheticDefaultImports.

What does "does not affect code emit, just typechecking" mean?

It means TypeScript will allow the import syntax during compile-time checks, but it will not change the generated JavaScript to make that syntax work at runtime.

Should I enable both options?

Usually you only need esModuleInterop: true, because it already includes the behavior of allowSyntheticDefaultImports.

Why do some examples use import * as express from "express"?

That style was commonly used when interop support was stricter or disabled. With esModuleInterop, many developers now use import express from "express" instead.

Is CommonJS the same as export default?

No. is not exactly the same thing as an ES module , even though they can feel similar in everyday use.

• CommonJS — These options mainly exist to improve compatibility with CommonJS modules.
• ES Modules — Understanding import, export, and export default makes these flags much easier to understand.
• module in tsconfig — The module setting affects how TypeScript emits import/export code.
• moduleResolution — Helps explain how TypeScript finds packages and type definitions.
• default export vs named export — This is the core import/export difference behind the confusion.
• require vs import — A practical comparison for understanding Node.js module history.
• Babel and TypeScript interoperability — Useful because many docs and code examples assume Babel-style interop behavior.