CommonJS против ESM

CommonJS: синхронно, резолв в рантайме, копия значений

CommonJS (CJS) — изначальная модульная система Node. Ты тянешь модуль через require() — обычную функцию, которая работает во время выполнения твоего кода: она читает целевой файл с диска, выполняет его и возвращает то, что файл присвоил в module.exports. Поскольку это обычный вызов функции, ты можешь require() условно, внутри if, или собрать путь в рантайме — резолв динамический и идёт строка за строкой.

// math.cjs
function add(a, b) { return a + b; }
let calls = 0;
module.exports = { add, get calls() { return calls; }, bump() { calls++; } };

// app.cjs
const math = require("./math.cjs");   // синхронно: блокирует, пока math.cjs не выполнится
console.log(math.add(2, 3));          // 5
const { add } = math;                 // копия значения — `add` это снимок биндинга

Важны два свойства. Первое: require() синхронен и блокирующий — вызывающая строка не продолжается, пока требуемый файл не отработает полностью; поэтому старт CJS — это обход дерева зависимостей в глубину. Второе: ты получаешь обратно копию значения на момент require. Если ты деструктурируешь const { add } = require(...), ты захватил ссылку, существовавшую тогда; если модуль позже переприсвоит module.exports.add, твой add не изменится. CJS также бесплатно даёт каждому модулю две path-глобали — __dirname и __filename — потому что резолв локальный и в рантайме.

ESM: статический, поднятый, асинхронный, с живыми биндингами

ECMAScript Modules (ESM) — это стандарт. Ты объявляешь зависимости через import/export, которые статичны: они обязаны быть на верхнем уровне (не внутри if и не в функции), чтобы движок нашёл каждый импорт до того, как выполнится хоть строка кода. Этот предварительный анализ — и есть весь смысл: он строит полный граф модулей, поднимает импорты и позволяет бандлерам точно видеть, какие экспорты используются, чтобы выбросить остальное (tree-shaking). Загрузка графа асинхронна — это и разблокирует top-level await.

// math.mjs
let calls = 0;
export function add(a, b) { return a + b; }
export function bump() { calls++; }
export function getCalls() { return calls; }

// app.mjs
import { add, bump, getCalls } from "./math.mjs";   // поднят, резолвится до запуска
import { readFile } from "node:fs/promises";

const config = await readFile("config.json", "utf8"); // top-level await — без async-обёртки
console.log(add(2, 3));   // 5
bump();
console.log(getCalls());  // 1 — живой биндинг отражает изменение

Импортируемые экспорты — это живые биндинги, а не копии: import { add } — это read-only вид на переменную экспортирующего модуля. Если тот модуль мутирует значение за именем, твой импорт видит новое значение — а сам ты переприсвоить импортированное имя не можешь (add = ... это TypeError). Нет __dirname; вместо этого пути выводят из import.meta.url (например, new URL("./data.json", import.meta.url)).

Как Node решает, какая система у файла

Node не угадывает по содержимому. Он классифицирует каждый файл как CJS или ESM по явному набору сигналов в порядке приоритета:

• Расширение перекрывает всё. .mjs — всегда ESM; .cjs — всегда CJS. Они побеждают остальное и являются однозначным запасным выходом.
• Поле "type" в ближайшем package.json. Для обычного .js-файла Node идёт вверх к ближайшему package.json: "type": "module" делает .js-файлы ESM, "type": "commonjs" (или отсутствие поля) делает их CJS. Переключение этого одного поля переинтерпретирует каждый .js-файл в пакете — именно поэтому require is not defined появляется в тот момент, когда ты его добавляешь.
• Поле "exports" управляет тем, во что резолвятся import "pkg" и require("pkg"), и через условные exports может отдавать разный файл каждому — паттерн dual-package.

{
  "name": "mylib",
  "type": "module",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    },
    "./package.json": "./package.json"
  }
}

Карта "exports" — это больше, чем двойная публикация: это граница публичного API твоего пакета. Всё, чего нет в exports, недостижимо снаружи — потребители больше не могут глубоко импортировать mylib/src/internal.js, даже если файл существует. Эта инкапсуляция — сеньорская причина определять exports осознанно, а не давать утечь всей директории.

Стык interop — где утекает время

Две системы не композируются симметрично, и эта асимметрия — настоящая боль эпохи миграции:

• ESM может импортировать CJS. import express from "express" работает; объект module.exports из CJS становится default-экспортом ESM. Именованные импорты из CJS-модуля — best-effort: Node статически анализирует исходник CJS, чтобы угадать именованные экспорты, но всё, присвоенное динамически (module.exports[name] = ...), невидимо, поэтому import { Router } from "express" может упасть там, где import express from "express"; const { Router } = express; работает.
• CJS не может синхронно require() ESM-модуль — исторически это кидало ERR_REQUIRE_ESM, потому что загрузка ESM асинхронна, а require синхронен. Портативный фикс — dynamic import(), который возвращает промис и работает из любой системы: const mod = await import("./esm-only.mjs"). (Свежие версии Node умеют require() синхронный ESM-граф, но dynamic import() — правило, которое держится всегда.)

// CJS-файл, которому нужна ESM-only зависимость
async function main() {
  const { default: chalk } = await import("chalk"); // chalk теперь ESM-only
  console.log(chalk.green("работает из CJS через dynamic import()"));
}
main();