Что такое CommonJS-модуль?

Что такое CommonJS-модуль?

CommonJS — это стандарт модульной системы для языка JavaScript, первоначально разработанный для использования вне браузера, в первую очередь на стороне сервера (в среде Node.js). Он был создан для решения проблемы организации кода в крупных приложениях, где необходимо изолировать логику, управлять зависимостями и избегать конфликтов имён в глобальной области видимости.

Ключевые принципы CommonJS

Основная идея CommonJS — каждый файл рассматривается как изолированный модуль. У модуля есть своя область видимости (переменные, объявленные в файле, по умолчанию не доступны извне), и он может явно экспортировать определённые значения, а также импортировать (загружать) функциональность из других модулей. Это реализуется через два главных объекта: require и module.exports (или его псевдоним exports).

Синтаксис и базовый пример

Экспорт функциональности

Чтобы сделать часть кода доступной из других модулей, используется объект module.exports.

// math.js - модуль с математическими функциями
function add(a, b) {
    return a + b;
}

function multiply(a, b) {
    return a * b;
}

// Экспортируем объект с функциями
module.exports = {
    add,
    multiply
};

// Альтернативный вариант через exports (сокращённая ссылка на module.exports)
// exports.add = add;
// exports.multiply = multiply;

Импорт функциональности

Для загрузки модуля используется функция require(). Она принимает путь к модулю и возвращает его экспортированный объект.

// app.js - основной файл приложения
const math = require('./math.js'); // Импортируем модуль math.js

console.log(math.add(5, 3));       // Выведет: 8
console.log(math.multiply(4, 2));  // Выведет: 8

Основные характеристики CommonJS

• Синхронная загрузка: Модули загружаются синхронно, то есть выполнение кода блокируется до полной загрузки требуемого модуля. Это хорошо подходит для серверной среды (Node.js), где файлы находятся на локальном диске, и их чтение происходит быстро.
• Кеширование модулей: При первом вызове require('путь') модуль загружается, выполняется, и его экспортируемый объект кешируется. Все последующие вызовы require() для того же пути возвращают кешированный объект, что предотвращает повторное выполнение кода и повышает производительность.
• Динамический require(): Поскольку require() — это обычная функция, её можно вызывать условно, в зависимости от логики программы. Это даёт динамическую загрузку модулей.

  let moduleName;
  if (process.env.NODE_ENV === 'production') {
      moduleName = './logger.prod.js';
  } else {
      moduleName = './logger.dev.js';
  }
  const logger = require(moduleName);
  

• Циклические зависимости: CommonJS умеет их обрабатывать, хотя это требует внимания. При наличии циклов модули могут получать частично загруженные экспорты.

Отличие от ES-модулей (ECMAScript Modules, ESM)

CommonJS долгое время был стандартом де-факто в Node.js, но с появлением в спецификации JavaScript нативного стандарта ES-модулей (использующих import/export), возникли два основных отличия:

1. Синтаксис: ES-модули используют статический, встроенный в язык синтаксис import и export.

   // ESM пример
   import { add, multiply } from './math.js';
   export const PI = 3.14;
   

2. Статическая vs динамическая загрузка: ESM — статические. Импорты анализируются до выполнения кода ("статический анализ"), что позволяет проводить оптимизацию ("тряски дерева", tree-shaking) и гарантирует, что зависимости известны заранее. CommonJS — динамический, require() может быть вызван в любом месте.

Заключение

CommonJS — это фундаментальная, проверенная временем модульная система, которая сыграла ключевую роль в развитии экосистемы Node.js и позволила создавать сложные серверные приложения на JavaScript. Несмотря на постепенный переход Node.js и современных сборщиков (Webpack, Vite) к нативным ES-модулям, понимание CommonJS остаётся критически важным по нескольким причинам: огромное количество существующих библиотек и legacy-кода используют его, а также для работы с конфигурационными файлами (например, webpack.config.js), которые по умолчанию обрабатываются Node.js в формате CommonJS.