Namespaces in TypeScript
Organize code with namespaces (internal modules) and understand when to prefer ES modules.
What you'll learn
- How to define and use namespaces with the namespace keyword
- Nested namespaces and the dot syntax
- Namespace merging across files
- Why ES modules are preferred over namespaces in modern code
Concept
The Namespace Keyword
A namespace is a named container for related declarations, defined with the namespace keyword: namespace Geometry { export function area() {} }. You access members with dot syntax: Geometry.area(). Namespaces predate ES modules and were TypeScript's original way to avoid global scope pollution. They are still found in older codebases and in declaration files for global libraries.
Nested and Merged Namespaces
Namespaces can be nested: namespace App.Utils { export function format() {} } accessed as App.Utils.format(). Namespaces also merge — declaring the same namespace name in multiple files combines their members. This merging is useful for extending a namespace across files without imports, but it can also lead to confusion about where a member is defined.
Namespaces vs Modules
In modern TypeScript, ES modules are strongly preferred over namespaces. Modules have explicit dependencies (import/export), better tooling support (tree-shaking, code splitting), and are the JavaScript standard. Namespaces create implicit global containers that are harder to reason about. Use namespaces only when working with legacy code or when writing declaration files for global libraries that cannot use modules.
Example
// Define a namespace to group related functions.
namespace Geometry {
export const PI = 3.14159;
export function circleArea(radius: number): number {
return PI * radius * radius;
}
export function squareArea(side: number): number {
return side * side;
}
}
// Nested namespace.
namespace App {
export namespace Utils {
export function formatPrice(value: number): string {
return "$" + value.toFixed(2);
}
}
}
// Namespace merging — same name in different files combines members.
namespace Geometry {
export function triangleArea(base: number, height: number): number {
return 0.5 * base * height;
}
}
console.log(Geometry.circleArea(5));
console.log(Geometry.squareArea(4));
console.log(Geometry.triangleArea(6, 8));
console.log(App.Utils.formatPrice(19.999));
Namespaces group related code with the namespace keyword. They can nest and merge across files. However, ES modules are preferred in modern code for explicit dependencies and better tooling.
Try it
- Code Minifier
See how namespaces compile to JavaScript objects vs module patterns.
- Code Diff
Compare namespace-based code with the equivalent ES module version.
Common mistakes
The mistake
Using namespaces in new projects instead of ES modules
The fix
ES modules are the modern standard with better tooling, tree-shaking, and explicit dependencies. Use namespaces only for legacy code or global library declarations.
The mistake
Forgetting to export members inside a namespace
The fix
Namespace members are private by default. Use the export keyword inside the namespace to make them accessible from outside, just like module exports.
Look up unfamiliar terms
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
Build real projects
Apply what you learned by building guided projects with starter code and solutions.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.