Modules & Resolution

When a JavaScript package ships no types, the community publishes them separately as @types/<name>, built from the DefinitelyTyped repository. TypeScript picks them up automatically from node_modules/@types — you never import them. A package that ships its own declarations needs no @types at all.

module.exports = x replaces the module object — the module is x. export default x adds one named export called default to a namespace object holding every other export too. So require() on an ES module hands you { default: x }, and default-importing CommonJS works only through an interop helper.

module decides the module syntax tsc emits — commonjs rewrites import/export into require and exports.x, while esnext leaves them as ES modules. It never changes what you author. Under node16 the format is chosen per file, from the nearest package.json type field.

namespace was TypeScript's pre-ESM way to group code: it emits an IIFE that hangs properties off a global object, and same-named blocks merge across files. ES modules replaced it because a module is scoped to its file, its imports are statically analysable, and bundlers can tree-shake it. Keep namespace for .d.ts files only.

allowSyntheticDefaultImports is type-only: it silences the no default export error so import fs from 'fs' type-checks, and emits nothing. esModuleInterop changes the emit — it wraps CommonJS requires in __importDefault so the import really receives module.exports — and it implies the first flag. Enable only the type-only one and the code compiles, then fails at run time.

tsc sees the whole program, so it knows a binding is used only in type position and elides the import. A single-file transpiler — esbuild, SWC, Babel — sees one file and no cross-file types, so it cannot tell whether import { User } names a type or a value. import type puts the answer in the syntax.

node10 is the legacy CommonJS algorithm: walk up node_modules, guess the extension, ignore the exports map. node16/nodenext model what Node really does — honour exports, decide CommonJS or ESM per file, require an explicit extension on relative ESM imports. bundler honours exports but keeps extensionless imports legal.

ESM import/export are static declarations: what a module takes and gives is known from the syntax alone, so a bundler builds the graph without running anything and drops unreferenced exports. require() is an ordinary call and module.exports is mutable, so nothing can be proven unused and it all stays.

Module augmentation: declare module 'lib' { ... } inside a file that is itself a module — it must have a top-level import or export. Your interfaces then merge with the library's own; merging can add members, never retype an existing one. Without that import or export the file is a script, and the block replaces the library's types.

With a literal specifier import('./m.js') is typed — the compiler resolves the file and infers Promise<typeof import('./m.js')>. With a computed specifier it can resolve nothing, so the result is any and everything after it is unchecked. Await into unknown, narrow with a type guard that inspects the shape at run time, and throw when it fails.

Types resolve lazily, so a circular type reference is legal and the check stays silent. The value cycle in the emit is invisible to it: the module evaluated second gets the other's empty exports, so entity_1.Entity is undefined at extends. Erase the type-only edges with import type, and move shared values to a third module.

It makes tsc reject anything a single-file transpiler cannot compile correctly. esbuild, SWC and Babel see one file at a time with no cross-file types, so a re-exported type must be written export type { T } and a const enum cannot be inlined across files. It is a compatibility contract.

paths is a compile-time alias only. It tells the checker where @app/x resolves, but tsc leaves the specifier untouched in the emit — Node then sees a literal @app/x and throws MODULE_NOT_FOUND. You need a matching run-time resolver: a bundler alias, Node subpath imports, or a loader such as tsconfig-paths.