How to fix Cannot use module augmentation with import assignment in TypeScript

TypeScriptINTERMEDIATEMEDIUMUpdated Dec 11, 2025· 110 views

This TypeScript error occurs when trying to augment modules using the older `import = require()` syntax. Module augmentation requires ES6-style `import` statements. The fix involves updating import syntax and ensuring proper module declaration merging.

Quick fix

Fixes Cannot use module augmentation with import assignment

// ❌ Wrong - CommonJS import assignment
import express = require('express');
declare module 'express' {
  interface Request {
    user?: User;
  }
}

// ✅ Correct - ES6 import syntax
import * as express from 'express';
declare module 'express' {
  interface Request {
    user?: User;
  }
}

Convert import assignment to ES6 import syntax
Check your tsconfig.json module setting
Create a separate declaration file for augmentations
Verify module has proper declarations

typescript — error

$// ❌ Wrong - CommonJS import assignment
import express = require('express');
declare module 'express' {
  interface Request {
    user?: User;
  }
}
// ✅ Correct - ES6 import syntax
import * as express from 'express';
declare module 'express' {
  interface Request {
    user?: User;
  }
}
Cannot use module augmentation with import assignment

What this error means

The error "Cannot use module augmentation with import assignment" happens when you try to use TypeScript's module augmentation feature with the CommonJS-style import assignment syntax (`import x = require('module')`). Module augmentation allows you to add new declarations to existing modules, but it only works with ES6 module syntax (`import` and `export`). This is because module augmentation relies on TypeScript's declaration merging system, which requires proper module scope and ES6 module semantics. When you use `import = require()`, you're telling TypeScript to treat the module as a CommonJS module with a default export, which doesn't support the same declaration merging capabilities as ES6 modules. TypeScript needs the ES6 module structure to properly track and merge declarations across files.

Typical symptoms

TypeScript compiler shows error: "Cannot use module augmentation with import assignment"
Module augmentation declarations are ignored or cause type errors
Attempts to extend third-party library types fail when using require() syntax
Autocomplete and IntelliSense don't show the augmented properties

Common causes

Using CommonJS import syntax (`import x = require("module")`) with module augmentation
Mixing ES6 and CommonJS module systems in the same augmentation file
Legacy TypeScript configuration that defaults to CommonJS modules
Copying module augmentation examples that assume ES6 modules without checking your import syntax

How to fix "Cannot use module augmentation with import assignment"

1Convert import assignment to ES6 import syntax

Change from CommonJS import assignment to ES6 import syntax:

typescript

// ❌ Wrong - CommonJS import assignment
import express = require('express');
declare module 'express' {
  interface Request {
    user?: User;
  }
}

// ✅ Correct - ES6 import syntax
import * as express from 'express';
declare module 'express' {
  interface Request {
    user?: User;
  }
}

Or if you need a default import:

typescript

// ✅ Also correct - ES6 default import
import express from 'express';
declare module 'express' {
  interface Request {
    user?: User;
  }
}

2Check your tsconfig.json module setting

Ensure your TypeScript configuration uses ES6 modules or higher:

json

{
  "compilerOptions": {
    "module": "ESNext",  // or "ES6", "ES2015", "ES2020", etc.
    // other options...
  }
}

Avoid using "module": "CommonJS" if you need module augmentation. If you must output CommonJS for Node.js compatibility, you can still write ES6 modules and let TypeScript transpile them:

json

{
  "compilerOptions": {
    "module": "CommonJS",     // Output format
    "moduleResolution": "node",
    "esModuleInterop": true,  // Important for compatibility
    "allowSyntheticDefaultImports": true
  }
}

With these settings, you can write ES6 imports and TypeScript will handle the conversion to CommonJS.

3Create a separate declaration file for augmentations

For cleaner code organization, create a separate .d.ts file for your module augmentations:

typescript

// types/express.d.ts
import * as express from 'express';

declare module 'express' {
  interface Request {
    user?: User;
    timestamp?: number;
  }

  interface Response {
    jsonSuccess(data: any): void;
  }
}

Then ensure this file is included in your TypeScript compilation. In tsconfig.json:

json

{
  "compilerOptions": {
    // ...
  },
  "include": [
    "src/**/*",
    "types/**/*.d.ts"  // Include your declaration files
  ]
}

