In tsconfig.json, what is the difference between the `esModuleInterop` and `allowSyntheticDefaultImports` compiler options?

## The friction both flags exist for ES modules and CommonJS disagree about what "the module's value" is. A CommonJS module has one mutable `module.exports` value; an ES module has a set of named bindings, one of which may be called `default`. When a TypeScript file written in ES module syntax consumes a CommonJS package, someone has to decide what `import x from 'pkg'` means. Both flags are answers to that, but at different layers of the compiler: one at the type level, one at the emit level. ## allowSyntheticDefaultImports — checking only The declarations for an old-style package typically describe it as an export-assignment (`export = Thing`) with no `default` member at all. Without this flag, writing `import thing from 'pkg'` is an error: there is no default export to import. Turning `allowSyntheticDefaultImports` on tells the checker to *pretend* a default export exists, bound to the module's export-assigned value. That is the entire effect. The compiler emits exactly what it emitted before; no helper appears, no import is rewritten. The flag is a statement about the environment: "whatever loads this code will give me a default, so stop complaining." That statement is often true, because a bundler or a native ESM loader does synthesise a default for CommonJS. It is exactly why the flag is the right choice when `tsc` is not the thing producing the runtime output. ## esModuleInterop — checking and emit `esModuleInterop` is a superset. It implies `allowSyntheticDefaultImports`, so the checking relaxation comes along, and it changes CommonJS emit so the runtime behaviour matches the pretence. ```json { "compilerOptions": { "module": "commonjs", "esModuleInterop": true } } ``` Under this configuration, a default import no longer compiles to a bare `require()` whose result is used directly. The compiler emits a small helper that inspects the required value and produces something with a `default` property, so the ESM-shaped source and the CommonJS-shaped dependency agree. Namespace imports (`import * as ns`) get their own helper, producing an object that behaves like a real module namespace. Because the flag only affects emitted CommonJS, it is irrelevant to output that is already ESM — there is no `require` to wrap. ## The tightening nobody expects Interop is not purely permissive. Before it, TypeScript let you treat a namespace import as the module's export value, so `import * as express from 'express'; express();` worked. With `esModuleInterop` on, that is an error: a namespace import is a namespace object, and a namespace object is not callable or constructable. The two correct spellings become: ```ts import express from "express"; // default import import express = require("express"); // TypeScript's export-assignment import ``` This is the single most common breakage when a codebase turns the flag on, and being able to name it is what separates a memorised answer from an experienced one. ## Defaults, and which one to set In TypeScript 5.x, `esModuleInterop` is on by default when `module` is `node16`, `nodenext` or `preserve`, and off otherwise; `allowSyntheticDefaultImports` defaults to on whenever `esModuleInterop` is on. Practical guidance: - **`tsc` produces the CommonJS you run** → `esModuleInterop: true`. You want the emit to match the checking. - **A bundler or another transpiler produces the output, and `tsc` only checks** → `allowSyntheticDefaultImports: true` is the honest setting. It aligns the checker with what the bundler will actually do, and it makes clear that `tsc`'s emit is not what runs. - **Output is native ESM** → the emit half is moot; only the checking relaxation matters. ## What this is not Neither flag changes what a package exports, and neither performs any runtime conversion of its own beyond the emitted helper. They are compiler-surface options: one adjusts what the checker will accept, the other also adjusts what the compiler writes. If the underlying question is what a CommonJS package's shape looks like to a native ESM loader, that is a runtime-semantics question, not a tsconfig one — the flags only decide how TypeScript's own compilation lines up with it.