What is a Module?

In TypeScript, a module is a way to organize your code into separate, reusable blocks. Think of it as a self-contained unit with its own scope, preventing naming conflicts and making your project more manageable. Without modules, all your code would exist in a single global scope, which can lead to problems in larger projects.

Setting the Module System: The module Option

The module option in your tsconfig.json file (or specified via the command line using tsc --module [module_system]) tells the TypeScript compiler *how* to transform your TypeScript modules into JavaScript. It determines which module system your generated JavaScript code will use. This is crucial for ensuring your code works correctly in the target environment (e.g., Node.js or a web browser).

Think of the module option as specifying the format in which your code will be packaged and delivered. Different module systems have different ways of defining and importing/exporting modules.

Exploring Different Module Systems

CommonJS (commonjs)

CommonJS is the module system traditionally used in Node.js. It uses require() to import modules and module.exports or exports to export them.

Example:

// myModule.ts
export function add(a: number, b: number): number {
    return a + b;
}

export const message: string = "Hello from myModule!"; 

// main.ts
import { add, message } from './myModule'; // NOT valid CommonJS syntax in TypeScript
const { add: addFn, message: myMessage } = require('./myModule');  //Valid CommonJS equivalent

console.log(addFn(5, 3));  // Output: 8
console.log(myMessage);    // Output: Hello from myModule! 

Important Note: While TypeScript can *compile* code targeting CommonJS, the TypeScript code itself uses ES Module syntax (import and export). The compiler then *transforms* this syntax into CommonJS-compatible require and module.exports statements. The import statement in the first code block is valid TypeScript for CommonJS targets when `esModuleInterop` is set to true (the default in many setups). This setting tells TypeScript to handle the differences between ES Modules and CommonJS modules.

ES Modules (ESM or esnext, es2015, es2020, es2022, etc.)

ES Modules (also known as ECMAScript Modules) are the standard module system for JavaScript and are supported natively by modern browsers and Node.js. They use import and export keywords.

Example:

// myModule.ts
export function multiply(a: number, b: number): number {
    return a * b;
}

export default function greet(name: string): string {
  return `Hello, ${name}!`;
} 

// main.ts
import multiply from './myModule'; //import default function under a new name
import { multiply as mult } from './myModule';  //import the function "multiply" from the module "myModule" and assign it the alias "mult"

console.log(multiply(5, 3));  // Output: 15
console.log(mult(2, 6));      // Output: 12 

Using esnext allows you to use the latest ECMAScript features and relies on a bundler (like Webpack, Parcel, or Rollup) or a modern runtime environment to handle module resolution.

When using es2015, es2020, etc., TypeScript compiles your code to that specific ECMAScript version's module format. This can be useful for targeting older environments that don't fully support the latest features.

For Node.js, you'll likely need to configure your package.json with "type": "module" to explicitly enable ES module support.

UMD (Universal Module Definition)

UMD aims for maximum compatibility. It tries to detect which module system is available (CommonJS, AMD, or global scope) and adapts accordingly. This allows your code to run in a variety of environments without modification.

Example:

// myUmdModule.ts
(function (root, factory) {
    if (typeof define === 'function' && define.amd) {
        // AMD
        define(['exports'], factory);
    } else if (typeof module === 'object' && module.exports) {
        // CommonJS
        factory(exports);
    } else {
        // Global (Browser)
        factory(root.myUmdModule = {});
    }
}(typeof self !== 'undefined' ? self : this, function (exports) {
    exports.myFunction = function () {
        return "Hello from UMD!";
    };
})); 

// Usage in a browser (assuming the script is loaded)
console.log(myUmdModule.myFunction()); // Output: Hello from UMD!

// Usage in Node.js (CommonJS)
const myUmdModule = require('./myUmdModule');
console.log(myUmdModule.myFunction()); // Output: Hello from UMD! 

Using UMD often increases the complexity of the module definition itself and is less commonly needed with the increasing support for ES Modules.

Note: The above example is for demonstration. TypeScript with the UMD module format doesn't directly generate this complex UMD wrapper. Instead, you typically write your module using ES Module syntax (import/export), and then configure your bundler (like Webpack) to output a UMD bundle.

Choosing the Right Module System

The best module system depends on your target environment:

• Node.js: Use CommonJS (commonjs) if you're targeting older versions of Node.js. Otherwise, use ES Modules (esnext, es2020, etc.) with the appropriate package.json configuration.
• Browsers: ES Modules (esnext, or a specific ES version) are generally the best choice, often used in conjunction with a bundler like Webpack, Parcel, or Rollup. Bundlers allow you to combine multiple modules into optimized bundles for the browser.
• Universal Libraries: If you need your library to work in a variety of environments without requiring the user to set up a bundler, UMD (umd) can be a good option, but be aware of the added complexity.

Configuring tsconfig.json

Here's a basic tsconfig.json example using ES Modules:

{
  "compilerOptions": {
    "target": "es5",       // Set to your desired target ECMAScript version
    "module": "esnext",      // Use ES Modules
    "moduleResolution": "node", // How modules are resolved
    "esModuleInterop": true,  // Enables interoperability between CommonJS and ES Modules
    "strict": true,         // Enable strict type checking
    "outDir": "./dist",      // Output directory for compiled JavaScript
    "sourceMap": true       // Generate source maps for debugging
  },
  "include": ["src/**/*"]   // Include all TypeScript files in the 'src' directory
}