This keeps your augmentations separate from implementation code and makes them easier to maintain.

4Verify module has proper declarations

Ensure the module you're augmenting actually has TypeScript declarations. Some modules might not have proper .d.ts files or might use different declaration styles.

Check if the module has its own types:

bash

# Check if types are included
npm info @types/express  # For DefinitelyTyped packages
npm info express types   # For packages with built-in types

If the module doesn't have TypeScript declarations, you might need to:
1. Install @types/module-name from DefinitelyTyped
2. Create your own ambient declarations
3. Use declare module without imports for ambient augmentation

For ambient augmentation (when you don't import the module):

typescript

// types/express.d.ts
declare module 'express' {
  interface Request {
    user?: User;
  }
}
// No import needed - this is an ambient declaration

5Test your augmentation works

Create a simple test to verify your module augmentation works:

typescript

// test-augmentation.ts
import express from 'express';

const app = express();

// This should work if augmentation is correct
app.use((req, res, next) => {
  req.user = { id: 1, name: 'Test' };  // Augmented property
  req.timestamp = Date.now();          // Another augmented property
  next();
});

// Also test augmented methods
app.get('/', (req, res) => {
  res.jsonSuccess({ message: 'Hello' });  // Augmented method
});

Compile and check for type errors:

bash

npx tsc --noEmit test-augmentation.ts

If there are no errors, your module augmentation is working correctly.

Advanced notes

## Understanding Module Augmentation vs Declaration Merging

Module augmentation is specifically for adding to *existing* module declarations. It differs from regular declaration merging in these ways:

1. Module augmentation uses declare module 'module-name' syntax and adds to modules from external packages or other files.

2. Declaration merging within the same file doesn't require declare module - TypeScript automatically merges interfaces, classes, etc.

## Common Pitfalls

1. Circular dependencies: If module A augments module B, and module B imports from module A, you might get confusing errors.

2. Global vs module augmentation: Use declare global for adding to global scope, declare module for specific modules.

3. Order matters: Augmentations must be in .d.ts files or files that don't produce runtime code. TypeScript processes them differently.

## Migration Strategy for Large Codebases

If you have a large codebase using import = require():
1. Start by converting only augmentation files to ES6 imports
2. Use esModuleInterop: true in tsconfig for compatibility
3. Gradually convert other files as needed
4. Consider using a codemod tool for bulk conversion

## TypeScript Version Considerations

- Older TypeScript versions (before 2.7) had more restrictions on module augmentation
- The esModuleInterop flag (introduced in TypeScript 2.7) helps bridge ES6 and CommonJS
- Always check the TypeScript version your project uses and consult the corresponding documentation

Frequently asked questions

What does "Cannot use module augmentation with import assignment" mean?: The error "Cannot use module augmentation with import assignment" happens when you try to use TypeScript's module augmentation feature with the CommonJS-style import assignment syntax (import x = require('module')). Module augmentation allows you to add new declarations to existing modules, but it only works with ES6 module syntax (import and export). This is because module augmentation relies on TypeScript's declaration merging system, which requires proper module scope and ES6 module semantics.
How do I fix "Cannot use module augmentation with import assignment"?: This TypeScript error occurs when trying to augment modules using the older import = require() syntax. Module augmentation requires ES6-style import statements. The fix involves updating import syntax and ensuring proper module declaration merging.
What causes "Cannot use module augmentation with import assignment"?: Using CommonJS import syntax (import x = require("module")) with module augmentation Mixing ES6 and CommonJS module systems in the same augmentation file Legacy TypeScript configuration that defaults to CommonJS modules
Is the "Cannot use module augmentation with import assignment" error serious?: It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading

📚TypeScript Official Documentation
📖
Typescriptlang.org - declaration-merging.html(Official Docs)
📖
Typescriptlang.org - modules.html(Official Docs)
💬
Stackoverflow.com - import-class-in-definition-file-d-ts(Stack Overflow)
🐙
Github.com - 17736(GitHub)
📖
Typescriptlang.org - modules.html#export--and-import--require(Official Docs)

How to fix Cannot use module augmentation with import assignment in TypeScript

Quick fix

What this error means

Typical symptoms

Common causes

How to fix "Cannot use module augmentation with import assignment"

Advanced notes

Frequently asked questions

Related errors

Official resources & further reading