Node.js Backend Development Bootcamp · Lesson

Migrating from CommonJS to Native ES Modules

Convert require/module.exports to import/export and handle dual-package and interop pitfalls.

Migrating from CommonJS to Native ES Modules is a free Node.js Backend Development Bootcamp lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Node.js Backend Development Bootcamp learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Two Module Systems, One Runtime

Node.js historically used CommonJS (CJS): you load code with require() and expose it with module.exports. Modern JavaScript has a built-in standard, ES Modules (ESM), using import and export.

CommonJS loads modules synchronously at runtime.
ESM is statically analyzed, loaded asynchronously, and is the official ECMAScript standard.

Node now supports both, but mixing them has rules. This lesson walks you through migrating a backend project from CJS to native ESM cleanly.

// CommonJS (old)
const fs = require('fs');
module.exports = { readConfig };

// ES Modules (new)
import fs from 'fs';
export { readConfig };

Telling Node You Mean ESM

Node decides how to treat a file based on its extension and the nearest package.json:

"type": "module" in package.json → .js files are treated as ESM.
No type field (or "commonjs") → .js files are CommonJS.
.mjs is always ESM; .cjs is always CommonJS, regardless of type.

The cleanest migration step is adding "type": "module" once, then fixing the files it breaks.

{
  "name": "my-api",
  "version": "1.0.0",
  "type": "module",
  "main": "src/server.js",
  "scripts": {
    "start": "node src/server.js"
  }
}

Converting Exports

Replace module.exports and exports.foo with export statements.

module.exports = X (single value) → export default X.
exports.foo = ... (multiple named) → export const foo = ... or a grouped export { foo, bar }.

Prefer named exports for utilities so consumers get autocompletion and clearer imports.

// Before (CJS)
// module.exports.add = (a, b) => a + b;
// module.exports.PI = 3.14159;

// After (ESM)
export const add = (a, b) => a + b;
export const PI = 3.14159;

console.log(add(2, 3)); // 5
console.log(PI);        // 3.14159

Converting Imports

Replace require() with import. Match the export style:

Named: const { add } = require('./math') → import { add } from './math.js'.
Default: const express = require('express') → import express from 'express'.

Critical rule: in ESM, relative imports of your own files must include the file extension (.js). Node will not guess it for you like CommonJS did.

// Before (CJS)
// const { add } = require('./math');

// After (ESM) — note the explicit .js extension
import { add } from './math.js';

console.log(add(10, 5)); // 15

No More dirname or filename

ESM does not provide the CommonJS globals __dirname and __filename. If your backend builds file paths (config, uploads, templates), you must recreate them from import.meta.url.

Modern Node (20.11+) also exposes import.meta.dirname and import.meta.filename directly, which is the simplest option going forward.

import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';

// Classic portable approach
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

const configPath = join(__dirname, 'config.json');
console.log(configPath);

// Node 20.11+ shortcut:
// const dir = import.meta.dirname;

Importing JSON and Built-ins

Two more changes that bite backend projects:

JSON: require('./data.json') no longer works directly. Use an import attribute: import data from './data.json' with { type: 'json' }.
Core modules: prefer the node: prefix (e.g. import { readFile } from 'node:fs/promises'). It is unambiguous and future-proof.

If you target older Node, reading JSON via fs avoids attribute-syntax compatibility concerns entirely.

import { readFile } from 'node:fs/promises';

// Robust, version-agnostic way to load JSON in ESM
const raw = await readFile(new URL('./pkg.json', import.meta.url));
const pkg = JSON.parse(raw);
console.log(pkg.name);

Top-Level await Is a Superpower

One genuine upgrade ESM gives backend code: top-level await. In CommonJS you had to wrap async startup in an IIFE. In an ESM module you can await directly at the top level.

This makes database connections, config fetching, and warm-up logic much cleaner in server entry files.

// ESM entry file
async function connectDb() {
  await new Promise((r) => setTimeout(r, 50));
  return { status: 'connected' };
}

