re:re:actable
Урок 013 минуты чтения

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 определяет тип модуля

МаркерТип
.cjsCommonJS
.mjsES 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-level await.
  • 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.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам