TypeScript Modules & Namespaces

Also Known As

TL;DR

Explanation

TypeScript module: any file with an import or export statement — isolated scope, explicit dependencies. Namespace (formerly 'internal module'): namespace Foo {} — only appropriate for global script files and ambient declarations. Modern TypeScript: always prefer ES modules for better tree-shaking, tooling, and compatibility. Ambient modules: declare module 'lodash' for adding types to untyped JavaScript packages. Declaration merging: interfaces and namespaces can be merged to extend existing types.

Common Misconception

Why It Matters

Common Mistakes

• Using namespaces in modern bundled applications — use ES modules
• Forgetting that a .ts file without import/export is a global script, not a module
• Triple-slash references (/// <reference>) in module code — use import in modern TypeScript
• Mixing namespace and module patterns in the same codebase

Code Examples

// Legacy namespace — not tree-shakeable, pollutes global scope:
namespace MyApp {
    export namespace Utils {
        export function formatDate(date: Date): string {
            return date.toISOString();
        }
    }
}
// Usage: MyApp.Utils.formatDate(new Date())

// ES Module — tree-shakeable, explicit dependencies:
// utils/date.ts:
export function formatDate(date: Date): string {
    return date.toISOString();
}

// app.ts:
import { formatDate } from './utils/date';
// Bundler includes only formatDate, not all of utils

// Ambient module for untyped JS:
declare module 'legacy-lib' {
    export function init(config: object): void;
}

References

• ↗ https://www.typescriptlang.org/docs/handbook/modules.html

Tags

Related Terms