Node.js Backend Development Bootcamp · レッスン

CommonJSからネイティブES Modulesへの移行

require/module.exportsをimport/exportに変換し、デュアルパッケージと相互運用性に関する問題に対処します。

「CommonJSからネイティブES Modulesへの移行」はCoddyKit上の無料Node.js Backend Development Bootcampレッスンです。これはレッスン1/4です。下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。これはNode.js Backend Development Bootcamp学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 Node.js Backend Development Bootcampコースには全4レッスンが含まれています。

このレッスンの一部はまだ翻訳されておらず、英語で表示されています。

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.

よくある質問

「CommonJSからネイティブES Modulesへの移行」レッスンは無料ですか？

はい。「CommonJSからネイティブES Modulesへの移行」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、Node.js Backend Development Bootcampコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 Node.js Backend Development Bootcampコースには全4レッスンが含まれています。

「CommonJSからネイティブES Modulesへの移行」で何を学びますか？

require/module.exportsをimport/exportに変換し、デュアルパッケージと相互運用性に関する問題に対処します。ブラウザで直接実行するハンズオンコードでNode.js Backend Development Bootcampを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

Node.js Backend Development Bootcampを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのNode.js Backend Development Bootcampは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。これはレッスン1/4です。

「CommonJSからネイティブES Modulesへの移行」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このNode.js Backend Development Bootcampレッスンでコードを書いて実行できますか？

はい。すべてのNode.js Backend Development Bootcampレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

← Node.js Backend Development Bootcampに戻る