Модули: CommonJS и ESM
Первый import в Node-проекте обычно работает, а через неделю появляются ERR_MODULE_NOT_FOUND, две копии одной библиотеки и ReferenceError из-за циклической зависимости. Почти все такие ошибки — не про синтаксис import, а про то, как рантайм ищет файлы, кэширует их и связывает между собой. Разберём обе системы модулей со стороны Node и то, как они сосуществуют в одном проекте.
Содержание
- Две системы модулей
- CommonJS: require, module.exports и кэш
- ESM: import, export и фазы загрузки
- Как включить ESM
- Разрешение модулей
- Поле exports и imports
- Пути к файлам в CJS и ESM
- Динамический импорт
- Top-level await
- Dual packages: двойная загрузка
- Циклические зависимости
- Эксперименты, которые объясняют модули
- Ключевые тезисы для интервью
- Заключение
- Полезные ссылки
Две системы модулей
В Node живут две несовместимые по механике системы:
- CommonJS (CJS) — то, с чего начался Node в 2009 году:
require,module.exports, синхронная загрузка. - ES Modules (ESM) — стандарт ECMAScript 2015:
import,export, статический граф и асинхронная загрузка.
Синтаксис и связывание значений (live bindings) подробно разобраны в статье «Модули: ESM и CJS» раздела JavaScript. Здесь важен другой слой: что Node делает с этими конструкциями — как находит файл, когда исполняет код, что кэширует и как смешивает два формата.
| Свойство | CommonJS | ESM |
|---|---|---|
| Синтаксис | require, module.exports | import, export |
| Когда известны зависимости | в момент вызова, динамически | до исполнения, статически |
| Поиск файла | с перебором расширений и index.js | точный путь, exports пакета |
| Загрузка | синхронная | асинхронная, в три фазы |
| Связь с экспортом | копия значения | live binding |
this на верхнем уровне | module.exports | undefined |
| 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», а другая модель исполнения. Модуль проходит три фазы.
- Построение графа. Node читает файлы, разбирает их и составляет карту: кто кого импортирует. Код при этом ещё не выполняется.
- Связывание. Импорты соединяются с экспортами; если экспорта с таким именем нет, ошибка возникает до запуска программы.
- Исполнение. Тела модулей выполняются в порядке зависимостей — сначала зависимости, затем тот, кто их импортирует.
Из фаз напрямую следуют свойства, которых нет в 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" |
|---|---|---|
.js | CommonJS | ESM |
.cjs | CommonJS | CommonJS |
.mjs | ESM | ESM |
"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
- Встроенный модуль?
fs,path,http— возвращается сразу. - Относительный или абсолютный путь (
./x,../x,/x) — сначала как файл, затем как каталог. - Имя пакета (
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
node:*или встроенный модуль — возвращается сразу.- Относительный путь — только точный файл: расширение обязательно, импорт каталога запрещён.
#имя— внутренний алиас из поляimportsпакета.- Имя пакета (
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_ESM | require пытается загрузить ESM на Node до 22.12 |
ERR_REQUIRE_ASYNC_MODULE | require(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);
Что происходит:
- Модуль становится асинхронным: его исполнение приостанавливается на промис.
- Все импортёры ждут завершения, прежде чем начать исполнение.
- Если промис отклонён, падает импорт, а не только тело модуля.
Поэтому 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 и правил интеропа позволяет выбирать формат осознанно и не ломать потребителей при публикации.
Полезные ссылки
- Node.js: CommonJS modules —
require, кэш, алгоритм разрешения - Node.js: ECMAScript modules — фазы,
import.meta, различия с CJS - Node.js: Packages —
exports,imports, dual packages,require(esm) - Node.js:
node:module—createRequire,import.meta.resolve, API модулей - Модули: ESM и CJS — синтаксис, live bindings и tree shaking на уровне языка
- npm и экосистема пакетов —
package.json,type,exportsи версии