> TypeScript > OOP and Modern JS > Forge Module Harmony: TypeScript CJS/ESM Interop

Forge Module Harmony: TypeScript CJS/ESM Interop

The evolution of JavaScript module systems presents a formidable challenge for developers navigating complex codebases. From the ubiquitous CommonJS (CJS) of Node.js to the modern ECMAScript Modules (ESM) that now dominate the web and much of the backend, the coexistence of these paradigms often creates friction. TypeScript, our trusted compiler, amplifies these intricacies, demanding precise configuration to achieve seamless interoperability.

This article activates a strategic blueprint for resolving the pervasive import/export dilemmas that arise when CJS and ESM converge within a TypeScript project. We decode the underlying mechanisms, illuminate critical tsconfig.json directives, and engineer robust solutions for common and advanced scenarios. Developers often encounter the challenge of reconciling these disparate systems, especially when integrating legacy codebases or third-party libraries within a modern TypeScript environment. Mastering this interoperation is a cornerstone of robust software architecture, deeply intertwined with effective modern object-oriented programming practices and JavaScript integration.

Prepare to transform module conflict into harmonious function. We will arm you with the actionable intelligence to build resilient, forward-compatible TypeScript applications, eliminating the frustration of module resolution errors. Dive in; conquer this frontier of software development.

Published on: 18 October 2026

Deciphering the Module Conflict: CommonJS vs. ESM in TypeScript

We initiate our exploration by firmly grasping the fundamental distinctions between CommonJS (CJS) and ECMAScript Modules (ESM), and how TypeScript interprets their interplay. CJS, the original module system for Node.js, operates synchronously, employing require() for imports and module.exports or exports for defining public interfaces. This synchronous nature perfectly suited Node.js's early design, enabling immediate file loading.

ESM, standardized by ECMAScript, introduces asynchronous loading, static analysis capabilities, and the explicit import and export keywords. Its design fosters tree-shaking, improved tooling, and aligns with browser-native module loading. The core conflict emerges from these divergent philosophies: synchronous vs. asynchronous, dynamic vs. static, and distinct syntaxes.

TypeScript compiles code into JavaScript. When we target an older Node.js version, TypeScript defaults to compiling ESM syntax into CJS-compatible output. However, as Node.js embraces native ESM, and projects increasingly adopt "type": "module" in package.json, the compiler's output and runtime environment often clash. This collision mandates explicit configuration to bridge the module gap, ensuring that what TypeScript compiles aligns precisely with how Node.js or bundlers expect to consume it. We engineer our TypeScript configuration to act as the primary translator, orchestrating smooth communication across these module boundaries. Understanding this foundational tension empowers us to anticipate and resolve integration challenges proactively.

Calibrating TypeScript: Forging Interoperability with tsconfig.json

The tsconfig.json file serves as our central command console for orchestrating module interoperability. Incorrect settings here propagate cascading errors throughout the project. We prioritize several key compiler options to manage the CJS/ESM blend effectively.

First, "module" dictates the module code generation. For Node.js projects targeting modern environments, setting this to "Node16" or "NodeNext" is crucial. These options ensure TypeScript emits JavaScript that respects Node.js's native ESM resolution logic, including conditional exports and the "type" field in package.json. Avoid older values like "CommonJS" or "ESNext" if native Node.js ESM is a primary concern, as they may lack the specific resolution semantics.

Next, "moduleResolution" must align with "module". For "Node16", we set "moduleResolution": "Node16". This instructs TypeScript's module resolver to mimic Node.js's algorithm, including the critical .mjs, .cjs, and .js extensions with "type": "module" considerations. This pairing is non-negotiable for robust interoperability.

Crucially, "esModuleInterop": true is a foundational enabler. It facilitates compatibility by generating synthetic __esModule flags and helper functions during compilation. This allows us to use standard import defaultExport from 'package' syntax for CommonJS modules, even if they originally export via module.exports = .... Without this, importing CJS packages would often require import * as packageName from 'package', leading to less ergonomic code. Paired with "allowSyntheticDefaultImports": true, it provides a smoother, more idiomatic import experience, especially with third-party libraries that adhere to CJS patterns.

Activate these settings to establish a robust foundation for mixed module operations. We engineer our compiler to resolve ambiguity, prevent runtime failures, and foster a unified module ecosystem.

