Starting with ECMAScript 2015, JavaScript has a concept of modules. TypeScript shares this concept.
\nModules are executed within their own scope, not in the global scope; this means that variables, functions, classes, etc. declared in a module are not visible outside the module unless they are explicitly exported using one of the export forms.\nConversely, to consume a variable, function, class, interface, etc. exported from a different module, it has to be imported using one of the import forms.
Modules are declarative; the relationships between modules are specified in terms of imports and exports at the file level.
\nModules import one another using a module loader.\nAt runtime the module loader is responsible for locating and executing all dependencies of a module before executing it.\nWell-known module loaders used in JavaScript are Node.js’s loader for CommonJS modules and the RequireJS loader for AMD modules in Web applications.
\nIn TypeScript, just as in ECMAScript 2015, any file containing a top-level import or export is considered a module.\nConversely, a file without any top-level import or export declarations is treated as a script whose contents are available in the global scope (and therefore to modules as well).
Any declaration (such as a variable, function, class, type alias, or interface) can be exported by adding the export keyword.
\ntsexport interface StringValidator {\n isAcceptable(s: string): boolean;\n}
\ntsimport { StringValidator } from \"./StringValidator\";\n\nexport const numberRegexp = /^[0-9]+$/;\n\nexport class ZipCodeValidator implements StringValidator {\n isAcceptable(s: string) {\n return s.length === 5 && numberRegexp.test(s);\n }\n}
Export statements are handy when exports need to be renamed for consumers, so the above example can be written as:
\n\ntsclass ZipCodeValidator implements StringValidator {\n isAcceptable(s: string) {\n return s.length === 5 && numberRegexp.test(s);\n }\n}\nexport { ZipCodeValidator };\nexport { ZipCodeValidator as mainValidator };
Often modules extend other modules, and partially expose some of their features.\nA re-export does not import it locally, or introduce a local variable.
\n\ntsexport class ParseIntBasedZipCodeValidator {\n isAcceptable(s: string) {\n return s.length === 5 && parseInt(s).toString() === s;\n }\n}\n\n// Export original validator but rename it\nexport { ZipCodeValidator as RegExpBasedZipCodeValidator } from \"./ZipCodeValidator\";
Optionally, a module can wrap one or more modules and combine all their exports using export * from \"module\" syntax.
\ntsexport * from \"./StringValidator\"; // exports 'StringValidator' interface\nexport * from \"./ZipCodeValidator\"; // exports 'ZipCodeValidator' and const 'numberRegexp' class\nexport * from \"./ParseIntBasedZipCodeValidator\"; // exports the 'ParseIntBasedZipCodeValidator' class\n// and re-exports 'RegExpBasedZipCodeValidator' as alias\n// of the 'ZipCodeValidator' class from 'ZipCodeValidator.ts'\n// module.
Importing is just about as easy as exporting from a module.\nImporting an exported declaration is done through using one of the import forms below:
\ntsimport { ZipCodeValidator } from \"./ZipCodeValidator\";\n\nlet myValidator = new ZipCodeValidator();
imports can also be renamed
\n\ntsimport { ZipCodeValidator as ZCV } from \"./ZipCodeValidator\";\nlet myValidator = new ZCV();
\ntsimport * as validator from \"./ZipCodeValidator\";\nlet myValidator = new validator.ZipCodeValidator();
Though not recommended practice, some modules set up some global state that can be used by other modules.\nThese modules may not have any exports, or the consumer is not interested in any of their exports.\nTo import these modules, use:
\n\ntsimport \"./my-module.js\";
Prior to TypeScript 3.8, you can import a type using import.\nWith TypeScript 3.8, you can import a type using the import statement, or using import type.
\nts// Re-using the same import\nimport {APIResponseType} from \"./api\";\n\n// Explicitly use import type\nimport type {APIResponseType} from \"./api\";
import type is always guaranteed to be removed from your JavaScript, and tools like Babel can make better assumptions about your code via the isolatedModules compiler flag.\nYou can read more in the 3.8 release notes.
Each module can optionally export a default export.\nDefault exports are marked with the keyword default; and there can only be one default export per module.\ndefault exports are imported using a different import form.
default exports are really handy.\nFor instance, a library like jQuery might have a default export of jQuery or $, which we’d probably also import under the name $ or jQuery.
\ntsdeclare let $: JQuery;\nexport default $;
\ntsimport $ from \"jquery\";\n\n$(\"button.continue\").html(\"Next Step...\");
Classes and function declarations can be authored directly as default exports.\nDefault export class and function declaration names are optional.
\n\ntsexport default class ZipCodeValidator {\n static numberRegexp = /^[0-9]+$/;\n isAcceptable(s: string) {\n return s.length === 5 && ZipCodeValidator.numberRegexp.test(s);\n }\n}
\ntsimport validator from \"./ZipCodeValidator\";\n\nlet myValidator = new validator();
or
\n\ntsconst numberRegexp = /^[0-9]+$/;\n\nexport default function(s: string) {\n return s.length === 5 && numberRegexp.test(s);\n}
\ntsimport validate from \"./StaticZipCodeValidator\";\n\nlet strings = [\"Hello\", \"98052\", \"101\"];\n\n// Use function validate\nstrings.forEach(s => {\n console.log(`\"${s}\" ${validate(s) ? \"matches\" : \"does not match\"}`);\n});
default exports can also be just values:
\ntsexport default \"123\";
\ntsimport num from \"./OneTwoThree\";\n\nconsole.log(num); // \"123\"
With TypeScript 3.8, you can use export * as ns as a shorthand for re-exporting another module with a name:
\ntsexport * as utilities from \"./utilities\";
This takes all of the dependencies from a module and makes it an exported field, you could import it like this:
\n\ntsimport { utilities } from \"./index\";
export = and import = require()Both CommonJS and AMD generally have the concept of an exports object which contains all exports from a module.
They also support replacing the exports object with a custom single object.\nDefault exports are meant to act as a replacement for this behavior; however, the two are incompatible.\nTypeScript supports export = to model the traditional CommonJS and AMD workflow.
The export = syntax specifies a single object that is exported from the module.\nThis can be a class, interface, namespace, function, or enum.
When exporting a module using export =, TypeScript-specific import module = require(\"module\") must be used to import the module.
\ntslet numberRegexp = /^[0-9]+$/;\nclass ZipCodeValidator {\n isAcceptable(s: string) {\n return s.length === 5 && numberRegexp.test(s);\n }\n}\nexport = ZipCodeValidator;
\ntsimport zip = require(\"./ZipCodeValidator\");\n\n// Some samples to try\nlet strings = [\"Hello\", \"98052\", \"101\"];\n\n// Validators to use\nlet validator = new zip();\n\n// Show whether each string passed each validator\nstrings.forEach(s => {\n console.log(\n `\"${s}\" - ${validator.isAcceptable(s) ? \"matches\" : \"does not match\"}`\n );\n});
Depending on the module target specified during compilation, the compiler will generate appropriate code for Node.js (CommonJS), require.js (AMD), UMD, SystemJS, or ECMAScript 2015 native modules (ES6) module-loading systems.\nFor more information on what the define, require and register calls in the generated code do, consult the documentation for each module loader.
This simple example shows how the names used during importing and exporting get translated into the module loading code.
\n\ntsimport m = require(\"mod\");\nexport let t = m.something + 1;
\njsdefine([\"require\", \"exports\", \"./mod\"], function(require, exports, mod_1) {\n exports.t = mod_1.something + 1;\n});
\njsvar mod_1 = require(\"./mod\");\nexports.t = mod_1.something + 1;
\njs(function(factory) {\n if (typeof module === \"object\" && typeof module.exports === \"object\") {\n var v = factory(require, exports);\n if (v !== undefined) module.exports = v;\n } else if (typeof define === \"function\" && define.amd) {\n define([\"require\", \"exports\", \"./mod\"], factory);\n }\n})(function(require, exports) {\n var mod_1 = require(\"./mod\");\n exports.t = mod_1.something + 1;\n});
\njsSystem.register([\"./mod\"], function(exports_1) {\n var mod_1;\n var t;\n return {\n setters: [\n function(mod_1_1) {\n mod_1 = mod_1_1;\n }\n ],\n execute: function() {\n exports_1(\"t\", (t = mod_1.something + 1));\n }\n };\n});
\njsimport { something } from \"./mod\";\nexport var t = something + 1;
Below, we’ve consolidated the Validator implementations used in previous examples to only export a single named export from each module.
\nTo compile, we must specify a module target on the command line. For Node.js, use --module commonjs;\nfor require.js, use --module amd. For example:
tsc --module commonjs Test.ts\nWhen compiled, each module will become a separate .js file.\nAs with reference tags, the compiler will follow import statements to compile dependent files.
\ntsexport interface StringValidator {\n isAcceptable(s: string): boolean;\n}
\ntsimport { StringValidator } from \"./Validation\";\n\nconst lettersRegexp = /^[A-Za-z]+$/;\n\nexport class LettersOnlyValidator implements StringValidator {\n isAcceptable(s: string) {\n return lettersRegexp.test(s);\n }\n}
\ntsimport { StringValidator } from \"./Validation\";\n\nconst numberRegexp = /^[0-9]+$/;\n\nexport class ZipCodeValidator implements StringValidator {\n isAcceptable(s: string) {\n return s.length === 5 && numberRegexp.test(s);\n }\n}
\ntsimport { StringValidator } from \"./Validation\";\nimport { ZipCodeValidator } from \"./ZipCodeValidator\";\nimport { LettersOnlyValidator } from \"./LettersOnlyValidator\";\n\n// Some samples to try\nlet strings = [\"Hello\", \"98052\", \"101\"];\n\n// Validators to use\nlet validators: { [s: string]: StringValidator } = {};\nvalidators[\"ZIP code\"] = new ZipCodeValidator();\nvalidators[\"Letters only\"] = new LettersOnlyValidator();\n\n// Show whether each string passed each validator\nstrings.forEach(s => {\n for (let name in validators) {\n console.log(\n `\"${s}\" - ${\n validators[name].isAcceptable(s) ? \"matches\" : \"does not match\"\n } ${name}`\n );\n }\n});
In some cases, you may want to only load a module under some conditions.\nIn TypeScript, we can use the pattern shown below to implement this and other advanced loading scenarios to directly invoke the module loaders without losing type safety.
\nThe compiler detects whether each module is used in the emitted JavaScript.\nIf a module identifier is only ever used as part of a type annotations and never as an expression, then no require call is emitted for that module.\nThis elision of unused references is a good performance optimization, and also allows for optional loading of those modules.
The core idea of the pattern is that the import id = require(\"...\") statement gives us access to the types exposed by the module.\nThe module loader is invoked (through require) dynamically, as shown in the if blocks below.\nThis leverages the reference-elision optimization so that the module is only loaded when needed.\nFor this pattern to work, it’s important that the symbol defined via an import is only used in type positions (i.e. never in a position that would be emitted into the JavaScript).
To maintain type safety, we can use the typeof keyword.\nThe typeof keyword, when used in a type position, produces the type of a value, in this case the type of the module.
\ntsdeclare function require(moduleName: string): any;\n\nimport { ZipCodeValidator as Zip } from \"./ZipCodeValidator\";\n\nif (needZipValidation) {\n let ZipCodeValidator: typeof Zip = require(\"./ZipCodeValidator\");\n let validator = new ZipCodeValidator();\n if (validator.isAcceptable(\"...\")) {\n /* ... */\n }\n}
\ntsdeclare function require(\n moduleNames: string[],\n onLoad: (...args: any[]) => void\n): void;\n\nimport * as Zip from \"./ZipCodeValidator\";\n\nif (needZipValidation) {\n require([\"./ZipCodeValidator\"], (ZipCodeValidator: typeof Zip) => {\n let validator = new ZipCodeValidator.ZipCodeValidator();\n if (validator.isAcceptable(\"...\")) {\n /* ... */\n }\n });\n}
\ntsdeclare const System: any;\n\nimport { ZipCodeValidator as Zip } from \"./ZipCodeValidator\";\n\nif (needZipValidation) {\n System.import(\"./ZipCodeValidator\").then((ZipCodeValidator: typeof Zip) => {\n var x = new ZipCodeValidator();\n if (x.isAcceptable(\"...\")) {\n /* ... */\n }\n });\n}
To describe the shape of libraries not written in TypeScript, we need to declare the API that the library exposes.
\nWe call declarations that don’t define an implementation “ambient”.\nTypically, these are defined in .d.ts files.\nIf you’re familiar with C/C++, you can think of these as .h files.\nLet’s look at a few examples.
In Node.js, most tasks are accomplished by loading one or more modules.\nWe could define each module in its own .d.ts file with top-level export declarations, but it’s more convenient to write them as one larger .d.ts file.\nTo do so, we use a construct similar to ambient namespaces, but we use the module keyword and the quoted name of the module which will be available to a later import.\nFor example:
\ntsdeclare module \"url\" {\n export interface Url {\n protocol?: string;\n hostname?: string;\n pathname?: string;\n }\n\n export function parse(\n urlStr: string,\n parseQueryString?,\n slashesDenoteHost?\n ): Url;\n}\n\ndeclare module \"path\" {\n export function normalize(p: string): string;\n export function join(...paths: any[]): string;\n export var sep: string;\n}
Now we can /// <reference> node.d.ts and then load the modules using import url = require(\"url\"); or import * as URL from \"url\".
\nts/// <reference path=\"node.d.ts\"/>\nimport * as URL from \"url\";\nlet myUrl = URL.parse(\"http://www.typescriptlang.org\");
If you don’t want to take the time to write out declarations before using a new module, you can use a shorthand declaration to get started quickly.
\n\ntsdeclare module \"hot-new-module\";
All imports from a shorthand module will have the any type.
\ntsimport x, { y } from \"hot-new-module\";\nx(y);
Some module loaders such as SystemJS\nand AMD allow non-JavaScript content to be imported.\nThese typically use a prefix or suffix to indicate the special loading semantics.\nWildcard module declarations can be used to cover these cases.
\n\ntsdeclare module \"*!text\" {\n const content: string;\n export default content;\n}\n// Some do it the other way around.\ndeclare module \"json!*\" {\n const value: any;\n export default value;\n}
Now you can import things that match \"*!text\" or \"json!*\".
\ntsimport fileContent from \"./xyz.txt!text\";\nimport data from \"json!http://example.com/data.json\";\nconsole.log(data, fileContent);
Some libraries are designed to be used in many module loaders, or with no module loading (global variables).\nThese are known as UMD modules.\nThese libraries can be accessed through either an import or a global variable.\nFor example:
\n\ntsexport function isPrime(x: number): boolean;\nexport as namespace mathLib;
The library can then be used as an import within modules:
\n\ntsimport { isPrime } from \"math-lib\";\nisPrime(2);\nmathLib.isPrime(2); // ERROR: can't use the global definition from inside a module
It can also be used as a global variable, but only inside of a script.\n(A script is a file with no imports or exports.)
\n\ntsmathLib.isPrime(2);
Consumers of your module should have as little friction as possible when using things that you export.\nAdding too many levels of nesting tends to be cumbersome, so think carefully about how you want to structure things.
\nExporting a namespace from your module is an example of adding too many layers of nesting.\nWhile namespaces sometime have their uses, they add an extra level of indirection when using modules.\nThis can quickly become a pain point for users, and is usually unnecessary.
\nStatic methods on an exported class have a similar problem - the class itself adds a layer of nesting.\nUnless it increases expressivity or intent in a clearly useful way, consider simply exporting a helper function.
\nclass or function, use export defaultJust as “exporting near the top-level” reduces friction on your module’s consumers, so does introducing a default export.\nIf a module’s primary purpose is to house one specific export, then you should consider exporting it as a default export.\nThis makes both importing and actually using the import a little easier.\nFor example:
\n\ntsexport default class SomeType {\n constructor() { ... }\n}
\ntsexport default function getThing() {\n return \"thing\";\n}
\ntsimport t from \"./MyClass\";\nimport f from \"./MyFunc\";\nlet x = new t();\nconsole.log(f());
This is optimal for consumers. They can name your type whatever they want (t in this case) and don’t have to do any excessive dotting to find your objects.
\ntsexport class SomeType {\n /* ... */\n}\nexport function someFunc() {\n /* ... */\n}
Conversely when importing:
\n\ntsimport { SomeType, someFunc } from \"./MyThings\";\nlet x = new SomeType();\nlet y = someFunc();
\ntsexport class Dog { ... }\nexport class Cat { ... }\nexport class Tree { ... }\nexport class Flower { ... }
\ntsimport * as myLargeModule from \"./MyLargeModule.ts\";\nlet x = new myLargeModule.Dog();
Often you will need to extend functionality on a module.\nA common JS pattern is to augment the original object with extensions, similar to how JQuery extensions work.\nAs we’ve mentioned before, modules do not merge like global namespace objects would.\nThe recommended solution is to not mutate the original object, but rather export a new entity that provides the new functionality.
\nConsider a simple calculator implementation defined in module Calculator.ts.\nThe module also exports a helper function to test the calculator functionality by passing a list of input strings and writing the result at the end.
\ntsexport class Calculator {\n private current = 0;\n private memory = 0;\n private operator: string;\n\n protected processDigit(digit: string, currentValue: number) {\n if (digit >= \"0\" && digit <= \"9\") {\n return currentValue * 10 + (digit.charCodeAt(0) - \"0\".charCodeAt(0));\n }\n }\n\n protected processOperator(operator: string) {\n if ([\"+\", \"-\", \"*\", \"/\"].indexOf(operator) >= 0) {\n return operator;\n }\n }\n\n protected evaluateOperator(\n operator: string,\n left: number,\n right: number\n ): number {\n switch (this.operator) {\n case \"+\":\n return left + right;\n case \"-\":\n return left - right;\n case \"*\":\n return left * right;\n case \"/\":\n return left / right;\n }\n }\n\n private evaluate() {\n if (this.operator) {\n this.memory = this.evaluateOperator(\n this.operator,\n this.memory,\n this.current\n );\n } else {\n this.memory = this.current;\n }\n this.current = 0;\n }\n\n public handleChar(char: string) {\n if (char === \"=\") {\n this.evaluate();\n return;\n } else {\n let value = this.processDigit(char, this.current);\n if (value !== undefined) {\n this.current = value;\n return;\n } else {\n let value = this.processOperator(char);\n if (value !== undefined) {\n this.evaluate();\n this.operator = value;\n return;\n }\n }\n }\n throw new Error(`Unsupported input: '${char}'`);\n }\n\n public getResult() {\n return this.memory;\n }\n}\n\nexport function test(c: Calculator, input: string) {\n for (let i = 0; i < input.length; i++) {\n c.handleChar(input[i]);\n }\n\n console.log(`result of '${input}' is '${c.getResult()}'`);\n}
Here is a simple test for the calculator using the exposed test function.
\ntsimport { Calculator, test } from \"./Calculator\";\n\nlet c = new Calculator();\ntest(c, \"1+2*33/11=\"); // prints 9
Now to extend this to add support for input with numbers in bases other than 10, let’s create ProgrammerCalculator.ts
\ntsimport { Calculator } from \"./Calculator\";\n\nclass ProgrammerCalculator extends Calculator {\n static digits = [\n \"0\",\n \"1\",\n \"2\",\n \"3\",\n \"4\",\n \"5\",\n \"6\",\n \"7\",\n \"8\",\n \"9\",\n \"A\",\n \"B\",\n \"C\",\n \"D\",\n \"E\",\n \"F\"\n ];\n\n constructor(public base: number) {\n super();\n const maxBase = ProgrammerCalculator.digits.length;\n if (base <= 0 || base > maxBase) {\n throw new Error(`base has to be within 0 to ${maxBase} inclusive.`);\n }\n }\n\n protected processDigit(digit: string, currentValue: number) {\n if (ProgrammerCalculator.digits.indexOf(digit) >= 0) {\n return (\n currentValue * this.base + ProgrammerCalculator.digits.indexOf(digit)\n );\n }\n }\n}\n\n// Export the new extended calculator as Calculator\nexport { ProgrammerCalculator as Calculator };\n\n// Also, export the helper function\nexport { test } from \"./Calculator\";
The new module ProgrammerCalculator exports an API shape similar to that of the original Calculator module, but does not augment any objects in the original module.\nHere is a test for our ProgrammerCalculator class:
\ntsimport { Calculator, test } from \"./ProgrammerCalculator\";\n\nlet c = new Calculator(2);\ntest(c, \"001+010=\"); // prints 3
When first moving to a module-based organization, a common tendency is to wrap exports in an additional layer of namespaces.\nModules have their own scope, and only exported declarations are visible from outside the module.\nWith this in mind, namespace provide very little, if any, value when working with modules.
\nOn the organization front, namespaces are handy for grouping together logically-related objects and types in the global scope.\nFor example, in C#, you’re going to find all the collection types in System.Collections.\nBy organizing our types into hierarchical namespaces, we provide a good “discovery” experience for users of those types.\nModules, on the other hand, are already present in a file system, necessarily.\nWe have to resolve them by path and filename, so there’s a logical organization scheme for us to use.\nWe can have a /collections/generic/ folder with a list module in it.
\nNamespaces are important to avoid naming collisions in the global scope.\nFor example, you might have My.Application.Customer.AddForm and My.Application.Order.AddForm — two types with the same name, but a different namespace.\nThis, however, is not an issue with modules.\nWithin a module, there’s no plausible reason to have two objects with the same name.\nFrom the consumption side, the consumer of any given module gets to pick the name that they will use to refer to the module, so accidental naming conflicts are impossible.
\n\nFor more discussion about modules and namespaces see Namespaces and Modules.
\n
All of the following are red flags for module structuring. Double-check that you’re not trying to namespace your external modules if any of these apply to your files:
\nexport namespace Foo { ... } (remove Foo and move everything ‘up’ a level)export namespace Foo { at top-level (don’t think that these are going to combine into one Foo!)