TypeScript Reference ยท Modules and Declaration Files
Generating TypeScript declaration files
Reference for generating .d.ts files with the TypeScript declaration, declarationMap, emitDeclarationOnly and isolatedDeclarations compiler options.
If you publish a library written in TypeScript, consumers need its types. You do not write those by hand: the compiler produces a .d.ts file for every source file when the declaration option is on. The declaration keeps the exported shape (names, parameter types, return types, classes with member signatures) and drops everything else, including function bodies and non-exported code.
Where you leave out a type annotation, the compiler writes the inferred type into the declaration. That is convenient but can produce very large or surprisingly specific types, which is why libraries often annotate their exported API explicitly.
{ "compilerOptions": { "declaration": true, "declarationMap": true, "outDir": "dist" } }
Try it
The runner compiles one file and does not emit declarations, so these examples show the types a declaration would contain by asking the compiler for them.
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
tsc --declaration --emitDeclarationOnly --outDir types tsc -p . --declaration --declarationMap
| Option | Description |
|---|---|
declaration |
Emit a .d.ts file next to each emitted .js file. Implied by composite. |
declarationDir |
Put .d.ts files in a separate folder from the JavaScript. |
declarationMap |
Emit .d.ts.map files so "Go to definition" jumps to the .ts source instead of the .d.ts. |
emitDeclarationOnly |
Emit only declarations, no JavaScript. Used when another tool (esbuild, SWC, Babel) compiles the code. |
isolatedDeclarations |
Require exported APIs to be annotated well enough that a declaration can be produced from one file alone, without type inference across files. |
stripInternal |
Omit declarations whose JSDoc contains @internal. |
Edge cases: with declaration on, TS4xxx errors appear when an exported value's type refers to something the declaration cannot name (a non-exported type, or a type from a module that is not reachable). Fix them by exporting the type or adding an explicit annotation.
Usage notes
- Annotate the public API. Explicit return types make the output stable, faster to generate and easier to read, and they protect you from changing a public type by accident.
isolatedDeclarations(TypeScript 5.5 and later) reports an error wherever an export needs inference. It lets fast tools generate.d.tswithout a full type check, and is helpful in large monorepos.- Package wiring. Point
types(or thetypesexport condition) at the generated file (@types packages). - Declaration maps need the
.tssources to ship (or be resolvable) next to the maps; otherwise the map points to files users do not have. - Do not hand-edit generated files. If the output is wrong, change the source types.
- A
.jsproject can also generate declarations withallowJsandcheckJsplus JSDoc annotations. - Verify the result. Compile a tiny consumer project against the built package, or use a tool that checks the published types, before releasing.