CommonJS vs ES Modules in Node.js — A Complete Guide

The import statement looks cleaner. Everyone says ES Modules are the future. So you add 'type': 'module' to package.json, your Express app crashes with require is not defined, and you spend two hours debugging why __dirname is undefined. The reality is that Node.js runs two parallel module systems, and understanding the difference — not just the syntax — is essential for shipping production code in 2026. CommonJS is not going away, and ES Modules have sharp edges that even experienced engineers hit. This article covers the practical differences, not just the syntax.

Module Systems in Node.js: The Two Standards

Node.js supports two module systems: CommonJS (CJS) and ES Modules (ESM). CommonJS, the original system, uses require() and module.exports. ES Modules, the modern standard, uses import and export. Both coexist, but they differ fundamentally in syntax, behavior, and ecosystem support. Understanding these differences is critical for writing maintainable, performant Node.js applications. CommonJS is synchronous and loads modules at runtime, while ESM is asynchronous and supports static analysis, enabling tree-shaking and better optimization. The Node.js team recommends ESM for new projects, but CommonJS remains widespread in legacy code and npm packages.

// CommonJS
const fs = require('fs');
module.exports = { readFile: fs.readFileSync };

Syntax and Export Differences

CommonJS uses module.exports to export a single value (often an object) and require() to import. ES Modules use named exports (export const) and default exports (export default), imported via import. ESM exports are live bindings — changes to the exported value in the exporting module are reflected in the importing module. CommonJS exports are copies. This distinction matters for mutable objects. Also, ESM supports top-level await, which CommonJS does not. The syntax differences affect how you structure your code and handle dependencies.

// ES Module
export const greet = (name) => `Hello, ${name}!`;
export default function() { return 'default'; }

File Extensions and Package Type

Node.js determines the module system based on file extension and nearest package.json. Files with .mjs are always ESM; .cjs are always CommonJS; .js files default to CommonJS unless the nearest package.json has "type": "module". This setting applies to all .js files in the package. You can override per file with .mjs/.cjs. This flexibility allows gradual migration but can cause confusion when dependencies have mixed types.

{
  "type": "module",
  "dependencies": {
    "lodash": "^4.17.21"
  }
}

Interoperability: Importing CJS from ESM and Vice Versa

ESM can import CommonJS modules using the default import syntax: import pkg from 'cjs-pkg'. Named imports from CJS are also supported via a static analysis of the CJS module's exports. However, CJS cannot use import to load ESM — it must use dynamic import(), which returns a promise. This asymmetry is a common pain point. Also, ESM imports are static and must be at the top level, while import() is dynamic. When migrating a large CJS codebase to ESM, you'll often need to use dynamic imports for ESM modules inside CJS files.

// CommonJS importing ESM
async function loadESM() {
  const esmModule = await import('./esm-module.mjs');
  console.log(esmModule.default());
}
loadESM();

Circular Dependencies: How Each System Handles Them

Circular dependencies occur when module A imports module B, and B imports A (directly or indirectly). CommonJS handles this by returning a partial copy of the module's exports at the time of the require. This can lead to undefined values if the circular dependency is not carefully managed. ES Modules handle circular dependencies better because exports are live bindings — the importing module gets a reference to the exported value, which may still be undefined if the export hasn't been initialized yet. However, both systems can fail if not designed carefully. The best practice is to avoid circular dependencies altogether.

// a.js
const b = require('./b');
console.log(b); // {}
module.exports = { name: 'A' };

// b.js
const a = require('./a');
console.log(a); // { name: 'A' }? No, it's {} because a hasn't finished exporting yet.
module.exports = { name: 'B' };

Performance and Tree-Shaking

ES Modules enable static analysis, which allows bundlers like Webpack and Rollup to perform tree-shaking — removing unused exports to reduce bundle size. CommonJS modules are dynamic, so tree-shaking is harder. In Node.js runtime, ESM has slightly higher startup overhead due to asynchronous loading, but this is negligible for most applications. For server-side code, the performance difference is minimal. However, for libraries published to npm, providing both CJS and ESM builds (dual packages) is common to support all consumers.

// utils.js
export const used = () => 'used';
export const unused = () => 'unused'; // will be removed by tree-shaking

// main.js
import { used } from './utils.js';
console.log(used());

Migrating from CJS to ESM: A Practical Strategy

Migrating a large codebase from CommonJS to ES Modules requires careful planning. Start by setting "type": "module" in package.json and renaming files to .mjs incrementally. Use dynamic import() for CJS files that need to load ESM modules. Update all require() calls to import statements, and change module.exports to export default or named exports. Be aware of differences like __dirname and __filename — in ESM, use import.meta.url and fileURLToPath. Also, note that require.resolve is not available in ESM; use createRequire from module if needed. Test thoroughly, especially for circular dependencies and interop with third-party packages.

import { fileURLToPath } from 'url';
import { dirname } from 'path';
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
console.log(__dirname);

Common Pitfalls and Best Practices

Common pitfalls include: forgetting to add "type": "module", using require in ESM (throws ReferenceError), assuming __dirname exists, and circular dependencies. Best practices: default to ESM for new projects, use named exports, avoid default exports for better tree-shaking, and always specify file extensions in imports (e.g., ./module.js not ./module). For dual-package libraries, use the exports field in package.json to map CJS and ESM entry points. Also, be careful with JSON imports — in ESM, you need to use assert { type: 'json' } (Node 17+) or createRequire.

