ES-модули и CommonJS в Node.js

Что это такое

CommonJS (CJS) — исходная модульная система Node: require() синхронно загружает модуль во время выполнения, а модуль экспортирует то, что присвоено module.exports. ES-модули (ESM) — стандарт языка: import и export статичны и разрешаются до выполнения тела модуля, загрузка асинхронна, разрешён await верхнего уровня, а import.meta содержит метаданные модуля. Node выбирает формат для каждого файла: .mjs всегда означает ESM, .cjs — CJS, а .js следует полю "type" ближайшего package.json. Файл без поля "type" документация пакетов называет неоднозначным: текущие версии Node сначала выполняют его как CommonJS, а если парсер обнаруживает синтаксис ES-модуля, повторно оценивают как ES-модуль — это определение по синтаксису; старые версии просто считают его CommonJS. Документация ESM перечисляет отсутствующие в ESM средства (require, module.exports, __filename, __dirname) и замены: import.meta.filename, import.meta.dirname, import.meta.resolve() и module.createRequire(). ESM может импортировать CommonJS, при этом импорт по умолчанию — это module.exports; текущие версии Node могут загружать ES-модуль через require(), если в его графе нет await верхнего уровня.

Почему это важно

Смешение двух систем лежит в основе самых распространённых ошибок запуска проектов Node: «Cannot use import statement outside a module», ERR_REQUIRE_ESM, exports is not defined. У средств запуска тестов, вывода TypeScript и сборщиков есть собственные настройки модулей, и несоответствие вызывает ошибку во время выполнения, а не сборки.

Как применять

• Для нового кода задайте "type": "module" в package.json и используйте ESM везде; немногие файлы, которые должны остаться CommonJS, называйте с расширением .cjs.
• Относительные импорты ESM должны включать расширение файла (./util.js, ./dir/index.js); механизм разрешения не угадывает его.
• JSON импортируется с атрибутом: import cfg from "./cfg.json" with { type: "json" }.
• Для библиотек в обоих форматах объявите "exports" с условиями import и require, а перед этим прочитайте документацию пакетов и связанный с ней репозиторий примеров двойных пакетов. Пакет, загруженный через обе точки входа, существует дважды, с раздельным состоянием модулей — это опасность двойного пакета.
• В браузерах модульные скрипты должны отдаваться с JavaScript MIME-типом, например text/javascript; MDN документирует ошибку строгой проверки MIME-типа для файлов .mjs, отданных иначе.

Подводные камни

Циклические импорты ведут себя по-разному: привязки ESM отражают текущее значение, но при раннем чтении могут быть ещё не инициализированы. require() для ESM с await верхнего уровня вызывает ERR_REQUIRE_ASYNC_MODULE; вместо него используйте import(). Компилятор, выдающий вызовы require в пакете с "type": "module", создаёт код, который падает при загрузке; согласуйте настройку модульного вывода компилятора со средой выполнения.