Ship public type contracts alongside compiled JavaScript.
Library publishing
TypeScript · Const
declaration
The declaration compiler option generates .d.ts files that describe a project’s external API. Consumers and editor tools can use them for type checking and IntelliSense without inspecting implementation code.
How it works
The declaration compiler option asks TypeScript to generate a .d.ts file for each project source file. These files describe the module’s externally visible types, support editor tooling and checking by consumers, and contain no executable implementation.
Syntax
{"compilerOptions":{"declaration":true}}Parameters
| Name | Type | Description |
|---|---|---|
declaration | boolean | Boolean compiler option. When true, generates .d.ts files for TypeScript or JavaScript project inputs. |
Returns
Generates .d.ts declaration files describing each input module’s external API; it does not return a runtime value.
Key points
- Enabling the option generates a declaration file for every TypeScript or JavaScript source file in the project.
- Each generated file records the module’s external, consumer-facing type contract.
- Declaration output improves IntelliSense and gives consumers accurate types even when implementation code is unavailable.
- The configuration form is
declaration: truein compiler options; the command-line equivalent is--declaration.
Common mistakes
- For JavaScript projects, consider
emitDeclarationOnlyoroutDirso declaration generation does not overwrite JavaScript output.
Example: Emit a declaration for an exported function
export const greet = (name: string): string => `Hello, ${name}`;
Compile with tsc --declaration to emit a JavaScript file and a corresponding declaration file describing the exported API.
When to use it
Let dependent projects type-check against stable generated API descriptions.
Large monorepos
Generate declarations for JavaScript sources while preserving or separately controlling JavaScript output.
JavaScript migration
Interview questions
QWhat does the declaration compiler option do?
Set declaration to true in the compiler options, then TypeScript emits a .d.ts file for each TypeScript or JavaScript input file. The declarations describe the module’s external API and enable accurate checking and editor support for consumers.
Follow-up: How can a JavaScript project avoid replacing its JavaScript output? Use emitDeclarationOnly or configure outDir when generating declarations.
QWhy are declaration files useful in a large codebase?
A .d.ts file contains type information rather than executable implementation. TypeScript and editor tools use it to understand a library’s exported API without analyzing the library’s source implementation.
Follow-up: What should a declaration contain for a module? The types of the things it exports—the public API—rather than private implementation details.
QHow do you generate declaration files?
Run the compiler with --declaration, or set declaration: true in a project configuration. For each source file, TypeScript can then emit a matching declaration file alongside the JavaScript output.
Follow-up: What does emitDeclarationOnly change? It emits declaration files without emitting JavaScript, which is useful when JavaScript is produced by another tool.
Related
emitDeclarationOnlyoutDir.d.ts filesTypeScript compilerexternal API