namespaces-and-modules.md

Namespace and Module

When declaring a module (or namespace), there are two options:

• declaration wrapped in declare {namespace,module} <name> {, or
• top-level declaration

Top-level declarations in a source file with no top-level import or export declarations belong to the global namespace. Top-level declarations in a source file with one or more top-level import or export declarations belong to the module represented by that source file. (link, need to scroll down a bit)

Namespace (Internal Module)

• Use declare namespace X { syntax.

• Avoid declare module X { syntax.

  Why? declare namespace X { will fixate the namespace to the name X, which is what you want.

  tslint no-internal-module

  // bad
  declare module Chai {
    // stuff...
  }
  
  // good
  declare namespace Chai {
    // stuff...
  }

Module (External Module)

• Do not wrap typings in declare module "X" {. Expose as top-level declaration

  Why? declare module "X" { will cause name conflict if consumer use two different version of the same library.

  // bad
  declare module "X" {
    export interface A {
      // stuff...
    };
  }
  
  // good
  export interface A {
    // stuff...
  };

Note

Prior to TypeScript 1.5, there are two types of modules:

• Internal module (declare module X {)
• External module (declare module "X" {)

In TypeScript 1.5, the term and keyword namespace is introduced. The nomenclature has changed.

• Internal module -> namespace
• External module -> module

The declare module X { syntax exists for backward compatibility.

Reference

https://github.com/Microsoft/TypeScript-Handbook/blob/master/pages/Namespaces.md https://github.com/Microsoft/TypeScript-Handbook/blob/master/pages/Namespaces%20and%20Modules.md https://github.com/Microsoft/TypeScript-Handbook/blob/master/pages/Modules.md