Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท tsconfig: Language, Modules and Emit Options

TypeScript allowSyntheticDefaultImports option

Reference for allowSyntheticDefaultImports: a type-checking-only option that permits default imports from modules without a default export, and how it differs from esModuleInterop.

allowSyntheticDefaultImports lets you write import x from "module" for a module whose declaration has no export default. The compiler pretends the whole module is the default export. It is a type-checking switch only: it changes no emitted code and cannot make the import work at runtime.

It exists for module systems where the default import really does work: bundlers and Node's native ESM treat a CommonJS module's module.exports as default. esModuleInterop turns it on automatically, so you rarely set it by hand.

TypeScript
import React from "react";   // allowed when the typings use export =

Try it

TypeScript Namespace versus default view of a CommonJS module

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 What a synthetic default looks like

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.

Syntax

JSON
{ "compilerOptions": { "allowSyntheticDefaultImports": true } }
Part Description
Type boolean. Default: true when esModuleInterop, module: system or moduleResolution: bundler is used; otherwise false.
Command line tsc --allowSyntheticDefaultImports
Effect Type checker only. Removes error TS1259 ("can only be default-imported using the 'allowSyntheticDefaultImports' flag") on default imports of export = modules.

Usage notes

  • It does not add __importDefault or any other helper. If your emit target is plain CommonJS and nothing interops, x.default is undefined at runtime even though it type-checks.
  • Use esModuleInterop instead when you compile to CommonJS: it implies this option and adds the helpers.
  • In bundler and native ESM setups this option alone is sufficient for type-checking because the runtime provides the default.
  • It affects only declarations written as export = something or declaration files without a default. If a module already has export default, nothing changes.
  • A common pattern: libraries distributed as CommonJS typed with export =, such as older Express or React type packages.
  • Errors TS1259 and TS2497 usually point to a missing interop setting, not to a bug in the import.