TypeScript is an amazing substitute for JavaScript that solves a bunch of significant problems that are surprisingly common in large JavaScript code bases. But, by solving those problems, it also creates a new one: it's now easier than ever to create larger and more complex code bases. It turns out that accommodating that complexity while supporting all the different JavaScript environments is quite a challenge. Which is why TypeScript has multiple module systems, unfortunately with confusing names and poor guidance. In this session, we sort out the mess and talk about the differences between internal and external modules, writing client and server code, how the TypeScript modules map to JavaScript modules in different versions of JavaScript, and about integration with build tools like Gulp. These are the slides for the talk I gave at the JavaScript Israel Meetup: http://www.meetup.com/JavaScript-Israel/events/228923402/

1. TYPESCRIPT
MODULES

2. Noam Kfir
■ SeniorArchitect at Sela
■ Front-End.IL Meetup organizer
■ Telerik Developer Expert
■ @NoamKfir
■ noam@kfir.cc

3. WhatAre Modules
■ Prevent name collisions
■ Group constructs logically
– Organization
– Namespacing
– Encapsulation
■ Implemented as scoped JavaScript objects

4. Superset of JavaScript
■ TypeScript has to work where JavaScript works
■ But module definitions differ:
CommonJS
Node.js
AMD
RequireJS
ECMAScript
6/2015
SystemJS
Custom
Modules
Different JS
Versions

5. Internal Modules
Represent namespaces
• The module name unrelated to file name
• Can be nested
Provide scope
• Declarations inside the module are private
• Can be exposed with the export keyword

6. Internal Modules - Syntax
module Internal {
export class B extends A {
a: A = new A();
}
}

7. Internal Modules -Type
Information
■ The compiler needs to know where to find the type info
/// <reference path="source.ts" />
– Compiler follows references, determines order
■ Or use tsconfig.json to create aTypeScript project
– Automatically sees all files in the directory

8. Internal Modules - Merging
■ Multiple files can define the same module
■ The compiler merges the individual modules
■ Scope is determined by original unmerged module
– Not shared

9. External Modules
Represent grouped constructs
• Module name defined by file name
• Don't need namespaces
Provide scope
• Declarations inside the module are private
• Can be exposed with the export keyword

10. Module Loaders
■ TypeScript doesn’t implement the module system itself
■ Uses module loaders instead
■ Unifies module declaration for external module loaders
■ Available loaders:
commonjs amd umd system es6

11. External Modules - Syntax
import m = require('mod');
export var t = m.something + 1;

12. Transpiled to AMD
define(['require', 'exports', 'mod'],
function(require, exports, m) {
exports.t = m.something + 1;
}
);

13. Transpiled to CommonJS
var m = require('mod');
exports.t = m.something + 1;

14. Aliases
■ Aliases are just shortcuts
■ Help shorted access to nested constructs
■ Can’t be combined with regular import
import foo = mod.foo;
class B {
a: A = foo;
}

15. Export = Syntax
■ External module syntax can be cumbersome
■ Export = syntax exports a single unqualified value
– Class, interface, module, function, enum
import A = require('./A');
class B {
a: A = new A();
}
export = B

16. ES6 Modules
■ External modules using ES6 syntax
■ More succinct than the regular external module syntax
■ More flexible than the the export = syntax

17. ES6 Modules – Syntax
• Exporting (from “A.ts”)
export class A {}
• Importing (to “B.ts”)
import { A } from './A';
export class B {
a: A = new A();
}

18. ES6 Modules – Default
Members
• Exporting (from “A.ts”)
export default class {}
• Importing (to “B.ts”)
import A from './A';
export class B {
a: A = new A();
}

19. Optional Module Loading
■ require() emitted only if a module is actually used at run time
■ If only type info is needed, require() isn’t emitted
■ Useful for type safety

20. Ambient Modules
■ Modules defined in type definition files – .d.ts
■ Provide type info for non-TypeScript files
■ Can be internal or external
■ Internal – mainly for client scripts
■ External –helps build larger definitions in one file

21. Ambient Internal Module –
D3.d.ts (simplified excerpt)
declare module D3 {
export interface Selectors {
select: { (selector: string): Selection; }
}
export interface Event {
x: number;
y: number;
}
}
declare var d3: D3.Base;

22. Ambient External Module –
node.d.ts (simplified extract)
declare module "url" {
export interface Url {
protocol?: string; hostname?: string;
}
export function parse(urlStr: string, …): Url;
}
declare module "path" {
export function join(...paths: any[]): string;
}

23. .ts file
• import x = require("name");
• top-level import/export declarations
.d.ts file
• like #1
• declaration file with top-level import/export
Ambient external module declaration
• find module by quoted name
LocatingType Info

24. Declaration Merging
■ Same kind
– module, class, interface, function, value
■ Different kinds
– module/class
– module/function
– module/enum

25. THANKYOU!
Noam Kfir
@NoamKfir
noam@kfir.cc