TypeScript Module Systems Explained

Understanding module systems is essential for TypeScript projects. Here's how they work and how to configure them.

Module Formats#

// ES Modules (ESM) - Modern standard
export const value = 42;
export function greet(name: string) {
  return `Hello, ${name}`;
}
export default class User {}

import { value, greet } from './module';
import User from './module';
import * as utils from './module';

// CommonJS (CJS) - Node.js traditional
module.exports = { value: 42 };
module.exports.greet = function(name) { return `Hello, ${name}`; };

const { value, greet } = require('./module');

// TypeScript emits based on tsconfig "module" setting

tsconfig Module Options#

// tsconfig.json
{
  "compilerOptions": {
    // Module system for output
    "module": "esnext",       // ES modules
    // "module": "commonjs",  // CommonJS
    // "module": "node16",    // Node.js ESM support

    // Module resolution strategy
    "moduleResolution": "bundler",   // Modern bundlers
    // "moduleResolution": "node16", // Node.js
    // "moduleResolution": "node",   // Legacy Node.js

    // Allow default imports from CJS
    "esModuleInterop": true,

    // Allow importing JSON
    "resolveJsonModule": true,

    // Type-only imports
    "verbatimModuleSyntax": true,

    // Path aliases
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"]
    }
  }
}

ES Modules in Node.js#

// package.json
{
  "name": "my-package",
  "type": "module",  // Enable ESM
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    },
    "./utils": {
      "import": "./dist/utils.js",
      "types": "./dist/utils.d.ts"
    }
  },
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts"
}

// tsconfig.json for Node.js ESM
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "node16",
    "moduleResolution": "node16",
    "outDir": "dist",
    "declaration": true,
    "esModuleInterop": true,
    "strict": true
  }
}

// Note: Must use .js extensions in imports
import { helper } from './utils.js';  // Even for .ts files

Import/Export Patterns#

// Named exports
export const API_URL = 'https://api.example.com';
export type User = { id: string; name: string };
export interface Config { debug: boolean }
export function fetchData() {}
export class ApiClient {}

// Default export
export default function main() {}

// Re-exports
export { helper } from './helper';
export * from './utils';
export * as utils from './utils';
export { default as Button } from './Button';

// Type-only imports (TypeScript 3.8+)
import type { User } from './types';
import { type Config, fetchData } from './api';

// Import assertions (for JSON, etc.)
import data from './data.json' assert { type: 'json' };

// Dynamic imports
const module = await import('./heavy-module');
const { feature } = await import(`./features/${name}`);

CommonJS Interoperability#

// tsconfig.json
{
  "compilerOptions": {
    "esModuleInterop": true,  // Enable interop
    "allowSyntheticDefaultImports": true
  }
}

// Without esModuleInterop
import * as express from 'express';
const app = express();

// With esModuleInterop
import express from 'express';
const app = express();

// Import CommonJS module
import cjsModule from 'cjs-package';

// Import CJS with named exports
import { namedExport } from 'cjs-package';

// When authoring dual packages
// index.ts
export function helper() {}
export default helper;

// Compiles to CJS that works both ways:
// const { helper } = require('package');
// import { helper } from 'package';
// import helper from 'package';

Path Aliases#

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"],
      "@types": ["src/types/index"]
    }
  }
}

// Usage
import { Button } from '@components/Button';
import { formatDate } from '@utils/date';
import type { User } from '@types';

// For bundlers, configure alias resolution:

// vite.config.ts
import { defineConfig } from 'vite';
import path from 'path';

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'),
      '@components': path.resolve(__dirname, 'src/components'),
    },
  },
});

// webpack.config.js
module.exports = {
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'),
    },
  },
};

// jest.config.js
module.exports = {
  moduleNameMapper: {
    '^@/(.*)$': '<rootDir>/src/$1',
  },
};

Barrel Files#

// components/index.ts (barrel file)
export { Button } from './Button';
export { Card } from './Card';
export { Modal } from './Modal';
export type { ButtonProps } from './Button';

// Usage
import { Button, Card, Modal } from '@/components';

// Caution: Can hurt tree-shaking and build performance

// Better for large projects: direct imports
import { Button } from '@/components/Button';

// Or selective barrel exports
// components/forms/index.ts
export { Input } from './Input';
export { Select } from './Select';

// Import specific barrel
import { Input, Select } from '@/components/forms';

Module Augmentation#

// Extend existing module
declare module 'express' {
  interface Request {
    user?: User;
    session?: Session;
  }
}

// Extend global
declare global {
  interface Window {
    analytics: Analytics;
  }

  namespace NodeJS {
    interface ProcessEnv {
      NODE_ENV: 'development' | 'production';
      API_URL: string;
    }
  }
}

// Must export to make it a module
export {};

// Extend third-party types
import 'styled-components';

declare module 'styled-components' {
  export interface DefaultTheme {
    colors: {
      primary: string;
      secondary: string;
    };
  }
}

Dual Package Publishing#

// Build both ESM and CJS
// tsup.config.ts
import { defineConfig } from 'tsup';

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['cjs', 'esm'],
  dts: true,
  splitting: false,
  sourcemap: true,
  clean: true,
});

// package.json
{
  "name": "my-library",
  "version": "1.0.0",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": {
        "types": "./dist/index.d.ts",
        "default": "./dist/index.js"
      },
      "require": {
        "types": "./dist/index.d.cts",
        "default": "./dist/index.cjs"
      }
    }
  },
  "files": ["dist"]
}

Best Practices#

Configuration:
✓ Use "moduleResolution": "bundler" for apps
✓ Use "moduleResolution": "node16" for Node.js
✓ Enable esModuleInterop
✓ Use verbatimModuleSyntax

Imports:
✓ Use type-only imports when possible
✓ Prefer named exports over default
✓ Use path aliases consistently
✓ Avoid deep barrel re-exports

Publishing:
✓ Ship both ESM and CJS
✓ Include type definitions
✓ Use exports field properly
✓ Test in both module systems

Understanding TypeScript's module systems helps you configure projects correctly and write interoperable code. Use ES Modules for modern projects, configure esModuleInterop for CommonJS compatibility, and set up proper dual-package exports when publishing libraries.