Course contentsShow
← TypeScript
Lesson 1167 of 1,79627. Declaration FilesFree lesson

Placement and Scope of Augmentation Files

Understand where to place .d.ts augmentation files and how TypeScript discovers and applies them.

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:

  1. Inside your rootDir or source folders — If your tsconfig.json includes files from src/, place augmentations there
  2. Matched by include patterns — The file must match your glob patterns (e.g., src/**/*.d.ts)
  3. 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:

  1. It merges your declare module additions with the original module's types
  2. Every file that imports that module sees the augmented version
  3. 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.