← All notes

Answer:

Namespace example

namespace Validation {
  export interface StringValidator { isAcceptable(s: string): boolean; }
  export const zip = /^[0-9]+$/;
}
Validation.zip.test("98052");

Only exported members are visible outside. Namespaces can span multiple files and be aliased with import v = Validation;.

Modules instead

// validation.ts
export const zip = /^[0-9]+$/;
// app.ts
import { zip } from "./validation";

Modules contain both code and declarations, get dependency tracking from bundlers and runtimes, and are the default in Node.js.

When namespaces still fit

Because the consumer of a module decides what name to assign it, there's no need to proactively wrap up the exported symbols in a namespace. (S2)

Claims

• id: C1 claim: Internal modules are now called namespaces. source: S1 evidence: "This post outlines the various ways to organize your code using namespaces (previously"
• id: C2 claim: Modules can contain both code and declarations. source: S2 evidence: "Modules can contain both code and declarations."
• id: C3 claim: Modules are recommended over namespaces in modern code. source: S2 evidence: "modules are the default and we recommended modules over namespaces in modern code"
• id: C4 claim: For new projects modules are the recommended mechanism. source: S2 evidence: "Thus, for new projects modules would be the recommended code organization mechanism."

Sources

• [S1] TypeScript: Documentation - Namespaces. TypeScript (Microsoft). https://www.typescriptlang.org/docs/handbook/namespaces.html . License: CC BY 4.0 (microsoft/TypeScript-Website). Accessed 2026-11-04.
• [S2] TypeScript: Documentation - Namespaces and Modules. TypeScript (Microsoft). https://www.typescriptlang.org/docs/handbook/namespaces-and-modules.html . License: CC BY 4.0 (microsoft/TypeScript-Website). Accessed 2026-11-04.

License: this note is CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Summary by iinventedlight (AI-assisted).

@misc{iil_note_rzw56xea,
  author = {{iinventedlight}},
  title = {{TypeScript namespaces vs modules}},
  howpublished = {iinventedlight Library},
  year = {2026},
  date = {2026-11-04},
  url = {https://iinventedlight.com/library/notes/typescript-namespaces/},
  note = {Permanent ID iil:note:rzw56xea. License: CC-BY-4.0.},
}

Markdown

Spotted a mistake? Use the MCP feedback tool or email hello@iinventedlight.com.

For language models and agents: start at /llms.txt. This page in Markdown: /library/notes/typescript-namespaces.md.