How to fix Namespace must be imported or aliased using 'import as' in TypeScript

What this error means

This error occurs when you attempt to use a TypeScript namespace without properly importing or referencing it. TypeScript namespaces are a way to organize code and prevent naming collisions, but they require specific syntax to access their contents. When you define a namespace like `namespace MyNamespace { export const value = 1; }`, you cannot directly reference `value` without either: 1. Importing the namespace with `import as` syntax 2. Using the namespace qualifier `MyNamespace.value` The error message "Namespace must be imported or aliased using 'import as'" is TypeScript's way of telling you that you're trying to use something from a namespace without following the proper access rules. This is different from ES6 modules, which use different import/export syntax.

Typical symptoms

• TypeScript compilation fails with error TS2693
• Error message: 'Namespace must be imported or aliased using 'import as''
• Code works at runtime but fails during TypeScript type checking
• IDE shows red squiggly lines under namespace references
• Build process fails but JavaScript execution might work
• Error occurs when migrating from JavaScript to TypeScript

Common causes

1. Directly referencing namespace members without proper import syntax
2. Mixing namespace syntax with ES6 module imports incorrectly
3. Missing 'import as' statement for namespace imports
4. Using triple-slash references (/// <reference>) without proper configuration
5. Trying to use global namespace declarations in module files
6. Incorrect tsconfig.json configuration for module resolution

How to fix "Namespace must be imported or aliased using 'import as'"

// Incorrect - will cause error
import { SomeFunction } from './my-namespace';

// Correct - use 'import as' for namespaces
import * as MyNamespace from './my-namespace';
// Then access with MyNamespace.SomeFunction

// Alternative: import specific members with alias
import { SomeFunction as MyFunction } from './my-namespace';

namespace MyNamespace {
  export const value = 42;
}

// Incorrect - direct reference
const x = value; // Error!

// Correct - use namespace qualifier
const x = MyNamespace.value;

// Also correct - import with 'import as' even in same file
import MyAlias = MyNamespace;
const y = MyAlias.value;

{
  "compilerOptions": {
    "module": "commonjs", // or "amd", "system", "umd"
    "moduleResolution": "node",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true
  }
}

// Old namespace style
namespace Utilities {
  export function helper() { /* ... */ }
}

// New ES6 module style
// utilities.ts
export function helper() { /* ... */ }

// consumer.ts
import { helper } from './utilities';

/// <reference path="./my-globals.d.ts" />

// Now you can use the namespace
const x = MyGlobalNamespace.someValue;

// my-globals.d.ts
declare namespace MyGlobalNamespace {
  export const someValue: string;
}

// Check file extensions
import * as MyNamespace from './my-namespace.ts'; // .ts extension
import * as MyNamespace from './my-namespace.js'; // .js extension in output

// Use path mapping in tsconfig.json for complex structures
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@namespaces/*": ["src/namespaces/*"]
    }
  }
}

// Then import
import * as MyNamespace from '@namespaces/my-namespace';

Advanced notes

// file1.ts
namespace MyLib {
  export function func1() { /* ... */ }
}

// file2.ts
namespace MyLib {
  export function func2() { /* ... */ }
}

// Both functions are available in MyLib

Frequently asked questions

What does "Namespace must be imported or aliased using 'import as'" mean?

This error occurs when you attempt to use a TypeScript namespace without properly importing or referencing it. TypeScript namespaces are a way to organize code and prevent naming collisions, but they require specific syntax to access their contents. When you define a namespace like namespace MyNamespace { export const value = 1; }, you cannot directly reference value without either: 1.

How do I fix "Namespace must be imported or aliased using 'import as'"?

This TypeScript compilation error occurs when trying to use a namespace without proper import syntax. Namespaces in TypeScript require explicit import statements using 'import as' syntax or namespace qualifiers to access their contents.

What causes "Namespace must be imported or aliased using 'import as'"?

Directly referencing namespace members without proper import syntax Mixing namespace syntax with ES6 module imports incorrectly Missing 'import as' statement for namespace imports

Is the "Namespace must be imported or aliased using 'import as'" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• Namespace import 'X' requires '* as' syntax

  How to fix "Namespace import 'X' requires '* as' syntax" in TypeScript

  MEDIUM

• 'moduleResolution' should be 'node' or 'classic'

  How to fix "'moduleResolution' should be 'node' or 'classic'" in TypeScript

  MEDIUM

• Namespace declaration must have a name

  How to fix "Namespace declaration must have a name" in TypeScript

  LOW

• Module has no exported member 'X'

  How to fix 'Module has no exported member X' error in TypeScript

  MEDIUM

• Cannot find name 'process'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node` and then add 'node' to the types field in your tsconfig.

  How to fix "Cannot find name 'process'" in TypeScript

  MEDIUM

• Cannot read properties of null (reading 'x')

  Cannot read properties of null (reading 'x')

  HIGH

Official resources & further reading

• 📚TypeScript Official Documentation
• 📖
  TypeScript Handbook - Namespaces(Official Docs)
• 📖
  TypeScript Handbook - Modules(Official Docs)
• Stack Overflow - Using namespaces with TypeScript external modules
• 🐙
  TypeScript Issue #2719 - Namespace import discussions(GitHub)
• 📝
  TypeScript - Namespaces and Modules