How to Use Namespaces in TypeScript

Use namespaces in TypeScript when related code should be grouped under one named scope without using ES modules. They are most useful in older codebases, browser scripts, SDK-style libraries, or situations where multiple global symbols must stay organized.

What you’ll build or solve

You’ll learn how to use namespaces in TypeScript to group values, functions, classes, and nested utilities. You’ll also know when modern modules are a better choice.

When this approach works best

This approach is the right choice when the project is not module-based or must expose one global API surface.

Common real-world scenarios include:

• Legacy browser apps
• SDK utilities
• Older enterprise code
• Global UI libraries
• Script-tag projects

This is a bad idea in modern module-based apps where ES imports and exports are the standard.

Prerequisites

You only need:

• Basic TypeScript syntax
• Functions or classes to group
• Awareness of modules vs globals

Step-by-step instructions

Step 1: Create a namespace

Use the namespace keyword.

namespace MathUtils {
  export function double(value: number): number {
    return value * 2;
  }
}

This groups the helper under one named scope.

Call it like this:

const result = MathUtils.double(5);

This avoids leaking many global names.

Step 2: Add multiple members

Namespaces can group many related values.

namespace UserUtils {
  export const defaultRole = "student";

  export function formatName(name: string): string {
    return name.trim();
  }
}

This keeps helpers visually organized.

Step 3: Use nested namespaces

Large libraries can group subdomains.

namespace App {
  export namespace Auth {
    export function login() {}
  }
}

This creates clear hierarchical access.

App.Auth.login();

What to look for:

• namespace groups related code
• Use export inside the namespace
• Access members with dot notation
• Great for legacy non-module apps
• Prefer ES modules in modern apps

Examples you can copy

Math helper

namespace MathHelper {
  export function add(a: number, b: number) {}
}

Config group

namespace Config {
  export const version = "1.0";
}

Nested auth

App.Auth.login();

Common mistakes and how to fix them

Mistake 1: Using namespaces in module-first apps

What the reader might do:

Use namespaces inside React or Node projects.

Why it breaks: ES modules are cleaner and standard.

Corrected approach:

Use export and import.

Mistake 2: Forgetting export

What the reader might do:

namespace Utils {
  function sum() {}
}

Why it breaks: the function is inaccessible outside the namespace.

Corrected approach:

Mark public members with export.

Mistake 3: Over-nesting namespaces

What the reader might do:

Create deep multi-level hierarchies.

Why it breaks: the API becomes harder to scan.

Corrected approach:

Keep nesting shallow and meaningful.

Troubleshooting

If the member is inaccessible, add export.

If the codebase already uses modules, replace namespaces with ES imports.

If the hierarchy feels deep, flatten the structure.

If browser globals collide, namespaces can still help.

Quick recap

• Use namespaces to group global code
• Export members inside the namespace
• Access with dot notation
• Best for legacy non-module projects
• Prefer ES modules in modern apps