TypeScript Reference ยท Modules and Declaration Files
TypeScript namespaces
Reference for TypeScript namespaces: syntax, exports, nesting, declaration merging with functions, classes and enums, erasableSyntaxOnly and modern alternatives.
A namespace is a TypeScript block that groups values and types under one name. It was the original way to avoid global name clashes, before JavaScript had modules. It compiles to an object created by an immediately-invoked function, with each exported member assigned to that object.
Today, ES modules do the job and namespaces are rarely needed in new code. They still matter in three places: describing old global libraries in .d.ts files, declaration merging (adding properties to a function, class or enum), and old codebases. Namespaces are also one of the few TypeScript features that produce code, which is why erasableSyntaxOnly rejects them.
namespace Shapes { export const unit = 1; export function square(n: number) { return n * n; } }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Syntax
namespace Name { export const x = 1; } namespace A.B.C { export const y = 2; } // nested shorthand declare namespace Lib { function f(): void; } // ambient, no code import Alias = Name.Inner; // namespace alias
| Part | Description |
|---|---|
export |
Only exported members are visible outside the block. Others are private. |
A.B.C |
Shorthand for namespaces nested inside each other. |
declare namespace |
Describes an existing global object. Emits nothing. |
import X = A.B |
Local name for a namespace member. It is not an ES import and is unrelated to modules. |
Errors and edge cases:
- A namespace that holds only types is non-instantiated and emits no code. As soon as it contains a value (a
const, function or class), it emits an object. - Namespaces merge when they have the same name in the same scope, including across files, which is how libraries add to a global object.
- A namespace merged with a class or function must come after it in the file; with an enum it can go anywhere after the enum.
- In a file that is a module (it has top-level
importorexport), a namespace is local to that file, not global. - The older spelling
module Name { }means the same but is deprecated; usenamespace.
Usage notes
- Do not mix namespaces and ES modules for new code. Put each concept in a file and export it.
- Node's type stripping cannot run namespaces that contain values, because the types-only erasure cannot produce the object.
erasableSyntaxOnlyreports them as errors up front. - Namespaces defeat tree shaking: the whole IIFE object is kept as one unit.
- Do not combine
/// <reference path>multi-file namespaces with modern builds; use imports. - Useful merging pattern: attach static helpers to an enum or function, or add members to
Express-style global namespaces in.d.tsfiles. - Exported
letvariables in a namespace are readable and writable through the namespace object, as theprefixexample shows.