skip to content

In TypeScript, what is a `namespace`, and why do new projects use ES modules instead?

level: juniorimportance: should knowfreq 40%

answer

  1. older than JavaScript's own modules
  2. a named object plus export
  3. internal modules, renamed in 1.5
  4. dependencies implied by global names
  5. the file is already the group

basics

~10 s

A TypeScript namespace is a named object that groups code and keeps unexported members private, usually in global scope. New projects use ES modules because they are native JavaScript and state their dependencies explicitly.

solid answer

~40 s

A `namespace` is TypeScript's own way to group declarations under one name: you write `namespace Validation { export class ZipCodeValidator {} }` and callers write `Validation.ZipCodeValidator`. It predates JavaScript's module system, and very old versions called it an internal module. At runtime it is a plain object, global in a script file, filled in by a wrapper function; anything without `export` stays private to its block. Modules replaced it for new work because they are part of the language. A module's dependencies are written as `import` statements instead of being implied by shared global names, two modules never contribute names to the same scope, and bundlers support them better. The handbook recommends modules for new projects. You still meet namespaces in older script-tag codebases and in typings for libraries that expose a global object.

go deeper

for a junior

Recall that a namespace is a named object with exported members, and that modules are the default today because they are native JavaScript.

for a middle

Be ready to say that a value namespace produces real runtime code and that its global name, not an import, is how other files find it.

for a senior

Connect the design to its cost: hidden dependencies and load order are what make large namespace codebases hard to change or bundle.

for a principal

Treat namespaces as a legacy decision to manage rather than an option for new work, and be able to say what would justify keeping one.

## What a namespace is A TypeScript **namespace** is a named container for declarations. You write the keyword `namespace`, a name and a block, and everything callers should reach gets the `export` keyword. Everything else stays private to that block. ```ts namespace Validation { const numberRegexp = /^[0-9]+$/; export class ZipCodeValidator { isAcceptable(s: string) { return s.length === 5 && numberRegexp.test(s); } } } const v = new Validation.ZipCodeValidator(); ``` Outside the block you use a **qualified name**, `Validation.ZipCodeValidator`. The regular expression has no `export`, so `Validation.numberRegexp` is a compile error. Namespaces are a TypeScript feature, not a JavaScript one. Very old versions called them **internal modules**, a name that predates JavaScript's own module systems, and TypeScript 1.5 renamed them. Their purpose was simple: stop an application's names colliding in the one global scope that every script tag shared. ## What it is at runtime A namespace that holds values is not erased the way an interface is. The compiler turns it into a plain JavaScript object, created and filled by a wrapper function that runs immediately. In a script file, meaning a file with no top-level `import` or `export`, that object is a global variable. The handbook says it directly: namespaces are simply named JavaScript objects in the global namespace. Two consequences follow: - **Blocks can be reopened.** Several blocks with the same name, even in different files, add to one object. - **Dependencies are invisible.** Nothing in a file states which other file must load first, so the order of the script tags or of the concatenated output has to be right. - **Exports are plain properties.** Outside code reaches a member through the object, and at runtime nothing stops a later script from overwriting it. ## Why ES modules replaced it An **ES module** is a file with a top-level `import` or `export`. Modules have been part of JavaScript since ECMAScript 2015, so compliant engines run them directly. | | `namespace` | ES module | |---|---|---| | Defined by | TypeScript | the JavaScript language | | Unit of grouping | a named block, may span files | one file | | Dependencies | implied by global names and load order | written as `import` statements | | Name collisions | possible in the shared global scope | two modules never contribute names to the same scope | | Who picks the local name | the author | the importer | | Needs | script tags in the right order | a module loader or a runtime that supports modules | The handbook says modules give better code reuse, stronger isolation and better tooling support for bundling, and it recommends them for new projects. The main cost of namespaces comes from what made them simple: with everything hanging off shared global names, it gets hard to see what depends on what as an application grows. ## Where you still see namespaces - **Older applications** that load every file with a script tag and have no module loader at all. - **Typings for a library that exposes a global object**, where `declare namespace` describes that object. That form emits nothing. Neither is a reason to start a new application with them. A new file that seems to want a namespace usually wants to be a module with a few named exports. ## The old spelling Older code writes `module Validation { }` for the same thing. The handbook says that form is equivalent and that `namespace` should be used instead, which also avoids confusion with ES modules. TypeScript 6.0 goes further and reports the old spelling as error TS1540. `declare module "some-package"` with a quoted string is a different construct, about packages, and it is still valid. ## Common mistakes 1. Calling a namespace a compile-time-only feature. Only a namespace holding nothing but types disappears. 2. Treating namespaces and modules as interchangeable. A module's scope is its file, while a namespace in a script file is global. 3. Wrapping a module's exports in a namespace to group them. The file is already the group, and the importer already chooses its name. 4. Reading `export` the same way in both places. Inside a namespace it attaches a member to the object, while in a module it is part of the file's public surface, which importers ask for by name.

  • In TypeScript, what is the difference between `module Foo {}` and `declare module "foo" {}`?
    `module Foo {}` with a bare identifier is the old spelling of `namespace Foo {}`, and TypeScript 6.0 reports it as error TS1540. With a quoted string, `declare module "foo"` describes a package you import by that name, and it remains valid. One keyword does two unrelated jobs, which is the confusion the rename to `namespace` was meant to remove.
  • Does a TypeScript `namespace` declared inside a module file still end up in global scope?
    No. A file with a top-level `import` or `export` is a module, so the `var` the compiler emits for the namespace is scoped to that module. Writing `export namespace Shapes` makes it an ordinary named export. The global behaviour belongs to script files only.

  • A namespace is always erased at compile time, just like an interface.
  • A TypeScript namespace and an ES module are two names for the same thing.
  • New projects should prefer namespaces because import and export are not idiomatic TypeScript.
  • Everything inside a namespace block is automatically visible to code outside it.
  • A namespace isolates code as well as a module does, because each one has its own scope.

The module keyword note assumes TypeScript 6.0, where the bare module X form is error TS1540; the rest holds across releases.