CommonJS to ES Modules Node.js Migration Challenges

Migrating a legacy CommonJS (CJS) Node.js project to modern ES Modules (ESM) offers benefits like native browser compatibility, standardized syntax, and improved tree-shaking. However, this transition is rarely seamless. This article outlines the primary challenges developers face during the migration process, including syntax incompatibilities, the loss of built-in Node.js globals, strict module resolution rules, and the complexities of handling third-party dependencies.

1. Loss of Node.js Globals (__dirname and __filename)

In CommonJS, developers frequently rely on the injection of global variables like __dirname and __filename to resolve absolute file paths. In ES Modules, these globals do not exist.

To achieve the same functionality in ESM, you must reconstruct these paths using import.meta.url and utility functions from the native path and url modules:

import { fileURLToPath } from 'url';
import { dirname } from 'path';

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

This requires finding and updating every instance of path resolution across your entire codebase.

2. Strict File Extensions and Module Resolution

CommonJS is highly permissive with file imports. It allows developers to omit file extensions (e.g., require('./utils')) and automatically searches for index.js files within directories.

ES Modules enforce strict, explicit path resolution. When using ESM, you must include the file extension for all local imports:

// CommonJS (Works)
const utils = require('./utils');

// ES Modules (Requires explicit extension)
import utils from './utils.js';

For large codebases with thousands of import statements, updating these paths manually is time-consuming and error-prone, often requiring codemods or automated refactoring tools.

3. Synchronous vs. Asynchronous Loading

CommonJS require() is synchronous and can be executed dynamically inside if statements, functions, or loops.

ES Modules are statically analyzed and loaded asynchronously before the code executes. Consequently, import statements must reside at the top level of the file. If you need dynamic loading in ESM, you must use the asynchronous import() function, which returns a Promise:

// CommonJS dynamic loading
if (condition) {
  const config = require('./config.json');
}

// ES Modules dynamic loading (returns a Promise)
if (condition) {
  const config = await import('./config.json', { assert: { type: 'json' } });
}

This forces developers to refactor synchronous execution flows into asynchronous ones, which can trigger a cascade of changes throughout the application.

4. Interoperability and the “Dual Package Hazard”

While ESM can import CommonJS modules, the reverse is not easily achieved. A legacy CommonJS application cannot use require() to load an ES Module; it must use dynamic import().

If your project is a library used by other applications, migrating fully to ESM might break compatibility for your CommonJS users. Maintaining support for both formats (creating a “dual package”) requires complex build configurations using bundlers like Rollup or ts-up, and introduces the risk of the “dual package hazard,” where two different instances of your library are loaded into memory simultaneously.

5. JSON and WASM Imports

In CommonJS, importing JSON files is straightforward using require('./data.json'). In ES Modules, importing JSON requires the use of import attributes (formerly import assertions), which are still evolving in the Node.js ecosystem:

import data from './data.json' with { type: 'json' };

Depending on the Node.js version your project runs on, the syntax for importing JSON or WebAssembly can vary, leading to potential compatibility issues during deployment.