How to fix Cannot augment module 'X' outside of its own definition in TypeScript

The simplest fix is to add an import statement at the beginning of your file. This ensures TypeScript treats your file as a module rather than a global script:

// ❌ Wrong - no imports, treated as global script
declare module 'my-library' {
  export interface MyType {
    customProp: string;
  }
}

// ✅ Correct - import makes it a module
import 'my-library'; // Import the module first

declare module 'my-library' {
  export interface MyType {
    customProp: string;
  }
}

The import statement doesn't need to import anything specific—it just signals to TypeScript that this is a module file, enabling module augmentation syntax.

If importing the module doesn't make sense for your use case, add an empty export to establish module context:

// ✅ Correct - export makes it a module
declare module 'jquery' {
  interface JQuery {
    customMethod(): void;
  }
}

export {}; // Makes this file a module

This empty export statement tells TypeScript "treat this as a module" without actually exporting anything. It's a common pattern in .d.ts files where you only want to augment types.

Ensure your augmentation file is included in your tsconfig.json:

{
  "compilerOptions": {
    "declaration": true,
    "declarationDir": "./types"
  },
  "include": [
    "src/**/*",
    "types/**/*.d.ts"
  ]
}

If your augmentation file is in a subdirectory, make sure it's explicitly included in the "include" array. TypeScript must be able to find and process the file.

Verify the module name in your declare module statement matches the actual module package name:

// If the package is named 'lodash'
declare module 'lodash' {
  export interface LoDashStatic {
    customUtility(): string;
  }
}

// NOT 'lodash/lib' or '_' or other variations
// Use the exact package name from node_modules

Check your package.json or node_modules to confirm the exact module name. Using incorrect module names will cause augmentation to fail.

If you're actually trying to augment global types (not module-specific types), use declare global syntax instead:

// ❌ Wrong approach for global augmentation
declare module 'global' {
  interface Window {
    customProp: string;
  }
}

// ✅ Correct approach for global types
declare global {
  interface Window {
    customProp: string;
  }
}

export {}; // Make it a module

declare global applies to the global namespace (window, process, etc.), while declare module augments specific named modules.

Create the augmentation in a .d.ts file with proper module context:

// ✅ Good structure for types/express-augmentation.d.ts
import 'express'; // or export {}

declare module 'express' {
  interface Request {
    userId?: string;
  }
}

Include it in tsconfig.json:

{
  "include": [
    "src/**/*",
    "types/**/*.d.ts"
  ]
}

This ensures the file is recognized as a module and properly processed by TypeScript.

If you're using legacy triple-slash directives, ensure you still have module context:

// ❌ Triple-slash without module context
/// <reference path="./my-types.d.ts" />
declare module 'my-library' {
  export interface MyType {}
}

// ✅ With proper module context
/// <reference path="./my-types.d.ts" />
import 'my-library';

declare module 'my-library' {
  export interface MyType {}
}

Triple-slash directives don't establish module context by themselves. You still need an import or export statement.