Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Modules and Declaration Files

ES modules in TypeScript

Reference for ES module syntax in TypeScript: named, default and namespace imports and exports, type-only imports, re-exports, dynamic import and top-level await.

A file becomes a module the moment it contains a top-level import or export. Its declarations are then private to that file unless exported, and it runs once, no matter how many files import it. A file without either is a script, whose top-level names land in the global scope.

TypeScript supports the full ES module syntax and adds type-only forms that disappear from the output. How import paths are resolved and whether the output is ESM or CommonJS depend on the module and moduleResolution options (nodenext and bundler are the usual choices).

TypeScript
import { readFileSync } from "node:fs";
import * as path from "node:path";
import type { Stats } from "node:fs";
export const answer = 42;
export default function hello(): string { return "hi"; }

Try it

TypeScript Imports, exports and dynamic import

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 Type-only imports are erased

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

TypeScript
// Imports
import def from "mod";                  // default
import { a, b as c } from "mod";        // named, with rename
import * as ns from "mod";              // namespace object
import type { T } from "mod";           // type only
import { type T, value } from "mod";    // inline type modifier
import "mod";                           // side effects only
const m = await import("mod");          // dynamic

// Exports
export const x = 1;
export { a, b as c };
export default expression;
export * from "mod";                    // re-export everything but default
export * as ns from "mod";
export type { T } from "mod";
export = thing;                         // CommonJS style (needs a compatible module setting)
Form Description
Named Binding names must match the export (or be renamed with as). Bindings are live: they reflect later changes to the exporter's variable.
Default One per module; imported under any local name.
Namespace An object holding all named exports, frozen.
Type-only Checked by the compiler, removed from the output.

Edge cases: an import declaration must be at the top level, but import() can appear anywhere. Modules support top-level await, which needs a module-aware target (ES2017+ with module set to es2022, esnext, node16, nodenext or similar).

Usage notes

  • Under nodenext, relative imports in ESM files need a file extension, written as the output extension: import ./util.js for a source file util.ts.
  • Use import type (or the inline type modifier) for names that are only types. With verbatimModuleSyntax, ordinary imports that are used only as types are an error, and imports are emitted exactly as written.
  • Whether the file is ESM or CommonJS under nodenext depends on the nearest package.json "type" field and the file extension (.mts and .cts force one or the other).
  • Circular imports work but may expose uninitialized bindings; keep import-time code free of cross-module reads.
  • A default import from a CommonJS package usually needs esModuleInterop; see ESM and CJS interop.
  • export * from does not re-export a default.