Migrate from CommonJS to ES Modules

Intermediate15 min

Convert a Node.js project from require/module.exports to import/export syntax with proper configuration.

Prerequisites

-Node.js 16 or later
-Existing CommonJS project

Steps

Set module type in package.json

Add the type field to package.json to tell Node.js to treat .js files as ES modules by default.

$ npm pkg set type=module

With type: module, all .js files use ESM. Use .cjs extension for files that must remain CommonJS.

Convert require statements to import

Replace require() calls with import statements and module.exports with export.

$ # Before (CommonJS): # const express = require('express'); # const { readFile } = require('fs/promises'); # module.exports = { handler }; # After (ESM): # import express from 'express'; # import { readFile } from 'fs/promises'; # export { handler };

Fix dirname and filename references

Replace __dirname and __filename with ESM equivalents since these globals do not exist in ES modules.

$ cat <<'EOF' // Add this to files that need __dirname or __filename: import { fileURLToPath } from 'url'; import { dirname } from 'path'; const __filename = fileURLToPath(import.meta.url); const __dirname = dirname(__filename); EOF

__dirname and __filename are not available in ESM. Every file that uses them needs the import.meta.url workaround.

Add file extensions to relative imports

ESM requires explicit file extensions on relative imports. Update all local import paths.

$ # ESM requires extensions on relative imports: # Before: import { handler } from './routes/api' # After: import { handler } from './routes/api.js' # Find all relative imports missing extensions: grep -rn "from '\./" src/ --include='*.js' | grep -v "\.js'" | grep -v "\.json'"

This is the most tedious part. Every relative import must include .js even if the source file is .ts (TypeScript resolves .js to .ts).

Handle JSON imports

JSON imports require an import assertion in ESM mode.

$ # Before (CommonJS): # const config = require('./config.json'); # After (ESM) - Node 20+: import config from './config.json' with { type: 'json' }; # After (ESM) - Node 16-19: import { createRequire } from 'module'; const require = createRequire(import.meta.url); const config = require('./config.json');

The createRequire workaround works on all Node.js versions and is useful for packages that only support CommonJS.

Full Script

full-script.sh

#!/bin/bash
set -euo pipefail

# CommonJS to ESM Migration Helper

echo "==> Analyzing project for CJS patterns..."

echo ""
echo "==> require() calls found:"
grep -rn "require(" src/ --include='*.js' --include='*.ts' 2>/dev/null | wc -l

echo ""
echo "==> module.exports found:"
grep -rn "module.exports" src/ --include='*.js' --include='*.ts' 2>/dev/null | wc -l

echo ""
echo "==> __dirname/__filename usage:"
grep -rn "__dirname|__filename" src/ --include='*.js' --include='*.ts' 2>/dev/null | wc -l

echo ""
echo "==> Relative imports missing .js extension:"
grep -rn "from '\./\|from "\.\./" src/ --include='*.js' --include='*.ts' 2>/dev/null | grep -v "\.js['"]" | grep -v "\.json['"]" | grep -v "\.mjs['"]" | wc -l

echo ""
echo "==> JSON requires:"
grep -rn "require.*\.json" src/ --include='*.js' --include='*.ts' 2>/dev/null | wc -l

echo ""
echo "Migration steps:"
echo "  1. Run: npm pkg set type=module"
echo "  2. Rename files that must stay CJS to .cjs"
echo "  3. Convert require() -> import"
echo "  4. Convert module.exports -> export"
echo "  5. Replace __dirname with import.meta.url"
echo "  6. Add .js extensions to relative imports"
echo "  7. Update JSON imports with assertions"
echo "  8. Run: node --experimental-vm-modules app.js (if using vm)"

FAQ

Discussion

Loading comments...

#!/bin/bash set -euo pipefail # CommonJS to ESM Migration Helper echo "==> Analyzing project for CJS patterns..." echo "" echo "==> require() calls found:" grep -rn "require(" src/ --include='*.js' --include='*.ts' 2>/dev/null | wc -l echo "" echo "==> module.exports found:" grep -rn "module.exports" src/ --include='*.js' --include='*.ts' 2>/dev/null | wc -l echo "" echo "==> __dirname/__filename usage:" grep -rn "__dirname|__filename" src/ --include='*.js' --include='*.ts' 2>/dev/null | wc -l echo "" echo "==> Relative imports missing .js extension:" grep -rn "from '\./\|from "\.\./" src/ --include='*.js' --include='*.ts' 2>/dev/null | grep -v "\.js['"]" | grep -v "\.json['"]" | grep -v "\.mjs['"]" | wc -l echo "" echo "==> JSON requires:" grep -rn "require.*\.json" src/ --include='*.js' --include='*.ts' 2>/dev/null | wc -l echo "" echo "Migration steps:" echo " 1. Run: npm pkg set type=module" echo " 2. Rename files that must stay CJS to .cjs" echo " 3. Convert require() -> import" echo " 4. Convert module.exports -> export" echo " 5. Replace __dirname with import.meta.url" echo " 6. Add .js extensions to relative imports" echo " 7. Update JSON imports with assertions" echo " 8. Run: node --experimental-vm-modules app.js (if using vm)"

Migrate from CommonJS to ES Modules

Prerequisites

Steps

Set module type in package.json

Convert require statements to import

Fix __dirname and __filename references

Add file extensions to relative imports

Handle JSON imports

Full Script

FAQ

Discussion

Migrate from CommonJS to ES Modules

Prerequisites

Steps

Set module type in package.json

Convert require statements to import

Fix __dirname and __filename references

Add file extensions to relative imports

Handle JSON imports

Full Script

FAQ

Discussion

Fix dirname and filename references

Fix dirname and filename references