How to fix Cannot use namespace as a module in TypeScript

TypeScriptINTERMEDIATEMEDIUMUpdated Dec 8, 2025· 104 views

This error occurs when you try to import a namespace declaration as if it were an ES module or CommonJS module. The issue arises from mixing TypeScript namespace syntax with modern module import/export patterns.

Quick fix

Fixes Cannot use namespace as a module

namespace Utils {
  export function doSomething() { }
}
  1. Check if the file uses namespace declarations
  2. Convert the namespace to ES module exports
  3. Update your import statements
  4. Replace triple-slash references with import statements
typescript — error
namespace Utils {
  export function doSomething() { }
}
Cannot use namespace as a module

What this error means

This error happens when TypeScript encounters a mismatch between how code is exported and how it's being imported. TypeScript has two distinct code organization mechanisms: **Namespaces** are a TypeScript-specific feature that pre-dates JavaScript modules. They organize code into named objects but don't create actual module boundaries. **ES Modules (import/export)** and **CommonJS (require/module.exports)** are the standard module systems that create separate scopes and clear dependencies. When you try to import a namespace using modern module syntax—like `import * as namespace from './file'` or `import namespace from './file'`—TypeScript complains because namespaces aren't actual module exports. They're just scoped objects within the same global file scope.

Typical symptoms

  • TypeScript compiler throws the error: 'Cannot use namespace as a module'
  • Import statements fail for files using namespace declarations
  • Using 'import * as' syntax with namespace files causes errors
  • Default imports from namespace-only files don't work
  • Code works fine when using triple-slash references but fails with import statements

Common causes

  1. Attempting to import a file that only exports a namespace, not a module export
  2. Mixing TypeScript namespace syntax with ES6 module import/export patterns
  3. Using modern module syntax to import from code that relies on the old 'module augmentation' pattern
  4. Files using only namespace declarations without exporting them as modules
  5. Misconfigured tsconfig.json module settings that don't align with the actual code structure

How to fix "Cannot use namespace as a module"

1Check if the file uses namespace declarations

Look at the file you're trying to import. If it contains code like:

typescript
namespace Utils {
  export function doSomething() { }
}

This is the problem. The namespace is declared but not exported as a module.

2Convert the namespace to ES module exports

Replace the namespace syntax with ES module exports:

Before:

typescript
namespace Utils {
  export function doSomething() { }
  export const value = 42;
}

After:

typescript
export function doSomething() { }
export const value = 42;

This converts the namespace into a proper ES module.

3Update your import statements

Change from namespace-style imports to modern ES module syntax:

Before (doesn't work):

typescript
import * as Utils from './utils';
Utils.doSomething();

After (works):

typescript
import { doSomething } from './utils';
doSomething();

Or if you prefer namespace-like behavior:

typescript
import * as Utils from './utils';
Utils.doSomething();
4Replace triple-slash references with import statements

If you're using the old TypeScript triple-slash syntax:

Before:

typescript
/// <reference path="./utils.ts" />

After:

typescript
import { doSomething } from './utils';

Triple-slash references are an old pattern and don't work well with modern module systems.

5Verify tsconfig.json module settings

Ensure your tsconfig.json is configured correctly for your module system:

For ES modules (recommended):

json
{
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "bundler"
  }
}

For CommonJS:

json
{
  "compilerOptions": {
    "module": "commonjs",
    "moduleResolution": "node"
  }
}

Make sure the module setting matches your actual import/export syntax.

Advanced notes

### Legacy Code Migration

If you're working with legacy TypeScript code that heavily uses namespaces (common in older Angular projects or .d.ts definition files), consider creating a "shim" file that exposes the namespace as a proper module export. This allows you to migrate gradually without rewriting all the old code at once.

### Namespace Merging

TypeScript supports namespace merging, where you can split a namespace across multiple files. This feature doesn't work with ES modules, which is another reason to migrate away from namespaces.

### Definition Files (.d.ts)

The namespaces pattern is still common in TypeScript definition files. If you're importing from a .d.ts file that uses namespaces, the library author needs to update it or provide separate type definitions.

### Why TypeScript Recommends Modules

ES modules have better tooling support, cleaner dependency graphs, and align with JavaScript's evolution. They're now the standard in Node.js and browsers.

Frequently asked questions

What does "Cannot use namespace as a module" mean?
This error happens when TypeScript encounters a mismatch between how code is exported and how it's being imported. TypeScript has two distinct code organization mechanisms: Namespaces are a TypeScript-specific feature that pre-dates JavaScript modules. They organize code into named objects but don't create actual module boundaries.
How do I fix "Cannot use namespace as a module"?
This error occurs when you try to import a namespace declaration as if it were an ES module or CommonJS module. The issue arises from mixing TypeScript namespace syntax with modern module import/export patterns.
What causes "Cannot use namespace as a module"?
Attempting to import a file that only exports a namespace, not a module export Mixing TypeScript namespace syntax with ES6 module import/export patterns Using modern module syntax to import from code that relies on the old 'module augmentation' pattern
Is the "Cannot use namespace as a module" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading