Syntax
declare module "name" { }
declare function fn(): type;Examples
Declaring Types for an Untyped Module
Adding type information for a JavaScript library that has none.
// my-library.d.ts
declare module "my-untyped-library" {
export function doSomething(value: string): number;
export const version: string;
}
// Now "my-untyped-library" can be imported with full type checking,
// even though the actual library is plain, untyped JavaScriptDeclaring Global Variables
Describing a global variable injected by an external script, like an analytics library.
// globals.d.ts
declare const analytics: {
track: (event: string, data?: object) => void;
};
// Now "analytics" can be used anywhere in the project with type checking,
// even though it is never explicitly importedBest practices
- Check DefinitelyTyped (the @types/ npm scope) first before writing your own declaration file - many popular untyped libraries already have community-maintained types
- Ship a .d.ts file alongside your own published TypeScript library so consumers get full autocomplete and type checking without needing separate type packages
- Keep hand-written declaration files minimal and focused only on what you actually use from the untyped library, rather than fully typing its entire API upfront
- Use declare global carefully and sparingly for genuinely global values (like a script-injected variable) - overuse can make type origins confusing
At a glance
- Purpose
- Static types for JavaScript
- File extension
- .ts · .tsx
- Runs in
- Compiled to JavaScript
- Usually used with
- JavaScript and its ecosystem
Specifications & further reading
Related TypeScript documentation
tsconfig.json Basics
tsconfig.json configures how the TypeScript compiler behaves for a project - which files to include, what JavaScript version to target, and which type-checking rules to enforce. It is the first file the compiler looks for when run without explicit file arguments.Strict Mode Options
The "strict" tsconfig option is actually a shorthand that enables a whole family of individual strictness flags at once, including strictNullChecks (null/undefined are not assignable to other types by default), noImplicitAny (variables must have an inferable or explicit type), and strictFunctionTypes. Enabling strict mode is one of the highest-value changes for TypeScript's type safety.Interfaces
Interfaces in TypeScript define the structure of objects by specifying property names and their types. They act as contracts that ensure objects conform to specific shapes, providing type safety and better IDE support. Interfaces can be extended, merged, and used to type-check function parameters, return values, and object literals.Basic Types
TypeScript extends JavaScript with static types, letting the compiler catch type errors before code ever runs. Beyond the familiar string, number, and boolean, TypeScript adds any (disables checking entirely), unknown (a safer any that requires narrowing), void (a function returning nothing), and never (a value that can never occur, like a function that always throws).
tsconfig.json configures how the TypeScript compiler behaves for a project - which files to include, what JavaScript version to target, and which type-checking rules to enforce. It is the first file the compiler looks for when run without explicit file arguments.Strict Mode Options
The "strict" tsconfig option is actually a shorthand that enables a whole family of individual strictness flags at once, including strictNullChecks (null/undefined are not assignable to other types by default), noImplicitAny (variables must have an inferable or explicit type), and strictFunctionTypes. Enabling strict mode is one of the highest-value changes for TypeScript's type safety.Interfaces
Interfaces in TypeScript define the structure of objects by specifying property names and their types. They act as contracts that ensure objects conform to specific shapes, providing type safety and better IDE support. Interfaces can be extended, merged, and used to type-check function parameters, return values, and object literals.Basic Types
TypeScript extends JavaScript with static types, letting the compiler catch type errors before code ever runs. Beyond the familiar string, number, and boolean, TypeScript adds any (disables checking entirely), unknown (a safer any that requires narrowing), void (a function returning nothing), and never (a value that can never occur, like a function that always throws).