/* tsconfig.json */
{
  "compilerOptions": {
    "target": "ES2022",                     /* Specify ECMAScript target version. */
    "module": "Node16",                     /* Specify module code generation: 'CommonJS', 'ESNext', 'Node16', etc. */
    "moduleResolution": "Node16",           /* Specify how modules are resolved: 'Node', 'Node10', 'Node16', 'bundler', etc. */
    "esModuleInterop": true,                /* Emit additional JavaScript for commonJS compatibility. */
    "allowSyntheticDefaultImports": true,   /* Allow default imports from modules with no default export. */
    "forceConsistentCasingInFileNames": true, /* Ensure that casing is consistent on disk. */
    "strict": true,                         /* Enable all strict type-checking options. */
    "skipLibCheck": true,                   /* Skip type checking all .d.ts files. */
    "outDir": "./dist",                     /* Specify an output directory for compiled code. */
    "rootDir": "./src"                      /* Specify the root directory of source files. */
  },
  "include": ["src/**/*.ts"],             /* Specify an array of filenames or patterns to include in the program. */
  "exclude": ["node_modules"]
}

Navigating Imports & Exports: Practical Strategies for Mixed Modules

Effective module mixing demands specific import and export patterns tailored to the target module system. We engineer our code to explicitly manage these transitions.

When an ESM file needs to consume a CJS module, the presence of "esModuleInterop": true in tsconfig.json simplifies the process dramatically. It allows us to use standard ES import syntax, treating the CJS module as if it had a default export or named exports that align with its module.exports. For instance, a CJS module exporting module.exports = { funcA, funcB } can be imported in an ESM TypeScript file as import { funcA, funcB } from './cjs-module.js'; or import * as cjsModule from './cjs-module.js';.

Conversely, consuming an ESM module from a CJS context presents a more intricate challenge. CJS's synchronous require() cannot directly load ESM's asynchronous structure. The recommended strategy involves using dynamic import() within the CJS module. This transforms the import into an asynchronous operation, which aligns with ESM's loading model. For example, a CJS file would use const esmModule = await import('./esm-module.js'); inside an async function. This approach maintains the CJS module's integrity while providing access to ESM functionalities.

For projects migrating to ESM or requiring dual package support, consider the package.json "type": "module" field. This flag mandates that all .js files within the package are treated as ESM. Files intended as CJS must then explicitly use the .cjs extension. This explicit file extension strategy (

.mjs

for ESM,

.cjs

for CJS) provides robust clarity for Node.js's module loader, eliminating ambiguity and fostering predictable resolution. We decode these patterns to prevent runtime ambiguities and solidify our application's modular foundation.

/* src/cjs-module.js */
// A simple CommonJS module
function greet(name) {
  return `Hello, ${name} from CJS!`
}

module.exports = {
  greet,
  version: '1.0.0'
};

/* src/esm-module.ts */
// A simple ES Module
export function farewell(name: string): string {
  return `Goodbye, ${name} from ESM!`
}

export const author = 'Computational Explorer';

/* src/index.ts */
// Example of ESM importing CJS
import * as cjsModule from './cjs-module.js'; // Requires esModuleInterop: true
// OR: import { greet, version } from './cjs-module.js'; // With esModuleInterop: true

// Example of ESM importing ESM
import { farewell, author } from './esm-module.js';

console.log(cjsModule.greet('World'));
console.log(`CJS Module Version: ${cjsModule.version}`);
console.log(farewell('Reader'));
console.log(`ESM Author: ${author}`);

/* 
   To run an ESM file in a mixed environment, 
   ensure package.json has "type": "module".
   Compile with tsc, then run with node dist/index.js
*/

/* In a CJS context (e.g., legacy file or specific build output) 
   importing an ESM module is more complex and often requires dynamic import().
   This example demonstrates an asynchronous CJS file importing ESM.
*/
/* src/legacy-cjs-app.js */
// CJS file trying to import ESM (via dynamic import for 'esm-module')
const cjsModule = require('./cjs-module'); // Direct CJS require

async function run() {
  console.log(cjsModule.greet('Legacy CJS App'));

  // Dynamically import the ESM module
  const esmModule = await import('./esm-module.js'); 
  console.log(esmModule.farewell('Dynamic ESM User'));
  console.log(`ESM Author (via dynamic import): ${esmModule.author}`);
}

run();

Optimizing Dual Packages & Strategic Bundling for Future Resilience

For library authors or complex applications, achieving true module harmony often involves a dual-package strategy and strategic bundling. We activate these advanced techniques to maximize compatibility and future resilience.

