Модульная система
Тема дорожной карты · Node.js
Система модулей Node.js обеспечивает основу для организации JavaScript-кода в переиспользуемые изолированные единицы; Node.js поддерживает два отдельных формата модулей: CommonJS (require / module.exports) и ECMAScript Modules (import / export). Модули CommonJS загружаются синхронно и были стандартом со времён создания Node.js, тогда как ESM-модули загружаются асинхронно и теперь нативно поддерживаются в среде выполнения Node.js через файлы .mjs или установку "type": "module" в package.json. Система модулей Node.js оборачивает каждый файл в функцию-обёртку модуля, которая добавляет в локальную область видимости __dirname, __filename, require, module и exports, сохраняя глобальное пространство имён чистым и обеспечивая инкапсуляцию, критически важную для крупномасштабной серверной разработки. TypeScript компилируется в любой из форматов в зависимости от поля module в tsconfig.json, поэтому согласование выходного формата компилятора с системой модулей среды выполнения необходимо как авторам npm-пакетов, так и разработчикам приложений.
Как это работает
Модульная система имеет два формата: CommonJS (legacy дефолт, require/module.exports, синхронный) и ES Modules (import/export, асинхронный, browser-compatible). Файлы резолвятся загрузчиком модулей: относительные пути → обход node_modules → встроенные. "type": "module" в package.json переключает дефолт для .js; расширения .mjs и .cjs форсируют формат. Conditional exports (exports в package.json) позволяют пакету поставлять оба формата.
Когда применять
Для новых проектов ESM — это стандарт JS, поддерживает top-level await, ожидается бандлерами/тулингом. CommonJS — только когда legacy-зависимости требуют или цена миграции запретительная. import("./mod.js") — для динамической / условной загрузки. Бандлер (esbuild, tsup) — только если публикуете пакет в обоих форматах; backend-сервисы обычно гоняют исходник.
Типичные ошибки
Ловушки Модульная система: пропущенное расширение .js в ESM-импортах (тихо ломается); циклические импорты (A → B → A — одна сторона получает partial export); случайный бандл CommonJS-only пакета в ESM-проект (interop болезненный); __dirname/__filename отсутствуют в ESM (используйте import.meta.url). Прочтите доку Node.js ESM перед битвой с "unexpected token".