const db = await connectDb(); // top-level await — no IIFE needed
console.log('DB:', db.status);

Interop: ESM Importing CommonJS

You will still depend on CJS-only npm packages. Good news: ESM can import CommonJS. Node wraps the package's module.exports as the default export.

Use import pkg from 'cjs-lib' to get module.exports.
Node tries to detect named exports too, but for complex CJS this can fail — destructure from the default instead.

// 'lodash' is CommonJS; the whole export object is the default
import _ from 'lodash';

const { chunk } = _; // safe: destructure from default
console.log(chunk([1, 2, 3, 4], 2)); // [[1,2],[3,4]]

Interop: CommonJS Loading ESM

The reverse is harder. A CommonJS file cannot require() an ESM module synchronously (older Node throws ERR_REQUIRE_ESM). Options:

Use a dynamic import(), which returns a Promise — works from inside async functions in CJS.
Node 22+ added experimental synchronous require() of ESM, but don't rely on it for portable code.

This asymmetry is the main reason teams migrate the whole codebase to ESM rather than mixing.

// Inside a CommonJS file:
async function run() {
  // dynamic import works even from CJS
  const { add } = await import('./math.mjs');
  console.log(add(4, 6)); // 10
}

run();

Dual-Package Publishing

If you publish a library, some users are ESM and some are CJS. The modern solution is the exports field with conditional exports, shipping both builds.

import condition → the ESM entry.
require condition → the CJS entry.

Beware the dual-package hazard: if both builds get loaded, you get two copies of your module state (e.g. two separate singletons). Keep stateful logic in a single internal module both builds import.

{
  "name": "my-lib",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    }
  }
}

A Pragmatic Migration Checklist

A reliable order of operations for an existing backend:

Add "type": "module" to package.json.
Rename any file that must stay CJS to .cjs.
Convert require/module.exports to import/export.
Add .js extensions to all relative imports.
Replace __dirname/__filename with import.meta helpers.
Fix JSON imports and CJS-default interop.
Run the test suite; let failures point to remaining require calls.

Tools like cjstoesm or codemods can automate the bulk edits, but always review the diff.

Quick Check

You convert a backend file to ESM and add "type": "module". Suddenly an import of your own helper throws ERR_MODULE_NOT_FOUND. What is the most likely fix?

Recap

You migrated a Node.js backend from CommonJS to native ES Modules. Key takeaways:

Opt in with "type": "module"; use .cjs/.mjs to override per file.
Swap require/module.exports for import/export, and always include the .js extension on relative imports.
Recreate __dirname via import.meta.url (or use import.meta.dirname).
ESM can import CJS (as default export); CJS must use dynamic import() for ESM.
Top-level await simplifies async startup.
For libraries, use conditional exports and beware the dual-package hazard.

With these rules, you can confidently modernize any Node service to standard ES Modules.

Frequently asked questions

Is the “Migrating from CommonJS to Native ES Modules” lesson free?

Yes — the full text of “Migrating from CommonJS to Native ES Modules” is free to read here on the web, and the Node.js Backend Development Bootcamp course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Node.js Backend Development Bootcamp course, upgrade to CoddyKit PRO.

What will I learn in “Migrating from CommonJS to Native ES Modules”?

Convert require/module.exports to import/export and handle dual-package and interop pitfalls. You practise Node.js Backend Development Bootcamp with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Node.js Backend Development Bootcamp?

No prior experience is required. Node.js Backend Development Bootcamp on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Migrating from CommonJS to Native ES Modules” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Node.js Backend Development Bootcamp lesson?

Yes. Every Node.js Backend Development Bootcamp lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

Migrating from CommonJS to Native ES Modules
Configuring tsconfig for Node Backend Projects
Type-Safe Environment Config and Runtime Validation
Fast Iteration with tsx, Hot Reload, and Source Maps

← Back to Node.js Backend Development Bootcamp