Modules and declaration files

The file decides this, not tsconfig.json

The module option in tsconfig.json chooses the output format: esnext, commonjs, and so on. It does not decide whether a given file is a module. Only the file itself does that, by having a top-level import or export.

This matters most in .d.ts files, where it is easy to have neither. The same declare module block means two different things depending on which kind of file it sits in. §04 shows both.

Why static imports allow tree shaking

Because ESM import and export declarations must appear at the top level and their names are fixed, a bundler can work out which exports are used without running the program. Unused exports can then be left out of the output. That removal is called tree shaking.

require gives no such guarantee. It can sit inside an if, take a computed path, and return a different object each time. So a bundler generally has to keep the whole module.

export default and module.exports = are not the same thing

export default x creates one named export called default on an ES module. module.exports = x replaces the whole exports object of a CommonJS module. So a CommonJS module that assigns a function to module.exports has no default property for an ESM default import to read.

esModuleInterop is what bridges the two. It makes the compiler emit a small helper, __importDefault, which wraps a non-ESM export as { default: … } so the default import finds something. It also changes the type rules to match: without the flag, the default import is rejected outright.

Why you should mark type-only imports yourself

tsc sees the whole project, so it can work out on its own that Order is only a type and that the import can go. Vite, esbuild, and SWC transpile one file at a time. They cannot tell whether Order is a value or a type, and dropping the wrong import breaks the program at run time.

verbatimModuleSyntax (TypeScript 5.0) removes the guesswork: an import or export statement is emitted exactly as written, and a type imported without type is reported as ts(1484), "'Order' is a type and must be imported using a type-only import when 'verbatimModuleSyntax' is enabled." Re-exporting a type without export type gives the matching ts(1205).

There is a second reason, independent of tooling. A .js module can run code when it is loaded. A type-only import that survives into the output would load that module at run time for no benefit at all.

Circular imports are allowed, but a binding can be unset

Two ES modules may import each other. The specification allows it and the type checker reports nothing. What can still fail is the order: the modules run one after another, and if one reads a binding from the other before that module has reached the line that initialises it, the read throws ReferenceError.

Reading such a binding later — inside a function that is called after both modules have finished — is fine. The practical fix is to move the shared declaration into a third module that both import.

A declaration file cannot hold code

Everything in a .d.ts is an ambient declaration: a statement about something that exists elsewhere. Write a function body in one and you get error TS1183: An implementation cannot be declared in ambient contexts.

This is also why a .d.ts can describe a library that was never written in TypeScript. Describing a shape does not require touching the code.

The built-ins come from declaration files too

Where do the types for document, fetch, and Promise come from? The same place: .d.ts files. TypeScript ships a set of them. lib.dom.d.ts covers what the browser provides. Files such as lib.es2022.d.ts cover the JavaScript language itself. The lib option in tsconfig.json decides which ones are loaded.

In your editor, hold Ctrl or Cmd and click fetch. You land inside lib.dom.d.ts. Seeing it once is enough to make "built-in" stop feeling like a special case.

@types versions drift away from the library

Declarations in DefinitelyTyped are written by volunteers, so they can lag behind the library. Install a new major version of lodash while @types/lodash stays on the old one, and the types will describe behavior the library no longer has.

The convention is that the major and minor version of the @types package match the library. When a type looks wrong, compare those two version numbers first.

Resolution is a compile-time answer only

Finding a declaration file is module resolution, and moduleResolution selects the rules. node10 is the legacy Node algorithm: it walks up through node_modules, reads main and types, and ignores the exports field. node16 and nodenext follow what modern Node actually does: they honour exports, and in an ESM file they require the file extension in a relative import (leaving it out is ts(2835)). bundler matches what bundlers do: it honours exports but allows extensionless imports. None of these is correct everywhere. The right one is the one that matches whatever loads your code.

paths is narrower still. It is a compile-time mapping only. tsc does not rewrite the specifier, so import { TAX } from "@/tax" is still written that way in the output. Node then reports Cannot find package '@/tax'. Next.js, Vite, and webpack read these paths or have an equivalent alias option, which is why aliases work in an app and break the first time you run plain node on the output.

What skipLibCheck actually skips

skipLibCheck: true skips type checking inside .d.ts files, including the checks between them. Your own calls into those libraries are still checked in full.

It buys faster compilation and avoids errors you cannot fix, such as two @types packages declaring the same global with different types. The cost is that a genuine mistake inside a declaration file goes unreported.

Two jobs, one keyword: declaring a module vs augmenting one

declare module "x" in a script file — no top-level import or export — is an ambient module declaration. It says: the module "x" exists and here are its types. Use it for a package that has no types of its own.

The same block in a module file is a module augmentation. It says: the module "x" already has types, add these to them. Use it to extend a typed library, for example to add a field to a theme interface.

Getting this backwards produces a confusing error. Put export {} in a file whose declare module was meant to describe an untyped package, and the compiler treats it as an augmentation with nothing to augment: error TS2665: Invalid module name in augmentation. Module 'boba-sdk' resolves to an untyped module …, which cannot be augmented.

A declaration is a claim, and claims can be wrong

However carefully you write it, declare does not add anything to the run time. Declare gtag but never load the analytics script, and the program still fails with gtag is not defined.

When the type check passes and the program fails immediately, check three things: was the script actually loaded, does the package really export that name, and is the name spelled correctly?

A note on namespace

You will see declare namespace in older declaration files. namespace predates ES modules: it was TypeScript's own way of grouping names before the language had modules of its own. It still works, and it is still the natural way to describe a library that puts everything on one global object.

For new code, modules are the recommendation. A module already gives you a private scope and an explicit list of exports, which is what namespace was for.

How much is enough?

Describe what you use. The any-shaped hole gets smaller each time you come back to it, and nobody expects a complete declaration on the first pass.

If you do end up writing a complete and reliable one, send it to DefinitelyTyped. Once @types/boba-sdk is published, the next person to use this library does not have to do any of this.

A declaration file is not a replacement for the module

A .d.ts contains no code. If a project has helpers.d.ts but no helpers.js, then import { helper } from "./helpers" passes the type check and fails at run time with Cannot find module.

The compiler reads declarations. The run time looks for real files. Both have to exist.