TypeScript Reference ยท Modules and Declaration Files
TypeScript module augmentation
Reference for TypeScript module augmentation: reopen an existing module with declare module to add members to its interfaces, without editing the library.
Module augmentation lets you add to the types that a module exports without touching its source. In a file that is itself a module, you write declare module "specifier" { ... } with the same specifier the code imports. TypeScript treats the block as additional declarations merged into that module's own, so interfaces gain members and namespaces gain exports.
It is the standard way to teach a library about your plugins: a web framework's Request gets a user property, a test library gets a custom matcher, or process.env gets known keys. As with global augmentation, only the types change; you must still provide the runtime behavior.
import "node:fs"; declare module "node:fs" { interface Stats { describe(): 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
import "library"; // makes this file a module declare module "library" { interface Existing { extra: string } // merges into Existing export function newHelper(): void; // see the limits below } declare module "./local-file.js" { // relative specifiers are resolved from this file interface Settings { theme: "light" | "dark" } }
| Part | Description |
|---|---|
| Module specifier | Must resolve to a real module, the same way an import would. An unresolvable name is an error (TS2664). |
interface / namespace / class members |
Merge with existing declarations of the same name. |
| New top-level declarations | Allowed for new names, but you cannot add a new default export. |
Edge cases: you cannot replace or change existing members, only add. The file containing the block must itself be a module (at least one import or export), otherwise the block is an ambient module declaration, a different feature (see declare and ambient modules).
Usage notes
- Interfaces merge, type aliases do not. If the library declares
type Options = {...}, you cannot extend it; only interfaces, namespaces and enums merge. This is a good reason for libraries to export interfaces for extension points. - Class members are added by augmenting the class's interface of the same name (declaration merging between a class and an interface).
- It is global. The augmentation applies to the whole program once the file is included by
tsconfig.json, not just where it is written. - Include the file. If the augmentation lives in a file that is never part of the compilation, the extra members silently disappear. Put it under
includeintsconfig.json. - Check the library's own docs for the supported extension interface; many libraries (Express, Vue, Pinia, Vitest) document exactly which interface to augment.
- Types only. Assigning to
Class.prototypeor registering a plugin is what makes the member real.