Навигация

Модули: CommonJS и ESM

Первый import в Node-проекте обычно работает, а через неделю появляются ERR_MODULE_NOT_FOUND, две копии одной библиотеки и ReferenceError из-за циклической зависимости. Почти все такие ошибки — не про синтаксис import, а про то, как рантайм ищет файлы, кэширует их и связывает между собой. Разберём обе системы модулей со стороны Node и то, как они сосуществуют в одном проекте.

Содержание

  1. Две системы модулей
  2. CommonJS: require, module.exports и кэш
  3. ESM: import, export и фазы загрузки
  4. Как включить ESM
  5. Разрешение модулей
  6. Поле exports и imports
  7. Пути к файлам в CJS и ESM
  8. Динамический импорт
  9. Top-level await
  10. Dual packages: двойная загрузка
  11. Циклические зависимости
  12. Эксперименты, которые объясняют модули
  13. Ключевые тезисы для интервью
  14. Заключение
  15. Полезные ссылки

Две системы модулей

В Node живут две несовместимые по механике системы:

  • CommonJS (CJS) — то, с чего начался Node в 2009 году: require, module.exports, синхронная загрузка.
  • ES Modules (ESM) — стандарт ECMAScript 2015: import, export, статический граф и асинхронная загрузка.

Синтаксис и связывание значений (live bindings) подробно разобраны в статье «Модули: ESM и CJS» раздела JavaScript. Здесь важен другой слой: что Node делает с этими конструкциями — как находит файл, когда исполняет код, что кэширует и как смешивает два формата.

СвойствоCommonJSESM
Синтаксисrequire, module.exportsimport, export
Когда известны зависимостив момент вызова, динамическидо исполнения, статически
Поиск файлас перебором расширений и index.jsточный путь, exports пакета
Загрузкасинхроннаяасинхронная, в три фазы
Связь с экспортомкопия значенияlive binding
this на верхнем уровнеmodule.exportsundefined
Top-level awaitнетда
Кэшrequire.cache по пути файлавнутренний кэш по URL

Выбор формата — не вкусовая настройка. Он определяет, какие ошибки вы увидите, как быстро стартует сервис и сколько экземпляров библиотеки окажется в памяти.


CommonJS: require, module.exports и кэш

require — обычная функция, которая делает всё сразу: находит файл, читает его с диска, оборачивает в функцию, исполняет и возвращает module.exports.

Внутри себя Node превращает каждый модуль в такую конструкцию:

(function (exports, require, module, __filename, __dirname) {
  // код модуля
  // module.exports — то, что вернёт require
});

Отсюда три следствия, которые надо помнить:

  • Загрузка синхронная. Пока файл читается и исполняется, главный поток занят — подробнее о цене блокировок в статье про устройство рантайма.
  • Код модуля выполняется при первом require, а не при старте процесса. Тяжёлая инициализация в модуле откладывается до первого импорта, но всё равно блокирует поток.
  • exports — это ссылка на module.exports. Присваивание exports = {...} рвёт ссылку, и require вернёт старый объект. Правильно — module.exports = {...}.
// counter.cjs
let count = 0;

module.exports = {
  increment: () => ++count,
  current: () => count,
};

Кэш по разрешённому пути

Модуль исполняется один раз, а повторный require возвращает тот же объект из require.cache:

const a = require('./counter.cjs');
const b = require('./counter.cjs');

a.increment();
console.log(a === b, b.current()); // true 1

Из этого вырастают две практики:

  • Singleton по умолчанию. Пул соединений, конфиг, логгер — всё, что экспортировано из модуля, существует в одном экземпляре на процесс. Это удобно, но означает и общее изменяемое состояние: один модуль поменял настройку, эффект видят все.
  • Кэш можно чистить. delete require.cache[require.resolve('./config.cjs')] перезагрузит файл, но старые ссылки у уже импортировавших модулей останутся. Для hot reload это компромисс, а не полноценная замена перезапуску.

require.resolve('./utils') возвращает найденный путь, не исполняя модуль, — полезно для диагностики «а какой файл на самом деле подхватился».

Почему require синхронный

CommonJS появился до промисов и не предполагал ожидания: require должен вернуть значение прямо сейчас. Отсюда запрет на асинхронную инициализацию на верхнем уровне модуля — если конфиг нужно получить из сети, его грузят лениво или на этапе старта приложения, а не в момент импорта.

