Placement and Scope of Augmentation Files
You'll learn: Where to place .d.ts augmentation files so TypeScript finds them and how the compiler applies those augmentations to your codebase.
The Discovery Problem
When you augment a third-party module with declare module "some-library", you're creating a file that adds type information. But where does this file go? And how does TypeScript know to include it?
Unlike regular source files, augmentation files don't get imported explicitly. Instead, TypeScript discovers them based on your project configuration and applies them globally within the compilation context.
File Placement Rules
Augmentation files must be in scope for your compilation. This means:
- Inside your
rootDiror source folders — If yourtsconfig.jsonincludes files fromsrc/, place augmentations there - Matched by
includepatterns — The file must match your glob patterns (e.g.,src/**/*.d.ts) - Not in
node_modules— Your augmentations live in your code, not in the library's folder
Common pattern: Many projects create a types/ or typings/ folder at the root and add it to include:
{
"include": ["src/**/*", "types/**/*"]
}
Then create files like types/express.d.ts or types/global.d.ts.
Module vs Global Scope
The scope of an augmentation depends on one critical detail: whether the .d.ts file has import or export statements.
- If the file has
export {}or any import/export, it's a module. Augmentations inside apply globally, but you must ensure TypeScript processes this file. - If the file has no imports/exports, it's treated as a script in the global scope. All declarations are automatically global.
For augmentations, you typically want module scope (add export {} at the bottom) so your augmentation doesn't accidentally pollute unrelated code.
How TypeScript Applies Augmentations
Once TypeScript discovers your augmentation file during compilation:
- It merges your
declare moduleadditions with the original module's types - Every file that imports that module sees the augmented version
- The augmentation affects the entire project, not just files that "see" the augmentation file
This is why augmentations are powerful but need careful placement—they're project-wide changes.
Key Takeaway:
Place augmentation .d.ts files where tsconfig.json will include them, typically in a types/ folder, and use export {} to keep them as modules while making their augmentations globally available across your project.