Модульная система: ESM vs CommonJS, package.json и поле exports

Архитектурная база#

Исторически Node.js развивался вокруг собственной модульной спецификации CommonJS (CJS), разработанной в 2009 году. Модель CJS основана на синхронной загрузке модулей: функция require() читает файл с диска, синхронно компилирует его в функцию-обертку, выполняет тело модуля и помещает экспортированный объект module.exports в системный кэш require.cache. Эта модель отлично подходила для монолитных серверных сред, но фундаментально противоречила асинхронной природе веба и препятствовала статическому анализу кода (Tree-shaking).

Начиная с редакции ECMAScript 2015 (ES6) и полноценной интеграции в Node.js, стандартом индустрии стала нативная спецификация ECMAScript Modules (ESM). Архитектура ESM разделяет процесс загрузки на три изолированные фазы: статический синтаксический анализ графа зависимостей, связывание живых ссылок (Live Bindings) и непосредственное вычисление кода.

Современный файл package.json выступает не просто списком зависимостей, а манифестом архитектуры пакета. С помощью поля "type": "module" и карты субпафовых экспортов "exports" разработчик строго инкапсулирует внутренности библиотеки, определяя публичные точки входа и поддерживая дуальную совместимость (Dual Package) для различных сред выполнения.

Ментальная модель#

В CommonJS модули вычисляются динамически прямо в момент вызова require(): код может содержать условные операторы if (condition) require('./a'), а возвращаемое значение является обычным снимком объекта (копированием значения). В ESM весь граф импортов строится статически ДО выполнения первой строчки исполняемого кода, гарантируя детерминированность структуры зависимостей.

[ CommonJS: Синхронное пошаговое вычисление ]
index.js -> require('./math.js') -> Чтение файла с диска -> Выполнение math.js -> Возврат module.exports

[ ESM: Трехфазный статический конвейер ]
Фаза 1: Construction (Парсинг всех import, построение графа модулей без исполнения кода)
                      |
Фаза 2: Instantiation (Выделение ячеек памяти и связывание Live Bindings)
                      |
Фаза 3: Evaluation (Исполнение кода модулей от листьев дерева к корню, Top-Level Await)

На практике применяется#

• Изоляция публичного API в Enterprise-библиотеках: с помощью карты "exports" в package.json корпоративные SDK скрывают утилитарные файлы и хелперы, предотвращая случайный импорт приватных зависимостей сторонними командами (import 'pkg/internal/hack' блокируется рантаймом).
• Снижение размера клиентских бандлов (Tree-Shaking): статический синтаксис ESM позволяет сборщикам (Vite, Rollup, Webpack) гарантированно вырезать неиспользуемые экспорты из сторонних библиотек (например, исключая 90% неиспользуемых функций из утилитных пакетов).
• Условный дуальный экспорт (Dual Package Hazard Prevention): поддержка параллельного экспорта ESM (для современных веб-серверов) и CommonJS (для устаревших пайплайнов) с единой кодовой базой типов TypeScript (.d.ts).
• Скрипты инициализации с Top-Level Await: подключение к базе данных, получение секретов из Vault и прогрев кэша на верхнем уровне файла конфигурации без необходимости создания временных асинхронных функций-оберток (async () => { ... })().

Как это работает#

1. Переключение проекта в режим ESM: поле "type" в package.json#

По умолчанию файлы с расширением .js в Node.js трактуются как CommonJS. Чтобы включить современный режим ESM для всех файлов проекта, необходимо указать "type": "module" в корневом файле конфигурации package.json.

{
  "name": "enterprise-backend-service",
  "version": "1.0.0",
  "type": "module",
  "engines": {
    "node": ">=24.0.0"
  },
  "scripts": {
    "start": "node src/index.js",
    "dev": "node --watch src/index.js"
  },
  "dependencies": {
    "zod": "^3.24.0"
  },
  "devDependencies": {
    "typescript": "^5.8.0"
  }
}

Правила разрешения расширений:

• .js: интерпретируется как ESM, если в ближайшем package.json указано "type": "module", иначе как CommonJS.
• .mjs: всегда интерпретируется как ECMAScript Module независимо от package.json.
• .cjs: всегда интерпретируется как CommonJS независимо от package.json.

2. Обязательность расширений файлов и отсутствие магии индексных файлов#

В отличие от устаревшего алгоритма CommonJS, который автоматически перебирал расширения (./utils, ./utils.js, ./utils.json, ./utils/index.js), резолвер ESM в Node.js требует строгого указания расширения файла:

// Экспорт именованных сущностей и констант
export const PI = 3.1415926535;

export function add(a: number, b: number): number {
  return a + b;
}

// Внутреннее изменяемое состояние для демонстрации Live Bindings
export let executionCount = 0;

export function trackExecution(): void {
  executionCount++;
}

// ВНИМАНИЕ: Обязательно указывать относительное расширение .js (даже при компиляции из TS)
import { PI, add, executionCount, trackExecution } from './math/calculator.js';

console.log('Math Constant PI:', PI);
console.log('Result of add(10, 20):', add(10, 20));

console.log('Initial Execution Count:', executionCount); // 0
trackExecution();
console.log('Updated Execution Count via Live Binding:', executionCount); // 1

3. Современная семантика package.json: поле "exports"#

Поле "exports" полностью заменяет устаревшее поле "main" и является современным стандартом инкапсуляции пакетов:

{
  "name": "@company/auth-sdk",
  "version": "2.4.0",
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./tokens": {
      "types": "./dist/tokens.d.ts",
      "import": "./dist/tokens.js"
    },
    "./package.json": "./package.json"
  }
}

Что дает такая структура:

1. Запрет глубоких импортов: попытка внешнего проекта вызвать import '@company/auth-sdk/dist/internal-secret.js' вызовет фатальную ошибку резолвера ERR_PACKAGE_PATH_NOT_EXPORTED.
2. Поддержка субпутей: разработчики могут писать чистые импорты import { verifyToken } from '@company/auth-sdk/tokens'.
3. Условные экспорты (Conditional Exports): потребители CommonJS получат файл .cjs, а потребители ESM — нативный .js.

4. Сравнительный анализ модульных систем#

Распространённые ошибки#

import { fileURLToPath } from 'node:url';
import path from 'node:path';

// Современный стандарт Node.js 20.11+
const currentFile = import.meta.filename;
const currentDir = import.meta.dirname;

// Универсальный кроссплатформенный подход
const __filenameFallback = fileURLToPath(import.meta.url);
const __dirnameFallback = path.dirname(__filenameFallback);

Связанные материалы#