Синхронность — причина, по которой CJS не умеет загружать ESM-модули с top-level await: вернуть результат до завершения промиса невозможно.


ESM: import, export и фазы загрузки

С точки зрения рантайма ESM — это не «другой синтаксис для того же require», а другая модель исполнения. Модуль проходит три фазы.

  1. Построение графа. Node читает файлы, разбирает их и составляет карту: кто кого импортирует. Код при этом ещё не выполняется.
  2. Связывание. Импорты соединяются с экспортами; если экспорта с таким именем нет, ошибка возникает до запуска программы.
  3. Исполнение. Тела модулей выполняются в порядке зависимостей — сначала зависимости, затем тот, кто их импортирует.

Из фаз напрямую следуют свойства, которых нет в CJS:

  • Импорты поднимаются. import исполняется до тела модуля, где бы он ни был записан. Поэтому import нельзя поставить внутрь if — для условий есть динамический import().
  • Ошибки в именах видны сразу. import { missing } from './math.js' падает при связывании, даже если функция ни разу не вызвана.
  • Связи живые. Импортированное значение отражает изменения в экспортирующем модуле.
// counter.js
export let count = 0;

export function increment() {
  count += 1;
}
// main.js
import { count, increment } from './counter.js';

increment();
console.log(count); // 1

В CJS аналог вернул бы 0: require копирует значение на момент импорта. При этом импортирующая сторона не может присвоить count — связь доступна только на чтение.

Ещё два отличия, заметные на практике:

  • Строгий режим по умолчанию. ESM всегда strict, поэтому недекларированные переменные и this === undefined ведут себя иначе, чем в CJS.
  • Свой кэш по URL. Один и тот же файл, загруженный через разные URL или с разными query-параметрами, может стать разными экземплярами.

Как включить ESM

Формат файла определяется его расширением и ближайшим package.json:

РасширениеПакет без type"type": "module"
.jsCommonJSESM
.cjsCommonJSCommonJS
.mjsESMESM

"type": "module" в package.json переключает все .js-файлы пакета в ESM. Исключения — .cjs, которые всегда остаются CommonJS. У соседнего вложенного package.json может быть свой type, поэтому формат определяется по ближайшему вверх по дереву каталогов.

Практические следствия перехода:

  • Расширение обязательно в относительных импортах: import './utils.js', а не import './utils'.
  • Нет require, module, exports, __dirname, __filename. Вместо них — import.meta и createRequire.
  • Встроенные модули импортируются с префиксом node:: import { readFile } from 'node:fs/promises'. Префикс отличает встроенный модуль от пакета с тем же именем и делает намерение явным.
  • import статический. Условная загрузка — только через import().

Типичный package.json сервиса:

{
  "type": "module",
  "scripts": {
    "dev": "node --watch src/server.js",
    "test": "node --test"
  }
}

Подробнее о полях манифеста и exports — в статье «npm и экосистема пакетов».


Разрешение модулей

Самый частый источник ошибок — незнание алгоритма. У CJS и ESM он разный.

CommonJS

  1. Встроенный модуль? fs, path, http — возвращается сразу.
  2. Относительный или абсолютный путь (./x, ../x, /x) — сначала как файл, затем как каталог.
  3. Имя пакета (express, lodash/get) — поиск в node_modules текущего каталога и вверх по дереву до корня.

Поиск файла идёт по расширениям: точное имя, затем .js, .json, .node. Если путь указывает на каталог, Node читает его package.json и берёт main, а при его отсутствии — index.js, index.json или index.node.

require('./utils');      // найдёт utils.js
require('./utils.js');   // то же самое
require('./lib');        // найдёт lib/index.js или main из lib/package.json

Именно поэтому require('./config') может незаметно подхватить config.json вместо config.js — расширения перебираются в фиксированном порядке.

ESM

  1. node:* или встроенный модуль — возвращается сразу.
  2. Относительный путь — только точный файл: расширение обязательно, импорт каталога запрещён.
  3. #имя — внутренний алиас из поля imports пакета.
  4. Имя пакета (pkg, pkg/sub) — через поле exports; если его нет, используется main.
import './utils.js';   // работает
import './utils';      // ERR_MODULE_NOT_FOUND
import './lib';        // ERR_UNSUPPORTED_DIR_IMPORT

