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).
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
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.
Syntax
// 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.jsfor a source fileutil.ts. - Use
import type(or the inlinetypemodifier) for names that are only types. WithverbatimModuleSyntax, 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
nodenextdepends on the nearestpackage.json"type"field and the file extension (.mtsand.ctsforce 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 * fromdoes not re-export a default.
Related
- ESM and CJS interop
- Tutorial: Modules