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.
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.
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.
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.
// 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 moderntsc --initoutput) 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 xon a CommonJS module changes meaning (the namespace object is a copy under interop, not the module itself). - Modern projects that use
module: nodenextdo 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.tsfor theexport =line.- Bundlers (Vite, esbuild, webpack) do their own interop;
allowSyntheticDefaultImportsormoduleResolution: bundlerplusesModuleInteropkeeps 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.