{
    "slug": "typescript_modules",
    "term": "TypeScript Modules & Namespaces",
    "category": "typescript",
    "difficulty": "intermediate",
    "short": "ES modules (import/export) are the modern standard — namespaces are legacy for global scripts and ambient declarations only.",
    "long": "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.",
    "aliases": [
        "TypeScript namespaces",
        "module resolution",
        "ambient module",
        "declare module"
    ],
    "tags": [
        "typescript",
        "modules"
    ],
    "misconception": "TypeScript namespaces are the correct way to organise code — namespaces are a legacy pattern; ES modules with explicit imports provide better tree-shaking and tooling support.",
    "why_it_matters": "Using namespaces in a bundler project prevents tree-shaking (all namespace code is included even if unused) and creates confusion about what is exported — ES modules are the correct default.",
    "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"
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "js_module_patterns",
        "typescript_interfaces_types",
        "typescript_decorators"
    ],
    "prerequisites": [
        "typescript_config",
        "js_module_patterns",
        "typescript_interfaces_types"
    ],
    "refs": [
        "https://www.typescriptlang.org/docs/handbook/modules.html"
    ],
    "bad_code": "// Legacy namespace — not tree-shakeable, pollutes global scope:\nnamespace MyApp {\n    export namespace Utils {\n        export function formatDate(date: Date): string {\n            return date.toISOString();\n        }\n    }\n}\n// Usage: MyApp.Utils.formatDate(new Date())",
    "good_code": "// ES Module — tree-shakeable, explicit dependencies:\n// utils/date.ts:\nexport function formatDate(date: Date): string {\n    return date.toISOString();\n}\n\n// app.ts:\nimport { formatDate } from './utils/date';\n// Bundler includes only formatDate, not all of utils\n\n// Ambient module for untyped JS:\ndeclare module 'legacy-lib' {\n    export function init(config: object): void;\n}",
    "quick_fix": "Use ES module syntax (import/export) not namespace or module keywords — TypeScript namespaces are legacy; configure moduleResolution: NodeNext or bundler to match your build tool",
    "severity": "medium",
    "effort": "low",
    "created": "2026-03-16",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/typescript_modules",
        "html_url": "https://codeclaritylab.com/glossary/typescript_modules",
        "json_url": "https://codeclaritylab.com/glossary/typescript_modules.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[TypeScript Modules & Namespaces](https://codeclaritylab.com/glossary/typescript_modules) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/typescript_modules"
            }
        }
    }
}