How to fix Module augmentation requires 'declare module' syntax in TypeScript

TypeScriptINTERMEDIATEMEDIUMUpdated Dec 11, 2025· 108 views

This TypeScript error occurs when you try to augment an existing module without using the proper `declare module` syntax. Module augmentation allows you to add new declarations to existing modules, but requires specific syntax to work correctly.

Quick fix

Fixes Module augmentation requires 'declare module' syntax

// Wrong:
module "some-module" {
  export interface ExtendedInterface {
    newProperty: string;
  }
}

// Correct:
declare module "some-module" {
  export interface ExtendedInterface {
    newProperty: string;
  }
}
  1. Add the declare keyword to your module augmentation
  2. Ensure you're in an ambient context or declaration file
  3. Verify the module path matches exactly
  4. Check if the module supports augmentation
typescript — error
// Wrong:
module "some-module" {
  export interface ExtendedInterface {
    newProperty: string;
  }
}
// Correct:
declare module "some-module" {
  export interface ExtendedInterface {
    newProperty: string;
  }
}
Module augmentation requires 'declare module' syntax

What this error means

Module augmentation in TypeScript is a feature that allows you to add new declarations (types, interfaces, functions, etc.) to existing modules. This is commonly used when you want to extend third-party library types or add custom functionality to built-in modules. The error occurs because TypeScript requires a specific syntax pattern for module augmentation: you must use `declare module "module-name"` followed by your additional declarations. Without this syntax, TypeScript cannot properly merge your new declarations with the existing module.

Typical symptoms

  • TypeScript compiler shows error: "Module augmentation requires 'declare module' syntax"
  • Attempts to extend or modify existing module types fail to compile
  • Auto-completion and type checking for augmented members doesn't work
  • Import statements for the augmented module show type errors

Common causes

  1. Missing `declare` keyword before the module declaration
  2. Using regular `module` syntax instead of `declare module`
  3. Attempting to augment a module in a regular TypeScript file without proper ambient context
  4. Incorrect module path or name in the declaration
  5. Trying to augment a module that doesn't exist or isn't in scope

How to fix "Module augmentation requires 'declare module' syntax"

1Add the declare keyword to your module augmentation

Change from regular module syntax to declare module syntax:

typescript
// Wrong:
module "some-module" {
  export interface ExtendedInterface {
    newProperty: string;
  }
}

// Correct:
declare module "some-module" {
  export interface ExtendedInterface {
    newProperty: string;
  }
}
2Ensure you're in an ambient context or declaration file

Module augmentations typically belong in .d.ts files or files with declare global. If you're augmenting in a regular .ts file, move the augmentation to a declaration file:

typescript
// Create a file: src/types/some-module.d.ts
declare module "some-module" {
  // Your augmentations here
}

Or use declare global for global augmentations:

typescript
declare global {
  namespace SomeNamespace {
    // Your augmentations here
  }
}
3Verify the module path matches exactly

The module path in your declaration must match how the module is imported. Check for exact string matching:

typescript
// If you import like this:
import * as lib from "some-library";

// Your augmentation should be:
declare module "some-library" {
  // ...
}

// Not:
declare module "some-library/dist/index" {
  // ...
}

Use the exact same module specifier that appears in your import statements.

4Check if the module supports augmentation

Some modules may not support augmentation if they don't have existing declarations or use specific module systems. Verify the module has existing declarations you can extend:

1. Check if the module has type definitions (look for @types/ package or .d.ts files)
2. Ensure you're not trying to augment a module that uses export = syntax (CommonJS default exports)
3. For global augmentations, ensure you're not conflicting with existing declarations

5Use proper merging syntax for different declaration types

Different declaration types require different merging approaches:

typescript
// Adding to an existing interface:
declare module "some-module" {
  interface ExistingInterface {
    newMethod(): void;
  }
}

// Adding new exports:
declare module "some-module" {
  export function newFunction(): string;
}

// Adding to a namespace:
declare module "some-module" {
  namespace SubNamespace {
    interface NewInterface {
      property: boolean;
    }
  }
}

Make sure your augmentation syntax matches the existing module structure.

6Test your augmentation works correctly

After fixing the syntax, test that your augmentation works:

1. Create a test file that imports the augmented module
2. Verify TypeScript recognizes your new declarations
3. Check that auto-completion works for the augmented members
4. Ensure no type errors appear when using the augmented functionality

Example test:

typescript
import * as lib from "some-module";

// This should now work without type errors
const result = lib.newFunction();
const obj: lib.ExtendedInterface = {
  existingProperty: "value",
  newProperty: "new value" // This property comes from your augmentation
};

Advanced notes

Module augmentation follows TypeScript's declaration merging rules. When you use declare module, TypeScript merges your new declarations with the existing module declarations. This is different from module declaration files (.d.ts) that describe entire modules - augmentations only add to existing declarations. For complex augmentations, consider creating a separate augmentation package or using conditional types. Be cautious when augmenting widely-used libraries as your augmentations affect all code that imports that module.

Frequently asked questions

What does "Module augmentation requires 'declare module' syntax" mean?
) to existing modules. This is commonly used when you want to extend third-party library types or add custom functionality to built-in modules. The error occurs because TypeScript requires a specific syntax pattern for module augmentation: you must use declare module "module-name" followed by your additional declarations.
How do I fix "Module augmentation requires 'declare module' syntax"?
This TypeScript error occurs when you try to augment an existing module without using the proper declare module syntax. Module augmentation allows you to add new declarations to existing modules, but requires specific syntax to work correctly.
What causes "Module augmentation requires 'declare module' syntax"?
Missing declare keyword before the module declaration Using regular module syntax instead of declare module Attempting to augment a module in a regular TypeScript file without proper ambient context
Is the "Module augmentation requires 'declare module' syntax" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading