TypeScript Namespace: Syntax, Usage, and Examples

A TypeScript namespace groups related code under a single name, preventing naming conflicts and improving code organization. While ES6 modules have largely replaced namespaces in modern development, namespaces are still useful for structuring large TypeScript applications that don’t use external bundlers. They provide a way to define reusable functions, classes, and interfaces in a shared scope while keeping them encapsulated.

How to Use a Namespace in TypeScript

To create a namespace, use the namespace keyword followed by a name and a block containing related code. Use the export keyword for elements you want to access outside the namespace.

namespace Logger {
  export function log(message: string): void {
    console.log(`[LOG]: ${message}`);
  }
}

Logger.log("Namespace example initialized.");

If a namespace spans multiple files, reference it using a triple-slash directive before using it elsewhere.

/// <reference path="logger.ts" />
Logger.log("Reference path is working.");

Nested Namespaces

You can nest namespaces to create a structured hierarchy for related functionality.

namespace Data {
  export namespace Validation {
    export function isNumber(value: any): boolean {
      return typeof value === "number";
    }
  }
}

console.log(Data.Validation.isNumber(42)); // Output: true
console.log(Data.Validation.isNumber("test")); // Output: false

When to Use a Namespace in TypeScript

Namespaces help manage large codebases by organizing related functionalities together. Use them when working on libraries, internal utility functions, or projects without module bundlers. They also help prevent variable collisions in applications with multiple contributors.

A namespace is useful for logically grouping similar functions, interfaces, or classes, such as utilities for mathematical calculations or application-wide logging mechanisms. You can also extend a namespace across different parts of a project, allowing additional functionality to be added incrementally.

Examples of Namespaces in TypeScript

Structuring Utility Functions

Namespaces provide a clear way to organize helper functions.

namespace MathUtils {
  export function square(num: number): number {
    return num * num;
  }

  export function cube(num: number): number {
    return num * num * num;
  }
}

console.log(MathUtils.square(5)); // Output: 25
console.log(MathUtils.cube(3)); // Output: 27

Extending a Namespace

You can add more functionality to an existing namespace by defining it in separate files.

namespace App {
  export function start(): void {
    console.log("Application started.");
  }
}

// Later in the project
namespace App {
  export function stop(): void {
    console.log("Application stopped.");
  }
}

App.start(); // Output: Application started.
App.stop(); // Output: Application stopped.

Using Namespaces in Multiple Files

When working with large applications, you can split a namespace across multiple files while maintaining accessibility.

math.ts

namespace Operations {
  export function multiply(a: number, b: number): number {
    return a * b;
  }
}

app.ts

/// <reference path="math.ts" />
console.log(Operations.multiply(4, 3)); // Output: 12

Learn More About TypeScript Namespaces

Namespace vs. Module

Although namespaces help organize code, ES6 modules provide a more modern and flexible way to structure applications. Modules use import and export, working seamlessly with modern JavaScript tooling.

// Using ES6 modules
export function add(a: number, b: number): number {
  return a + b;
}

import { add } from "./mathModule";
console.log(add(5, 2)); // Output: 7

Namespaces suit projects where external module bundlers aren’t used, while ES6 modules are ideal for scalable applications.

Handling "Cannot Find Namespace" Errors

A common issue when using namespaces is the "Cannot find namespace" error, which occurs when TypeScript cannot locate the namespace definition. This often happens when:

• The namespace isn't referenced properly with /// <reference path="file.ts" />.
• The TypeScript compiler isn't set up to recognize the files containing the namespace.

Ensure all necessary references are in place and the TypeScript configuration includes the correct files.

Global vs. Local Namespaces

Namespaces can be global or local, depending on how they are declared. Global namespaces are accessible throughout a project, but they can cause conflicts if multiple files define the same name. To avoid issues, encapsulate namespaces in separate files or use namespace extensions instead of redefining them.

Namespace Imports

If a namespace contains many elements, importing it as an alias makes code easier to read.

namespace Database {
  export function connect(): void {
    console.log("Connected to database.");
  }
}

import DB = Database;
DB.connect(); // Output: Connected to database.

This approach reduces the need for long namespace references while keeping code modular.

Namespace and Class Differences

While both namespaces and classes group related logic, they serve different purposes. A class defines an object blueprint with properties and methods, whereas a namespace organizes functions, interfaces, and types under a common scope.

Namespaces help avoid naming conflicts in large applications, but for reusable components, modules and classes provide better flexibility and maintainability.

Module vs. Namespace for Large Applications

For modern applications, ES6 modules handle dependency management more effectively than namespaces. Modules offer better support for dynamic imports, tree-shaking, and code-splitting, making them preferable for large-scale projects.

However, namespaces remain relevant when working with TypeScript in environments where module loading is not an option, such as older JavaScript projects or internal company libraries.

TypeScript namespaces provide a way to organize and encapsulate related code within a local scope, reducing the risk of naming conflicts. While ES6 modules are the preferred approach for structuring modern applications, namespaces still serve a purpose in legacy projects and large-scale TypeScript applications without module bundlers.