Разница не случайна: ESM строит граф до исполнения, поэтому резолвер должен быть однозначным. Перебор расширений и index.js сделал бы результат зависящим от содержимого каталога и сломал бы статический анализ.

Коды ошибок, по которым легко определить причину:

КодЧто случилось
ERR_MODULE_NOT_FOUNDфайла нет или забыто расширение
ERR_UNSUPPORTED_DIR_IMPORTимпортируется каталог в ESM
ERR_PACKAGE_PATH_NOT_EXPORTEDподпуть не объявлен в exports
ERR_INVALID_MODULE_SPECIFIERнекорректный или незакрытый specifier
ERR_REQUIRE_ESMrequire пытается загрузить ESM на Node до 22.12
ERR_REQUIRE_ASYNC_MODULErequire(esm) встретил top-level await

Поле exports и imports

main описывает одну точку входа. exports описывает контракт пакета: какие подпути доступны, в каком формате и при каких условиях.

{
  "name": "@acme/taskflow-core",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./queue": "./dist/queue.js",
    "./package.json": "./package.json"
  }
}

Что это даёт:

  • Инкапсуляция. Всё, что не перечислено, недоступно: import x from '@acme/taskflow-core/dist/internal.js' упадёт с ERR_PACKAGE_PATH_NOT_EXPORTED. Внутренние файлы можно перекладывать без мажорного релиза.
  • Разные сборки под разные условия. import получает ESM, require — CJS, types — декларации для TypeScript.
  • Порядок условий важен. Резолвер берёт первое совпадение, поэтому types ставят первым, а default — последним; иначе TypeScript или старый потребитель получит не тот файл.
  • Подстановочные знаки. "./*": "./dist/*.js" открывает группу подпутей, но требует аккуратности: легко случайно опубликовать внутренности.

exports действует и на require, а не только на import. Поэтому добавление поля в уже опубликованный пакет — ломающее изменение для тех, кто ходил в глубокие подпути.

imports: алиасы внутри пакета

Поле imports позволяет давать внутренним файлам короткие имена, не привязанные к пути:

{
  "imports": {
    "#db": {
      "node": "./src/db.js",
      "default": "./src/db.mock.js"
    }
  }
}
import { db } from '#db';

Работает только внутри самого пакета и только для specifier, начинающихся с #. Это удобно для подмены реализации в тестах и для того, чтобы не тащить ../../ по всему коду. Внешним потребителям такие имена недоступны — в отличие от exports, здесь нет публичного контракта.


Пути к файлам в CJS и ESM

В CJS __dirname и __filename — аргументы той самой функции-обёртки. В ESM обёртки нет, и этих переменных тоже нет.

