Namespace Import

A namespace import is an ECMAScript module syntax feature supported by TypeScript that binds all exported members of a target module into a single, locally scoped identifier. At runtime, this identifier acts as a module namespace exotic object encapsulating all named and default exports as read-only properties. During compilation, TypeScript extends this behavior by allowing the same identifier to act as a namespace for accessing exported types, which are subsequently erased during the emit phase.

import * as AliasName from "module-path";

Mechanics and Behavior

Module Resolution and Binding The * wildcard instructs the compiler to resolve the entire export graph of the target module. The compiler constructs a single identifier (AliasName) where each exported runtime member becomes a property on the module namespace exotic object.

Default Export Handling If the target module contains a default export, the namespace import does not bind it to the root alias. Instead, it is explicitly attached to a property named default.

Immutability The generated runtime namespace object is strictly read-only. TypeScript enforces this at compile time. Attempting to reassign a property on the namespace object throws TS2540: Cannot assign to 'Property' because it is a read-only property. Furthermore, attempting to reassign the namespace alias itself throws TS2628: Cannot assign to 'AliasName' because it is an import.

TypeScript Type Integration

While the runtime module namespace exotic object strictly contains values (functions, objects, primitives), TypeScript allows the namespace alias to be used in type positions to access compile-time constructs (interfaces, type aliases). The compiler resolves these type accesses during static analysis and completely erases them from the emitted JavaScript.

// --- target-module.ts 
export const TIMEOUT_MS = 5000;
export function initialize() {}
export interface SystemConfig { strict: boolean; }
export default class Core {}

// --- consumer.ts 
import * as System from "./target-module";

// 1. Value Access (Named Exports)
const time = System.TIMEOUT_MS;
System.initialize();

// 2. Value Access (Default Export)
const coreInstance = new System.default();

// 3. Type Access (TypeScript Specific)
// The alias 'System' is used in a type position to access 'SystemConfig'
const config: System.SystemConfig = { strict: true };

Type-Only Namespace Imports

TypeScript 3.8 introduced the ability to prefix a namespace import with the type modifier. This guarantees that the namespace object is completely erased during the emit phase and only exists in the TypeScript AST for type checking.

import type * as SystemTypes from "./target-module";

// Valid: Accessing types
const config: SystemTypes.SystemConfig = { strict: true };

// TS1361: 'SystemTypes' cannot be used as a value because it was imported using 'import type'.
const time = SystemTypes.TIMEOUT_MS; 

Master TypeScript with Deep Grasping Methodology!

Learn More