Core Code
Core Code Modern Dev Handbook

Namespaces (When and Why)

Understand what TypeScript namespaces are, why modern projects usually prefer ES modules, and when namespaces still make sense. Learn practical guidance for keeping codebases maintainable.
On this page

What are namespaces?

Namespaces are an older TypeScript feature used to organize code by grouping related functions, types, and values under a single name. They were especially common before ES modules became the standard in modern JavaScript ecosystems.

Why modern projects prefer ES modules

Today, most TypeScript projects use ES modules with import and export. Modules create clear boundaries, work naturally with bundlers and Node.js, and prevent global scope pollution. In most modern architectures, modules are the correct default.

Namespace vs module: the core difference

A module is file-based and uses import/export. A namespace is a language-level grouping that can span multiple files and often compiles into a global-like structure. This can make dependencies less explicit.

A basic namespace example

namespace MathTools {
  export function add(a: number, b: number) {
    return a + b;
  }

  export function multiply(a: number, b: number) {
    return a * b;
  }
}

const result = MathTools.add(2, 3);

Why namespaces can be risky

Namespaces can hide dependencies because they encourage a shared global-style access pattern. In large codebases, this can make refactoring harder and increase coupling between modules.

When namespaces are still appropriate

  • Very small projects or demos where module tooling is not available.
  • Legacy codebases that already use namespaces heavily.
  • Global type augmentation patterns in .d.ts files (rare but real).
  • Building libraries that target environments without module loaders (uncommon today).

Namespaces in declaration files

Namespaces still appear in some declaration files (.d.ts) to describe global libraries. You may encounter this when typing older scripts that attach values to the window object.

Avoid mixing namespaces and modules

Mixing namespaces with ES modules often creates confusion. In modern projects, use modules everywhere and reserve namespaces for specific legacy or declaration scenarios.

Common mistakes

  • Using namespaces as a replacement for proper module boundaries.
  • Creating large shared namespaces that become dumping grounds.
  • Relying on implicit access instead of explicit imports.
  • Introducing namespaces into modern module-based codebases without need.

Production guidance

  • Prefer ES modules (import/export) as the default.
  • Use namespaces only for legacy interop or global .d.ts scenarios.
  • Keep dependencies explicit and refactor-friendly.
  • Do not introduce namespaces into a modern architecture without a strong reason.

What’s next

Next, we will summarize TypeScript best practices: the patterns that consistently improve maintainability, safety, and team velocity in large systems.

TypeScript Best Practices →