TypeScript namespaces and modules

Note about terminology: It is important to note that the term name in TypeScript 1.5 has changed. T he "internal module" is now called the "namespace". "External Module" is now referred to simply as "Module" in order to be consistent with the terminology in ECMAScript 2015 (i.e., module X { is equivalent to the now namespace X {

Introduced

This article will provide an overview of how to organize your code in TypeScript using modules and namespaces. We also talk about advanced usage scenarios for namespaces and modules, and common pitfalls in using them.

Check out the Modules section to learn more about modules. Check out the Namespaces section to learn more about namespaces.

Use a namespace

A namespace is a generic JavaScript object with a name under a global namespace. T his makes namespaces easy to use. T hey can be used simultaneously in multiple files and combined with --outFile Namespaces are a great way to help you organize your Web applications, and you can put all your dependencies in <script> HTML pages.

But like other global namespace contamination, it is difficult to identify dependencies between components, especially in large applications.

Use the module

Like namespaces, modules can contain code and declarations. The difference is that the module can declare its dependencies.

The module adds dependencies to the module loader (e.g. CommonJs / .js). T his may not be necessary for small JS applications, but for large applications, this cost can lead to long-term modularity and maintainability. Modules also provide better code reuse, greater enclosure, and better use of tools for optimization.

For Node .js, modules are the default and recommended way to organization code.

Starting with ECMAScript 2015, modules have become part of the language built-in and should be supported by all normal interpretation engines. Therefore, for new projects, it is recommended to use modules as a way to organize your code.

Traps for namespaces and modules

In this section we describe common namespace and module usage traps and how to avoid them.

Use /// <reference>

A common mistake is to refer to the module file using /// <reference> and you should use import T o understand the difference, we should first figure out how the compiler import path (for example, import x from import x from "..."; or import x = require("...") ... , ... to locate the module's type information.

The compiler first tries to find .ts .tsx .d.ts I f these files are not found, the compiler looks for external module declarations. Recall that they were declared .d.ts file.

• myModules.d.ts

// In a .d.ts file or .ts file that is not a module:
declare module "SomeModule" {
    export function fn(): string;
}

• myOtherModule.ts

/// <reference path="myModules.d.ts" />
import * as m from "SomeModule";

The reference label here specifies the location of the foreign module. This is how node.d.ts

Unnecessary namespaces

If you want to convert a namespace to a module, it might look like this file:

• shapes.ts

export namespace Shapes {
    export class Triangle { /* ... */ }
    export class Square { /* ... */ }
}

Top-level module Shapes Triangle and Square This is confusing and annoying for those who use it:

• shapeConsumer.ts

import * as shapes from "./shapes";
let t = new shapes.Shapes.Triangle(); // shapes.Shapes?

One feature of modules in TypeScript is that different modules never use the same name within the same scope. Because people who use modules name them, there is no need to wrap exported symbols in a namespace.

Again, namespaces should not be used for modules, which are used to provide logical grouping and avoid naming conflicts. The module file itself is already a logical grouping, and its name is specified by the code that imported the module, so there is no need to add an additional module layer to the exported object.

Here are some examples of improvements:

• shapes.ts

export class Triangle { /* ... */ }
export class Square { /* ... */ }

• shapeConsumer.ts

import * as shapes from "./shapes";
let t = new shapes.Triangle();

The pick-and-go for the module

Just as each JS file corresponds to a module, the module file in TypeScript corresponds to the generated JS file one-to-one. T his can have an effect, and depending on the target module system you specify, you may not be able to connect multiple module source files. For example, the outFile option cannot be used when the target module system is commonjs or umd but versions above TypeScript 1.8 can outFile when the amd or system