Namespace Export

The export as namespace syntax in TypeScript is a module-level declaration that exposes a module’s exports to the global scope under a single specified identifier. It provides ambient type information for Universal Module Definition (UMD) libraries, allowing the TypeScript compiler to recognize the module’s members as global variables when a module loader is not present.

Syntax

export as namespace Identifier;

Mechanics and Compiler Behavior

• Type-Level Binding: The declaration does not emit runtime JavaScript to attach the module to the global object (e.g., window or global). It strictly informs the TypeScript type checker that the underlying UMD bundle will handle the global assignment at runtime.
• Module Requirement: It can only be declared inside a file that is already recognized as a module by the compiler (i.e., a file containing at least one top-level import or export statement).
• Single Declaration Limit: TypeScript strictly allows only one export as namespace declaration per file. Attempting to declare multiple namespace aliases within the same module will result in a compiler error.
• Global Access Resolution: By default, the declared global namespace identifier is only accessible in script files. If the consuming file is a module (meaning it contains top-level import or export statements), TypeScript intentionally hides the global alias and throws an error (TS2686), enforcing explicit imports. However, this strict isolation can be bypassed by enabling the allowUmdGlobalAccess compiler option (introduced in TypeScript 3.5), which explicitly permits module files to access UMD globals without requiring an import statement.

Implementation Example

// geometry.d.ts

// 1. Standard ES Module exports
export interface Vector2D {
    x: number;
    y: number;
}
export function calculateDistance(a: Vector2D, b: Vector2D): number;

// 2. Namespace export declaration (Strictly one per file)
export as namespace GeometryLib;

When the above declaration is included in a TypeScript compilation context, the compiler’s resolution behavior depends on the nature of the consuming file and the tsconfig.json configuration:

1. Consumption in a Script File

// script-consumer.ts (Environment without a module loader)
// No top-level imports or exports exist in this file.

// The compiler resolves 'GeometryLib' globally.
const pointA: GeometryLib.Vector2D = { x: 0, y: 0 };
const pointB: GeometryLib.Vector2D = { x: 10, y: 10 };

const distance = GeometryLib.calculateDistance(pointA, pointB);

2. Consumption in a Module File

// module-consumer.ts (Environment with a module loader)
export const origin = { x: 0, y: 0 }; // Top-level export makes this file a module

// Default Behavior (allowUmdGlobalAccess: false):
// ERROR TS2686: 'GeometryLib' refers to a UMD global, but the current file is a module.
// Consider adding an import instead.
const distance = GeometryLib.calculateDistance(origin, { x: 5, y: 5 });

// Correct approach in a module (when allowUmdGlobalAccess is false):
// import * as GeometryLib from './geometry';

// Note: If "allowUmdGlobalAccess": true is set in tsconfig.json, 
// the direct usage of GeometryLib.calculateDistance above will compile successfully.

Master TypeScript with Deep Grasping Methodology!

Learn More