import data from './config.json' assert { type: 'json' };
console.log(data);

Tooling and Ecosystem Support

Modern tools like TypeScript, Webpack, Rollup, and Jest support both CJS and ESM. TypeScript can output both module types via module compiler option. Jest requires configuration to handle ESM (e.g., transform). ESLint's import plugin works with both. For testing, consider using Node's native test runner or Vitest for ESM-first projects. The npm registry hosts packages in both formats, but many popular packages still ship only CJS. Check the exports field in package.json to see what's available. The ecosystem is moving toward ESM, but CJS will remain for years.

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "node"
  }
}

The Future: ESM as Default

Node.js is moving toward ESM as the default. Starting from Node 22, the --experimental-default-type flag may become stable. The community is pushing for ESM-first packages. However, CommonJS won't disappear soon due to legacy code. As a developer, you should be comfortable with both. For new projects, choose ESM. For existing CJS projects, consider migration if the benefits (tree-shaking, better static analysis, top-level await) outweigh the migration cost. The Node.js documentation recommends ESM for new projects.

node --experimental-default-type=module index.js

Dynamic Imports: import() vs require()

While both import() and require() load modules dynamically, they differ fundamentally in behavior. require() is synchronous and returns the module exports directly. import() is asynchronous and returns a Promise, enabling lazy loading and code splitting. In Node.js, import() works in both CJS and ESM contexts, but require() is only available in CJS. Use import() for conditionally loading modules, especially when the module path is dynamic or when you need to load ESM from CJS. Note that import() always loads the module as ESM, even if the file is CJS, which can cause unexpected behavior if the module uses module.exports.

// CJS file
const { createRequire } = require('module');
const require = createRequire(import.meta.url);

async function loadModule() {
  // Dynamic import (ESM)
  const esmModule = await import('./esm-module.mjs');
  console.log(esmModule.default);

  // Dynamic require (CJS only)
  const cjsModule = require('./cjs-module.cjs');
  console.log(cjsModule);
}

loadModule();

module.createRequire() — Bridging the Gap

When working in ESM, you lose access to require(). To load CJS modules dynamically, use module.createRequire(). This function creates a require function scoped to the current file's URL. It's essential for gradual migration from CJS to ESM, allowing you to keep legacy CJS dependencies while writing new code in ESM. However, avoid overusing it—it's a crutch, not a long-term solution. Prefer rewriting CJS modules to ESM when possible.

// ESM file
import { createRequire } from 'module';
const require = createRequire(import.meta.url);

const lodash = require('lodash');
const result = lodash.chunk(['a', 'b', 'c', 'd'], 2);
console.log(result);

import.meta — Module Metadata in ESM

ESM provides import.meta, an object containing metadata about the current module. The most common property is import.meta.url, which gives the file URL. This replaces __filename and __dirname from CJS. You can derive the directory path using fileURLToPath from the url module. import.meta is also extensible—Node.js adds properties like import.meta.resolve (experimental) for resolving module specifiers. Use import.meta for constructing paths relative to the current module, especially in ESM-only codebases.

// ESM file
import { fileURLToPath } from 'url';
import { dirname } from 'path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

console.log('Current file:', __filename);
console.log('Current dir:', __dirname);

Tree-Shaking Mechanics in ESM vs CJS

Tree-shaking—dead code elimination—works because ESM has static, analyzable imports and exports. Bundlers like Webpack and Rollup can determine which exports are used and remove unused ones. CJS, with its dynamic require() and module.exports, is not statically analyzable, making tree-shaking nearly impossible. For effective tree-shaking, always use named exports (export const foo) rather than default exports, and avoid side effects in modules. Mark your package as "sideEffects": false in package.json to allow aggressive tree-shaking.

// utils.mjs
export const used = () => 'used';
export const unused = () => 'unused'; // Will be tree-shaken

// main.mjs
import { used } from './utils.mjs';
console.log(used());

Package.json Exports Map and Conditional Exports

The exports field in package.json controls how other modules import your package. It replaces the traditional main field and allows subpath exports, conditional exports (based on environment), and preventing access to internal files. Conditional exports let you provide different entry points for different environments (e.g., Node.js vs browser, CJS vs ESM). This is crucial for dual-package hazards where you need to avoid loading the same module twice. Always define both "import" and "require" conditions to support both module systems.

{
  "name": "my-package",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    },
    "./feature": {
      "import": "./dist/feature.mjs",
      "require": "./dist/feature.cjs"
    }
  },
  "sideEffects": false
}

Loader Hooks: Customizing Module Resolution

Node.js ESM loader hooks allow you to intercept and customize module resolution, loading, and transformation. The three main hooks are resolve (modify specifier resolution), load (transform source code), and transform (deprecated, use load instead). These hooks are powerful for transpilation (e.g., TypeScript), aliasing, or mocking. To use them, create a loader file and pass it via --experimental-loader flag. Note: this API is experimental and may change.

// loader.mjs
export async function resolve(specifier, context, defaultResolve) {
  if (specifier === 'debug') {
    return { url: 'file:///dev/null' };
  }
  return defaultResolve(specifier, context, defaultResolve);
}

export async function load(url, context, defaultLoad) {
  const result = await defaultLoad(url, context, defaultLoad);
  if (result.format === 'module') {
    // Transform source (e.g., add logging)
    const transformed = `console.log('Loading: ${url}');\n${result.source}`;
    return { format: 'module', source: transformed };
  }
  return result;
}