// ESM
import { readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';

const currentDir = dirname(fileURLToPath(import.meta.url));
const config = JSON.parse(readFileSync(join(currentDir, 'config.json'), 'utf8'));

В Node 20.11+ проще:

const config = JSON.parse(
  readFileSync(join(import.meta.dirname, 'config.json'), 'utf8'),
);

import.meta — объект с метаданными текущего модуля:

  • import.meta.url — URL файла, например file:///.../src/config.js;
  • import.meta.dirname и import.meta.filename — готовые путь и имя файла;
  • import.meta.resolve('pkg') — синхронно разрешает specifier в URL.

Почему не просто import.meta.url: это URL, а не путь файловой системы. На Windows между ними есть разница в префиксе и экранировании, поэтому перед передачей в fs URL нужно конвертировать через fileURLToPath.

Если в ESM-модуле нужен именно require — например, для JSON или CJS-пакета, — его создают заново:

import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const pkg = require('./package.json');

JSON в ESM импортируют и напрямую, с указанием типа:

import data from './data.json' with { type: 'json' };

Синтаксис assert из ранних версий заменён на with; на старых версиях Node атрибуты могут требовать флага, поэтому createRequire остаётся универсальным обходным путём.


Динамический импорт

import() — функция, которая возвращает промис с namespace-объектом модуля. В отличие от статического import, она:

  • работает и в ESM, и в CommonJS;
  • может стоять в любом месте кода, включая условия и функции;
  • принимает вычисляемое выражение;
  • грузит ESM из CJS — до Node 22.12 это основной способ сделать это.
async function sendReport(report) {
  if (!report.pdf) return;

  const { renderPdf } = await import('./pdf.js'); // тяжёлая зависимость только здесь
  await renderPdf(report);
}

Три практических нюанса:

  • Ошибка отклоняет промис, а не бросается синхронно: нужен try/catch вокруг await import().
  • Путь вычисляется в рантайме, поэтому сборщик не может проанализировать зависимость. Для бандлеров оставляют статический комментарий или перечисляют варианты явно.
  • Каждый вызов — обращение к кэшу, а не повторное исполнение: модуль загрузится один раз на URL.

Динамический импорт — штатный способ разорвать циклическую зависимость: модуль не участвует в начальном графе, поэтому цикл исчезает.


Top-level await

В ESM await разрешён на верхнем уровне модуля:

// db.js
import { createPool } from 'pg';

export const pool = await createPool(process.env.DATABASE_URL);

Что происходит:

  1. Модуль становится асинхронным: его исполнение приостанавливается на промис.
  2. Все импортёры ждут завершения, прежде чем начать исполнение.
  3. Если промис отклонён, падает импорт, а не только тело модуля.

Поэтому top-level await — инструмент точки входа и инициализации: конфиг, подключение к базе, загрузка схемы. В обработчике запроса он не нужен и опасен: любая задержка инициализации превращается в задержку старта.

Главное ограничение — несовместимость с require:

// Node 22.12+
const db = require('./db.js');
// ERR_REQUIRE_ASYNC_MODULE: модуль использует top-level await

Синхронный require не может дождаться промиса, поэтому для такого модуля остаётся await import('./db.js'). Если модуль нужен и CJS-, и ESM-потребителям, асинхронную инициализацию выносят в явную функцию init(), которую вызывают на старте.


Dual packages: двойная загрузка

Пакет, который публикует две сборки, называют dual package:

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

Замысел — удобство для потребителей. Проблема — в рантайме: import и require получают разные файлы, а кэши у них разные. В одном процессе оказываются две копии модуля.

Чем это опасно:

  • Разное состояние. Два кэша, два пула соединений, два логгера, два DI-контейнера — каждый со своими настройками.
  • Разные классы. instanceof между «одинаковыми» классами из двух копий возвращает false.
  • Тихие баги. Ошибка не появляется при установке: код просто ведёт себя не так, как ожидалось, а диагностика занимает дни.

Типичный симптом: логгер пишет каждую строку дважды или приложение открывает вдвое больше соединений с базой, чем настроено.

require(esm)

Начиная с Node 22.12 require() умеет загружать ESM без флага. Это снимает необходимость в dual-сборке для многих пакетов:

// Node 22.12+
const esm = require('esm-only-package'); // namespace-объект

Ограничения, которые надо знать:

  • Граф должен быть синхронным. Top-level await в модуле или его зависимостях даёт ERR_REQUIRE_ASYNC_MODULE.
  • Возвращается namespace, а не module.exports: дефолтный экспорт доступен как .default, именованные — как свойства.
  • Старые Node не поддерживают механизм: для них остаётся await import() или dual-сборка.

Практический вывод: если минимальная версия Node — 22.12+, проще публиковать один ESM-формат и не плодить две сборки. Если потребители на старых версиях — dual неизбежен, но состояние лучше держать вне модуля: в переданных зависимостях, а не в модульных синглтонах.


Циклические зависимости

Цикл — это когда a импортирует b, а b импортирует a. Обе системы такое допускают, но ведут себя по-разному.

CommonJS: частичный экспорт

CJS создаёт запись в кэше до исполнения модуля. Поэтому второй участник цикла видит уже существующий, но ещё не заполненный module.exports.

// a.cjs
exports.a = 1;
const b = require('./b.cjs');
console.log('b в a:', b.b); // 2

// b.cjs
const a = require('./a.cjs');
console.log('a в b:', a.a); // 1 — модуль a ещё не завершён
exports.b = 2;

Порядок такой: a начинает исполнение, выставляет a = 1, затем грузит b; b получает частичный exports от a (там уже есть a), выставляет b = 2 и возвращает управление; a получает готовый b.

Если бы a выставил значение после require, в b было бы undefined. Это самая частая форма бага: код работает, пока порядок импортов случайно благоприятен.

ESM: живые связи и TDZ

ESM сначала строит полный граф, затем связывает модули и только потом исполняет. Цикл для него — нормальная ситуация, а не аварийная:

  • импорты получают живые связи, а не копии;
  • функции и var доступны благодаря поднятию;
  • let, const и class до инициализации находятся во временной мёртвой зоне (TDZ).
// a.js
import { b } from './b.js';
export const a = 1;
console.log('a видит b:', b);

// b.js
import { a } from './a.js';
export const b = 2;
console.log('b видит a:', a); // ReferenceError: Cannot access 'a' before initialization

Node исполняет b первым, потому что a от него зависит. Но a ещё не доехал до const a = 1, и обращение к связи бросает ReferenceError — в отличие от CJS, где молча пришёл бы undefined.

Если бы a был объявлен через function, ошибки бы не было: функция поднимается и доступна до исполнения тела.

Как с этим жить

  • Не строить циклы специально. Цикл — сигнал, что модули слишком связаны.
  • Вынести общее в третий модуль, от которого зависят оба.
  • Использовать динамический import() внутри функции: модуль загрузится позже, когда цикл уже не важен.
  • Ловить автоматически. madge --circular или правило линтера на import/no-cycle показывают проблему до продакшена.

Эксперименты, которые объясняют модули

Три коротких опыта, которые переводят теорию в наблюдаемое поведение.

1. Убедиться, что кэш CJS общий

Создайте counter.cjs из раздела про CommonJS и два файла, которые его импортируют. Вызовите increment() в одном — второй увидит изменённое значение. Это и есть модульный singleton: удобный для пула соединений и опасный для всего, что кажется «локальным».

2. Сравнить разрешение путей

mkdir -p lib && echo 'module.exports = { x: 1 }' > lib/index.js

node -e "console.log(require('./lib'))"            # { x: 1 }: index.js
node --input-type=module -e "import('./lib')"      # ERR_UNSUPPORTED_DIR_IMPORT

node -e "console.log(require('./lib/index'))"      # { x: 1 }: расширение подставлено
node --input-type=module -e "import('./lib/index')" # ERR_MODULE_NOT_FOUND

Одинаковый на вид путь ведёт себя по-разному — и это не баг, а разные контракты резолверов.

3. Поймать двойную загрузку

Соберите пакет с двумя сборками и в одном процессе загрузите его через import и через require. Сравните instanceof и счётчик внутри модуля: значения разойдутся. Тот же опыт объясняет, почему после миграции на ESM «внезапно» перестал работать singleton.


Ключевые тезисы для интервью

  • require синхронный: он читает, компилирует и исполняет модуль внутри вызова, поэтому первый импорт блокирует поток, а асинхронная инициализация на верхнем уровне невозможна.
  • Кэш CJS ведёт себя как singleton по разрешённому пути: повторный require возвращает тот же объект, а значит, модульное состояние общее для всех потребителей.
  • ESM исполняется в три фазы — построение графа, связывание, исполнение; поэтому имена экспортов проверяются до запуска, импорты поднимаются, а связи остаются живыми.
  • Резолверы разные: CJS перебирает расширения и index.js, ESM требует точный путь и уважает exports, из-за чего один и тот же импорт может работать в одном формате и падать в другом.
  • exports и imports — контракт пакета: первый закрывает внутренности и разводит ESM/CJS-сборки по условиям, второй даёт внутренние алиасы #name.
  • Dual package даёт две копии модуля с независимым состоянием; require(esm) с Node 22.12+ грузит тот же ESM-экземпляр, но не умеет ждать top-level await.
  • Цикл в CJS отдаёт частичный module.exports и молча приводит к undefined, в ESM — живые связи с ReferenceError при обращении до инициализации; надёжный выход — третий модуль или динамический import().

Заключение

CommonJS и ESM — не два синтаксиса одного механизма, а две модели загрузки. CJS исполняет код в момент вызова, кэширует по пути и отдаёт копию module.exports; ESM строит граф заранее, связывает экспорты до исполнения и работает с живыми связями. Практические проблемы почти всегда растут из этой разницы: ERR_MODULE_NOT_FOUND из-за забытого расширения, undefined из-за цикла, два пула соединений из-за dual-сборки. Знание алгоритма разрешения, полей exports/imports и правил интеропа позволяет выбирать формат осознанно и не ломать потребителей при публикации.

Полезные ссылки