How do I migrate from CommonJS to ES Modules?

Step-by-step migration: 1) Add 'type': 'module' to package.json, 2) Rename .js files to .mjs or keep .js with type field, 3) Replace require() with import statements, 4) Replace module.exports with export statements, 5) Add file extensions to all imports (.js), 6) Update __dirname and __filename usage, 7) Test thoroughly. Migrate gradually, starting with new code or leaf modules.

Can I use both CommonJS and ES Modules in the same project?

Yes, you can mix them during migration. Use .mjs for ES Modules and .cjs for CommonJS files. ESM can import CommonJS with default imports, but CommonJS must use dynamic import() to load ESM. However, avoid long-term mixing - plan to fully migrate for consistency and better tooling support.

What happens to __dirname and __filename in ES Modules?

ES Modules don't have __dirname and __filename. The classic approach uses: import { fileURLToPath } from 'url'; import { dirname } from 'path'; const __filename = fileURLToPath(import.meta.url); const __dirname = dirname(__filename). In Node.js 21.2+ (stable in Node 22 LTS), you can use import.meta.dirname and import.meta.filename directly with no imports needed.

Should I migrate my existing project to ES Modules?

Consider migrating if: 1) You want better tree-shaking and bundle optimization, 2) Your project is actively developed and will benefit from modern tooling, 3) You're starting a new major version. Don't migrate if: 1) Project is stable and rarely updated, 2) Dependencies don't support ESM, 3) Migration risk outweighs benefits. For new projects, always start with ESM.

CommonJS to ES Modules Migration Guide

6-Step Migration Checklist

Add "type": "module" to package.json

This makes all .js files ES Modules by default

Replace require() with import

Convert all CommonJS imports to ES Module syntax

Replace module.exports with export

Use named or default exports

Add .js extensions to imports

ES Modules require explicit file extensions

Replace __dirname and __filename

Use import.meta.url instead

Test thoroughly

Run your test suite and check for errors

Before & After Examples

❌ CommonJS (Before)

// utils.js
const helper = require('./helper');

function add(a, b) {
  return a + b;
}

module.exports = { add };

✅ ES Modules (After)

// utils.js
import helper from './helper.js';

export function add(a, b) {
  return a + b;
}

Common Pitfalls & Solutions

❌ Problem: Missing file extensions

import utils from './utils'; // Error!

✅ Solution: Add .js extension

import utils from './utils.js';

❌ Problem: __dirname not defined

const path = __dirname + '/file.txt'; // Error!

✅ Solution: Use import.meta.url

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

Simpler in Node.js 22+:

// Node.js 21.2+ provides these directly
const __dirname = import.meta.dirname;
const __filename = import.meta.filename;
// No imports needed!

❌ Problem: Dynamic require()

const mod = require(`./${name}.js`); // Error!

✅ Solution: Use dynamic import()

const mod = await import(`./${name}.js`);

Gradual Migration Strategy

You can migrate gradually using the dual package approach:

package.json

{
  "type": "module",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  }
}

This allows your package to work with both CommonJS and ES Module consumers.

The 2026 Interop Landscape

The CJS-to-ESM migration story has improved significantly:

require(esm) - Node.js 22+ can require() ES Modules directly (default in Node 23+), reducing the urgency of full migration
Deno 2.x - Full npm/Node.js backwards compatibility while being ESM-native
Bun - Seamless CJS/ESM interop with no configuration needed
TypeScript 5.8+ - --rewriteRelativeImportExtensions auto-rewrites .ts to .js in imports

Should You Still Migrate?

Yes. While interop has improved, ESM is the standard going forward. New packages increasingly ship ESM-only, and ESM enables better tree-shaking, static analysis, and tooling support.

Automated Migration Tools

Several tools can automate the mechanical parts of CJS-to-ESM conversion:

cjs-to-esm

Converts require() to import and module.exports to export. Handles most common patterns automatically.

npx cjs-to-esm ./src

jscodeshift / codemods

AST-based transform toolkit for large-scale codebase migrations. Write custom transforms for project-specific patterns.

Tip: Automated tools handle ~80% of conversions. Always review the output and test thoroughly - edge cases like conditional require() and dynamic paths need manual attention.

Migration Guide