CommonJS и ES Modules в Node.js
На этой странице
CommonJS использует require() и module.exports, а ES Modules используют import и export. В Node.js обе системы поддерживаются, но отличаются синтаксисом, загрузкой, interop и правилами определения типа файла.
Вопрос
Чем CommonJS отличается от ES Modules в Node.js, как Node.js определяет тип модуля и как они взаимодействуют?
Синтаксис
CommonJS:
const { sum } = require("./math.js");
module.exports = { sum };ES Modules:
import { sum } from "./math.js";
export { sum };Как Node.js определяет тип модуля
| Маркер | Тип |
|---|---|
.cjs | CommonJS |
.mjs | ES Module |
.js + "type": "commonjs" | CommonJS |
.js + "type": "module" | ES Module |
Загрузка
CommonJS загружается синхронно через require(). ES Modules поддерживают статический анализ импортов и top-level await.
const config = await import("./config.js");Interop
ESM может импортировать CommonJS, но named exports могут быть не всегда такими очевидными. CommonJS может загружать ESM не так же просто, особенно если модуль использует top-level await.
Что выбрать
Для нового Node.js-проекта часто выбирают ESM, потому что это стандарт JavaScript и он совпадает с браузером. Но при работе с legacy-кодом и старой экосистемой нужно уверенно читать CommonJS.
CommonJS - как работает require
require() загружает модуль, выполняет файл и возвращает то, что записано в module.exports.
const fs = require("node:fs");CommonJS синхронный по своей природе, поэтому хорошо подходил для серверного окружения Node.js.
module.exports и exports
exports.sum = (a, b) => a + b;Это короткая ссылка на module.exports, но ее легко сломать, если присвоить exports новое значение.
// плохо
exports = { sum };Лучше явно использовать module.exports, если экспортируется объект целиком.
Где встречается CommonJS
- Старые Node.js-проекты.
- Много npm-пакетов.
- Конфиги инструментов.
- Скрипты без
"type": "module".
Как включить ESM
Есть несколько явных способов:
{
"type": "module"
}Или расширение:
app.mjsФайлы .mjs всегда считаются ES Modules.
Импорт встроенных модулей
import { readFile } from "node:fs/promises";
import path from "node:path";Префикс node: показывает, что модуль встроенный.
Чего нет в ESM
В ESM нет CommonJS-переменных __dirname, __filename, module, exports, require в обычном виде.
Для пути текущего файла используют import.meta.url.
import { fileURLToPath } from "node:url";
import { dirname } from "node:path";
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);Что важно помнить
- Тип
.jsопределяется полем"type"ближайшегоpackage.json;.mjs— всегда ESM,.cjs— всегда CommonJS. requireсинхронный, ESM-импорты статические и поддерживают top-levelawait.- ESM может импортировать CommonJS; современные версии Node.js умеют
require()синхронных ES-модулей без top-level await. - В ESM относительные импорты указывают с расширением файла:
./math.js.
Мини-шпаргалка
- CommonJS:
require,module.exports. - ESM:
import,export. .mjsвсегда ESM..cjsвсегда CommonJS."type"вpackage.jsonвлияет на.js.- На собеседовании важно понимать оба формата.
- CommonJS использует
require(). - Экспорт идет через
module.exports. - Каждый файл - отдельный модуль.
- Модули кешируются после первого require.
- CommonJS до сих пор часто встречается в Node.js.
- ESM использует
importиexport. - В Node.js ESM включают через
"type": "module"или.mjs. - В ESM нет обычного
__dirname. - Новые проекты часто выбирают ESM, но CommonJS еще очень распространен.
Документация
Node.js: ECMAScript modules, Node.js: CommonJS modules, Node.js: Determining module system.