Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Error Codes Worth Knowing

TypeScript errors TS1259 and TS2497: default import needs an interop flag

TS1259 and TS2497 appear when you default-import or namespace-import a CommonJS module that uses export =. See why and how to fix imports or the config.

Both errors come from CommonJS-style declarations. A module whose declaration says export = something exposes one value as the whole module. ES module syntax then has two ways to reach it, and each needs help from a compiler flag.

TS1259 reads Module '"x"' can only be default-imported using the 'esModuleInterop' flag. and appears for import x from "x". TS2497 reads This module can only be referenced with ECMAScript imports/exports by turning on the 'esModuleInterop' flag and referencing its default export. and appears for import * as x from "x" when the thing exported is a function or class rather than a namespace. Some versions report a variant of the first message that mentions allowSyntheticDefaultImports.

TypeScript
import express from "express";   // TS1259 without esModuleInterop

Try it

Because the failure depends on a CommonJS package and on tsconfig flags, which a single checked file cannot recreate, the broken forms are read-only. The runnable examples show forms that work with Node's built-in modules under modern settings.

TypeScript Default and namespace imports that work

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript The import-equals form for export = modules

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript
// Read-only: what fails without interop, and the choices.
import express from "express";        // TS1259 when esModuleInterop is off
import * as express2 from "express";  // namespace import cannot be called (TS2497 for callable export =)
import express3 = require("express"); // always works for export = (CommonJS output only)

Syntax

Flag What it does Effect on these errors
esModuleInterop: true Emits helpers so default and namespace imports of CommonJS modules behave like Babel/Node; also turns on allowSyntheticDefaultImports. Removes TS1259 and TS2497.
allowSyntheticDefaultImports: true Type-level only: lets import x from type-check without emitting helpers. Removes TS1259, but runtime behavior is up to your bundler or runtime.
module: nodenext or node16 Interop is built in for ES modules importing CommonJS. These errors do not occur for ordinary packages.
module: commonjs plus both flags off Old default. Use import x = require("x"), or turn a flag on.

Usage notes

  • Set esModuleInterop: true (it is on by default in modern tsc --init output) unless you have a specific reason not to. Mixing code compiled with and without it causes subtle runtime differences.
  • Do not flip the flag partway through a project without testing: import * as x on a CommonJS module changes meaning (the namespace object is a copy under interop, not the module itself).
  • Modern projects that use module: nodenext do not need to think about this for packages that ship proper ESM or CJS metadata.
  • export = packages in @types (such as older Express typings) are the usual trigger. Check the package's .d.ts for the export = line.
  • Bundlers (Vite, esbuild, webpack) do their own interop; allowSyntheticDefaultImports or moduleResolution: bundler plus esModuleInterop keeps the type checker consistent with them.
  • Alternative with no flags: import x = require("x") works for CommonJS output only and cannot be used in ES module output.