TypeScript Reference ยท Modules and Declaration Files
TypeScript declare and ambient declarations
Reference for the TypeScript declare keyword: ambient variables, functions, classes, namespaces and modules that describe code that exists elsewhere at runtime.
The declare keyword tells the compiler that something exists at runtime without creating it. A declaration marked with declare is called an ambient declaration: it adds a name and a type to the compiler's picture of the program, but it emits no JavaScript at all. You use it to describe values that come from somewhere the compiler cannot see, such as a build-time constant injected by a bundler, a global set by a script tag, or a whole JavaScript library.
Because nothing is emitted, you take responsibility for the claim. If you declare a function that is never defined, TypeScript will happily compile calls to it and the program fails at runtime with a ReferenceError.
declare const BUILD_ID: string; declare function legacyLog(message: string): void; declare class Widget { constructor(name: string); render(): string; } declare namespace Analytics { function track(event: string): void; } declare module "virtual:config" { export const apiUrl: string; }
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
declare var | let | const name: Type; declare function name(params): ReturnType; declare class Name { /* member signatures, no bodies */ } declare enum Name { A, B } declare namespace Name { /* declarations */ } declare module "specifier" { /* declarations */ } declare module "*.svg"; // wildcard, everything typed as any declare global { /* only inside a module file */ }
| Form | Description |
|---|---|
declare const x: T |
A variable that already exists. No initializer is allowed. |
declare function f(): T |
A function signature without a body. Overloads are written as several signatures. |
declare class C { } |
Property and method signatures only. Constructors and methods have no bodies. |
declare namespace N { } |
An object with members, often used for libraries that attach to one global name. |
declare module "m" { } |
An ambient module: tells the compiler what import "m" gives you. |
declare module "*.ext" |
A pattern module for asset imports handled by a bundler. |
Edge cases: an ambient declaration cannot contain statements or initializers (error TS1039 for an initializer in an ambient context). Inside a .d.ts file or a declare namespace, top-level declare is implied for members, and in a .d.ts file the top-level items must still start with declare or export.
Usage notes
- Script versus module files. A file with no top-level
importorexportis a script, and itsdeclarestatements become true globals for the whole program. A file with an import or export is a module, sodeclare const xis local to that file. Usedeclare globalinside a module to add real globals. - Ambient module declarations only work in scripts.
declare module "name" { }in a file that is itself a module is treated as a module augmentation and fails if the module does not exist. Put ambient modules in a.d.tsscript file with no imports. - Shorthand ambient modules.
declare module "legacy-lib";with no body types everything imported from it asany. It is a quick way to silence a missing-types error, at the cost of safety. - Wildcards such as
declare module "*.css"let a bundler-resolved asset import type-check. - No emit, no checking of reality. Prefer generating types from real code, or writing a proper declaration file, over scattering
declarein application code. declareon class fields has a different meaning: it re-declares a property's type without emitting the field (seedeclarefields in the tutorial on classes).