Describe external variables
A browser global, injected configuration object, or host-provided constant is available at runtime but absent from the current TypeScript source.
TypeScript · Const
declare
The declare keyword describes a runtime-provided symbol to TypeScript without implementing it in the current source. It is commonly used in .d.ts files and for external variables, functions, classes, namespaces, and modules.
How it works
The declare modifier tells TypeScript that a value, function, class, namespace, or module exists without providing its implementation. It is used to describe runtime-provided APIs, commonly in declaration files, and contributes type information rather than JavaScript behavior.
Syntax
declare const name: Type;
declare let name: Type;
declare var name: Type;
declare function name(...parameters): ReturnType;
declare class Name { ... }
declare namespace Name { ... }
declare module "module-name";Key points
- Use declare when a variable exists outside the current source but needs a compile-time type.
- declare namespace models APIs reached through dotted names, grouping related types and values under one namespace.
- declare class describes an externally implemented class, including its constructor, properties, and methods.
- declare function records an external function signature, including accepted arguments and its return type.
- Choose declare const when the external variable cannot be reassigned; declare let is available for block-scoped mutable bindings.
Common mistakes
- A declaration does not create the value at runtime; the environment must provide it, or the program can fail when it is used.
Example: Typing an externally supplied constant
declare const config: { apiUrl: string };
export function request(path: string) {
return fetch(`${config.apiUrl}${path}`);
}The declaration supplies a compile-time type for a value provided by another script or runtime environment; it emits no initialization for config.
When to use it
Type an external function
A JavaScript library has no bundled TypeScript types and its callable API must be exposed to a TypeScript consumer.
Model a JavaScript class
An existing JavaScript constructor and its instance members need to be represented for consumers without rewriting the implementation.
Add module declarations
A package or module lacks type declarations and needs an ambient module declaration so imports can be checked.
Interview questions
QWhat does the declare keyword do?
declare tells the compiler that a symbol exists elsewhere, so TypeScript can type-check uses without an implementation in the current source. It is useful for describing APIs supplied by JavaScript libraries or the runtime.
Follow-up: What happens at runtime? Nothing is created by declare; the external code must define the symbol before use.
QHow do declare const, declare let, and declare var differ?
Use declare const for a read-only externally supplied variable, declare let for a block-scoped variable, and declare var for a variable with var-style semantics. The declaration gives TypeScript the variable's type but not its value.
Follow-up: How would you describe an external function? Use declare function with its parameter and return types, such as declare function greet(message: string): void.
QWhy are declare statements common in .d.ts files?
A declaration file describes types or values without implementations and conventionally uses the .d.ts extension. Such files are consumed for type-checking and do not produce JavaScript output.
Follow-up: How can an untyped module be acknowledged quickly? Add an empty declare module "module-name"; declaration, though this provides the module with an any-like fallback.
Related
declare vardeclare letdeclare functiondeclare classdeclare namespacedeclaration files.d.tsdeclare module