Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Keywords and Declarations

The namespace and module keywords

Reference for TypeScript namespace and the legacy module keyword: nesting, exporting members, merging with classes, functions and enums, and when to avoid them.

A namespace groups related declarations under one name so they do not clutter the global scope. At runtime it compiles to an immediately invoked function that fills an object, so a namespace is a value as well as a container for types. Only members marked export are visible from outside.

The older spelling module Name { } means exactly the same thing and is deprecated in favor of namespace. Today ES modules replace namespaces for organizing code; namespaces remain useful for declaration merging, for describing legacy global libraries, and for augmenting existing types.

TypeScript
namespace Geometry {
  export const PI = 3.14159;
  export function area(r: number): number {
    return PI * r * r;
  }
}

Try it

TypeScript Exports and nesting

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.

TypeScript Declaration merging

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

TypeScript
namespace A.B.C {      // dotted name = nested namespaces
  export const x = 1;
}
module Legacy {}       // deprecated spelling
declare namespace Lib { function run(): void }
declare module "name" { export const v: number }
import Alias = A.B.C;  // alias for a namespace or member
Part Description
namespace name An identifier, or dotted names for nesting. Repeating the name in the same scope merges the declarations.
export Required for members that should be visible outside the block. Unexported members are private to that block.
import X = A.B Creates a local alias; it is not an ES import.
declare module "x" With a string name, declares or augments an external module (see the declare page).

Edge cases and errors:

  • A non-ambient namespace emits code. A namespace that contains only types is "non-instantiated" and emits nothing.
  • Merging a namespace with a class or function requires the namespace to come after the class or function in the same file.
  • Namespaces cannot be used under erasableSyntaxOnly unless they contain only types.
  • Unexported members are not visible even to another merged block of the same namespace.

Usage notes

  • Do not use namespaces in new application code. Use ES modules with import and export.
  • Namespaces cannot be tree-shaken as well as modules, because they are objects built at runtime.
  • Merging adds static members to classes, properties to functions, and members to enums. These are the legitimate modern uses.
  • declare global { } inside a module file is the preferred way to extend global types.
  • In .d.ts files, declare namespace describes a global object such as a library loaded with a script tag.
  • export as namespace Lib; in a declaration file exposes a UMD global.