Namespaces

Reviewed & published by Brayan K

A namespace is TypeScript's older way of grouping related code under one named object so it doesn't leak into the global scope, compiling down to a simple immediately-invoked function that exposes only its exported members.

Part of the free TypeScript course at LearnCodingFast — hands-on lessons with worked examples and the output they print, plus practice exercises and a quick quiz.

What You'll Learn

• Declare a namespace and export members from it
• Understand the IIFE that a namespace compiles to
• See why only exported members are visible outside
• Nest namespaces and shorten paths with import aliases
• Compare namespaces with ES modules — and prefer modules
• Recognise where namespaces still belong (global .d.ts)

💡 Real-World Analogy

A namespace is like a labelled drawer in a filing cabinet. Everything related to "Geometry" goes in the Geometry drawer, so its names never collide with the "Banking" drawer next to it. The drawer also has a private back compartment (un-exported helpers) that only the drawer's own contents can reach. ES modules are the modern upgrade: instead of one big cabinet, each file is its own drawer with its own lock.

1. Declaring a Namespace & the Compiled IIFE

You declare a namespace with namespace Name { ... } and mark the parts you want visible with export. The compiler turns this into an IIFE that creates one object and bolts the exported members onto it. Anything you don't export becomes a private function trapped inside the closure — which is exactly how the namespace keeps helpers hidden.

// The SAME thing in real TypeScript source:
namespace Geometry {
  export const PI = 3.14159;

  export function areaOfCircle(r: number): number {
    return PI * r * r;
  }

  // No 'export' -> private to the namespace, invisible outside:
  function square(n: number): number { return n * n; }
  export function areaOfSquare(side: number): number {
    return square(side);
  }
}

Geometry.PI;              // 3.14159
Geometry.areaOfCircle(2); // 12.566...
// Geometry.square(4);    // ❌ 'square' is not exported

// A TypeScript 'namespace' is a compile-time grouping. It COMPILES to a tiny
// IIFE (Immediately Invoked Function Expression) that builds ONE object and
// attaches only the EXPORTED members to it. Here is that compiled pattern by hand:

var Geometry;
(function (Geometry) {
  Geometry.PI = 3.14159;

  function areaOfCircle(r) {
    return Geometry.PI * r * r;
  }
  Geometry.areaOfCircle = areaOfCircle;   // exported -> attached to Geometry

  // A non-exported helper stays PRIVATE inside the IIFE:
  function square(n) { return n * n; }
  Geometry.areaOfSquare = (side) => square(side);
})(Geometry || (Geometry = {}));

console.log(Geometry.PI);                          // 3.14159
console.log(Geometry.areaOfCircle(2).toFixed(2));  // 12.57
console.log(Geometry.areaOfSquare(4));             // 16
console.log(typeof Geometry.square);               // undefined (never exported)

2. Nested Namespaces

Namespaces can nest, producing a dotted path like App.Models.User. At runtime that's just nested objects: App has a Models property which has the user helpers. When the path gets long, an import Alias = App.Models shorthand keeps your code readable.

// Nesting in TS source — read it as folders of related code:
namespace App {
  export namespace Models {
    export interface User { name: string; role: string }
    export function makeUser(name: string): User {
      return { name, role: "member" };
    }
  }
}

const u: App.Models.User = App.Models.makeUser("Ada");
// You can shorten a long path with an alias import:
import Models = App.Models;
const v = Models.makeUser("Grace");

// NESTED namespaces compile to nested objects. App.Models.User becomes an
// object 'App' with a property 'Models', which has the User helpers on it.

var App;
(function (App) {
  let Models;
  (function (Models) {
    function makeUser(name) {
      return { name, role: "member" };
    }
    Models.makeUser = makeUser;
  })(Models = App.Models || (App.Models = {}));
})(App || (App = {}));

const u = App.Models.makeUser("Ada");
console.log(u.name);  // Ada
console.log(u.role);  // member

3. Namespaces vs ES Modules (Prefer Modules)

Today, ES modules are the right default. A module is a file that uses import/export; each file has its own scope, and bundlers can tree-shake away unused exports. Namespaces predate modules and put everything on one global object. Reserve namespaces for global declaration files (.d.ts) where modules aren't available.

// PREFER ES modules in modern code. The same grouping as a namespace, but
// each FILE is its own scope and bundlers/tree-shaking understand it.

// geometry.ts
export const PI = 3.14159;
export function areaOfCircle(r: number): number { return PI * r * r; }

// main.ts
import { areaOfCircle, PI } from "./geometry";
areaOfCircle(2);

// Namespaces still legitimately appear in GLOBAL .d.ts files, e.g.:
//   declare namespace NodeJS { interface ProcessEnv { API_URL: string } }
// and in older script-tag (non-module) codebases. For app code: use modules.

// You can't 'import' in this single-file runner, so here is the RUNTIME
// difference. A namespace = one shared object built by an IIFE (everything in
// one global). A module = separate scopes you wire together with import/export.

// Namespace-style (one global object holding everything):
var Geometry;
(function (Geometry) {
  Geometry.areaOfCircle = (r) => 3.14159 * r * r;
})(Geometry || (Geometry = {}));
console.log(Geometry.areaOfCircle(2).toFixed(2)); // 12.57

// Module-style (conceptually): each file exports; the bundler only includes
// what's imported (tree-shaking). Simulated here as a plain exports object:
const geometryModule = { areaOfCircle: (r) => 3.14159 * r * r };
const { areaOfCircle } = geometryModule;          // like: import { areaOfCircle }
console.log(areaOfCircle(2).toFixed(2));           // 12.57

🎯 Your Turn

Hand-compile a MathUtils namespace with two exported helpers. Fill in the two blanks marked ___, then run it.

// 🎯 YOUR TURN — replace each ___ then press "Try it Yourself".
// Recreate the compiled output of a 'MathUtils' namespace with two exports.

var MathUtils;
(function (MathUtils) {
  MathUtils.double = (n) => n * 2;
  MathUtils.triple = (n) => n * ___;   // 👉 triple multiplies by 3
})(MathUtils || (MathUtils = {}));

console.log(MathUtils.double(5));  // 10
console.log(MathUtils.___(5));     // 👉 call 'triple' -> 15

// ✅ Expected output:
//    10
//    15

Common Errors (and the fix)

• ❌ "Property 'square' does not exist on type 'typeof Geometry'" — you forgot export. ✅ Add export to any member you need outside the namespace.
• ❌ Namespace appears empty at runtime — you used a namespace inside a file that's already a module, so output was elided. ✅ Use plain export in module files; reserve namespaces for global .d.ts.
• ❌ "Cannot find namespace 'App'" — the file containing it isn't referenced. ✅ In script-tag setups add a /// <reference path="..." />; in modules, just import it.
• ❌ Mixing module and namespace keywords — the old module Foo {} syntax is confusing. ✅ Use namespace Foo {} for internal grouping and ES import/export for files.

Pro Tips

• 💡 For new app code, default to modules. If you're reaching for a namespace, ask whether a file with export would be cleaner.
• 💡 Namespaces are great in global .d.ts for grouping ambient types like NodeJS.ProcessEnv.
• 💡 Use import X = Some.Long.Path aliases to shorten deep namespace access without a real module import.
• 💡 A namespace merges with a class or function of the same name — a handy way to add nested types or static helpers.

📚 Keep Learning

• 📖 TypeScript Handbook — Namespaces
• 📖 Handbook — Namespaces and Modules
• 📖 Handbook — Modules (the modern default)

Mini-Challenge: Hand-Compile a Validation Namespace

No blanks this time — just a brief and a starting outline. Build the IIFE yourself, run it, and check your output against the example in the comments.

// 🎯 MINI-CHALLENGE: hand-compile a 'Validation' namespace.
// 1. Build an IIFE that creates a global object 'Validation'.
// 2. Export isEmail(s)  -> true when s contains "@".
// 3. Export isEmpty(s)  -> true when s.length === 0.
// 4. Log Validation.isEmail("a@b.com"), Validation.isEmail("nope"),
//    and Validation.isEmpty("").
//
// ✅ Expected output:
//    true
//    false
//    true

// your code here

🎉 Lesson Complete

• ✅ A namespace groups related code under one named object
• ✅ It compiles to an IIFE that attaches only exported members
• ✅ Un-exported members stay private inside the closure
• ✅ Namespaces nest into dotted paths like App.Models.User
• ✅ Prefer ES modules for app code; keep namespaces for global .d.ts

Practice quiz

Continue this course

• Previous: Declaration Merging
• Next: Ambient Declarations & @types — Type untyped JavaScript with declare, .d.ts files, and DefinitelyTyped
• Quick reference: TypeScript cheat sheet

Frequently asked questions

What is a TypeScript namespace?

A namespace is a way to group related code (types, functions, constants) under a single named object so they don't pollute the global scope. In source you write 'namespace Foo { export ... }'; at compile time it becomes an IIFE that builds one object 'Foo' and attaches the exported members to it.

Namespaces vs ES modules — which should I use?

Use ES modules (import/export across files) for virtually all modern application code. Modules give each file its own scope, work with bundlers and tree-shaking, and match how the rest of the JavaScript ecosystem works. Namespaces are mostly a legacy feature from before modules existed in TypeScript.

Why does only an 'export'-ed member show up outside the namespace?

Because the compiled IIFE only attaches exported members to the namespace object. Anything without 'export' becomes a private function or variable inside the IIFE's closure — useful for helpers you don't want to expose, but invisible to code outside.

Where do namespaces still legitimately appear?

Chiefly in global declaration files (.d.ts), where you can't use modules — for example 'declare namespace NodeJS { interface ProcessEnv { ... } }' or the global Express namespace. They also show up in older script-tag codebases that load TypeScript output directly without a module system.