A dual-package strategy involves publishing both CJS and ESM versions of your code. This is accomplished by setting up separate build processes (e.g., using TypeScript's --outDir and different "module" targets) and configuring package.json accordingly. The "exports" field in package.json is the definitive mechanism for this. It dictates how different module systems resolve entry points: "exports": { ".": { "import": "./dist/esm/index.js", "require": "./dist/cjs/index.js" } }. This provides conditional exports, ensuring that ESM consumers load the ESM version and CJS consumers load the CJS version. We employ this field to precisely control module resolution based on the importing environment.

For Node.js projects, setting "type": "module" in package.json is a powerful declarative statement. It designates all .js files within the package as ESM. If CJS files are still required, they must explicitly use the .cjs extension. This explicit naming convention is vital for Node.js's resolver to correctly identify and load modules. Conversely, omitting "type": "module" implies CJS by default, requiring .mjs for ESM files.

Finally, bundlers like Webpack, Rollup, or esbuild can significantly simplify module interoperability challenges. They often abstract away the complexities of CJS/ESM mixing by transforming and optimizing modules into a single, unified output format (e.g., a single ESM bundle or a UMD bundle). While not always necessary for pure Node.js environments, bundlers are indispensable for web applications and for distributing libraries that need broad compatibility across diverse environments. We leverage these tools to generate highly optimized and universally consumable module outputs, consolidating our gains in cross-module compatibility. This holistic approach ensures our TypeScript projects operate with maximal stability and reach.

/* package.json */
{
  "name": "my-mixed-module-package",
  "version": "1.0.0",
  "description": "A package supporting both CommonJS and ESM consumers",
  "main": "./dist/cjs/index.js",       /* Entry point for CommonJS consumers */
  "module": "./dist/esm/index.js",      /* Entry point for ES Module bundlers/consumers */
  "types": "./dist/esm/index.d.ts",     /* TypeScript type definitions */
  "type": "module",                     /* Designates .js files as ESM by default */
  "exports": {
    ".": {
      "import": "./dist/esm/index.js",  /* For ESM consumers */
      "require": "./dist/cjs/index.js", /* For CommonJS consumers */
      "types": "./dist/esm/index.d.ts"
    },
    "./package.json": "./package.json"  /* Explicitly export package.json */
  },
  "scripts": {
    "build": "npm run build:esm && npm run build:cjs",
    "build:esm": "tsc --outDir dist/esm --module ESNext --target ES2020",
    "build:cjs": "tsc --outDir dist/cjs --module CommonJS --target ES2020",
    "start": "node --experimental-specifier-resolution=node dist/esm/index.js" 
  },
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}

Key Takeaways

Module System Fundamentals

Master the core differences: CommonJS (synchronous require/module.exports) and ESM (asynchronous import/export). This foundational knowledge is essential for effective interoperability.

tsconfig.json Directives are Key

Configure "module": "Node16", "moduleResolution": "Node16", and crucially, "esModuleInterop": true (often paired with "allowSyntheticDefaultImports": true). These settings are non-negotiable for resolving module conflicts in TypeScript.

Strategic Import/Export Patterns

Employ standard ES import for CJS modules (with esModuleInterop). Utilize dynamic import() for consuming ESM modules within CJS contexts. Leverage package.json's "type": "module" and explicit file extensions (.mjs, .cjs) for clarity.

Leverage Dual Packages and Bundlers

For libraries or complex applications, implement a dual-package strategy using the "exports" field in package.json. For web applications and broader distribution, integrate bundlers (Webpack, Rollup, esbuild) to abstract and optimize module resolution.

Editorial Team

← Forge Reusable Objects: Inheritance vs. Composition in TypeScript Forge Static Members: TypeScript Utility & Constants Mastery →

FAQ

Why do I get 'SyntaxError: Cannot use import statement outside a module' in Node.js?

This error activates when Node.js attempts to execute an ES Module (using import/export syntax) in a CommonJS context. Node.js interprets .js files as CJS by default unless otherwise specified. To resolve this, ensure your package.json contains "type": "module" at the root level for your project, or explicitly name your ES Module files with the .mjs extension. This explicitly designates the file as an ES Module, allowing Node.js to parse it correctly.
How do I import a CommonJS library that doesn't provide TypeScript types?

We can engineer a solution for untyped CJS libraries. First, attempt to install existing type definitions via npm install --save-dev @types/library-name. If no types exist, manually declare them. Create a .d.ts file (e.g., src/types/library-name.d.ts) and use declare module 'library-name' { ... } for global modules, or declare module './path/to/module' { ... } for local CJS files. For simple cases, declare module 'library-name'; can provide basic compatibility, allowing TypeScript to recognize the module, even without specific type information. Activate this declarative power to extend type safety to untyped modules.
What is the role of `allowSyntheticDefaultImports` and `esModuleInterop` together?

These two tsconfig.json options forge a robust bridge for importing CommonJS modules into an ES Module context. "esModuleInterop": true is the primary enabler; it generates helper code during compilation (e.g., __importDefault) that handles the differences in default export behavior between CJS and ESM. This allows you to use import SomeModule from 'commonjs-module'. "allowSyntheticDefaultImports": true complements this by telling TypeScript that it's safe to assume any module (even CJS ones without an explicit __esModule marker) might have a default export. This provides a more ergonomic and familiar import syntax for CJS modules within your TypeScript ESM codebase, ensuring a smoother development experience.