Двойной выходной формат ESM и CJS

ESM (модули ECMAScript) — официальный стандарт модулей JavaScript, использующий синтаксис import и export. ESM можно анализировать статически: сборщики во время сборки могут точно определить, какие экспорты используются, что позволяет удалять неиспользуемый код. Современные браузеры и Node.js нативно поддерживают ESM.

CJS (CommonJS) использует синтаксис require() и module.exports. Это исходная система модулей Node.js, которая по-прежнему нужна для совместимости со старыми средами Node.js, с Jest (исторически использовавшим CJS) и с кодом, в котором используется require(). CJS вычисляется динамически, поэтому удалять неиспользуемый код сложнее.

Современный пакет npm должен поставляться и в формате ESM, и в формате CJS для максимальной совместимости. Пользователи ESM (Vite, Next.js, современные сборщики) получают импорты с удалением неиспользуемого кода. Пользователи CJS (старые скрипты Node.js, Jest без настройки) получают совместимость с require(). Поле exports в package.json сообщает Node и сборщикам, какой формат использовать.

Поле exports в package.json — современный способ определить условные точки входа. Например: { '.': { 'import': './dist/esm/index.js', 'require': './dist/cjs/index.js', 'types': './dist/esm/index.d.ts' } }. Сборщики и Node.js версии 12 и выше считывают exports, чтобы автоматически выбрать подходящий формат.

Старые инструменты не понимают поле exports. Для совместимости также задайте: main, указывающее на вывод CJS (резервный вариант для старого require в Node), и module, указывающее на вывод ESM (подсказка для webpack/rollup, нестандартная, но широко поддерживаемая). Современные инструменты предпочитают exports, а старые используют main/module как резервный вариант.

Установка "type": "module" в package.json означает, что все файлы .js в пакете будут считаться ESM. Если вы поставляете оба формата, нужны явные расширения: при type: module используйте .mjs для файлов ESM и .cjs для файлов CJS или наоборот. tsup выполняет это автоматически.

Явное использование расширений файлов .mjs (ESM) и .cjs (CJS) обозначает формат независимо от поля type. Это устраняет неоднозначность. tsup может создавать файлы index.js (ESM) и index.cjs (CJS), когда формат задан как ['esm', 'cjs'], а поле type не указано, что соответствует наиболее распространённому соглашению.

Когда пакет предоставляет форматы ESM и CJS, сборщик пользователя может загрузить обе версии в одном процессе — например, версию ESM для основного приложения и версию CJS для теста Jest. Если в пакете есть состояние на уровне модуля, например контекст React, оба экземпляра будут иметь независимое состояние. Это и есть риск двухформатного пакета.

Чтобы снизить этот риск, не храните состояние на уровне модуля в библиотеке (не используйте шаблоны синглтонов), точно задавайте условия exports, чтобы загружался только один формат, и документируйте, что тесты должны настроить сборщик на использование ESM. Этот риск особенно важен для библиотек с общими синглтонами.

Проверьте работу обоих форматов после сборки. Протестируйте CJS: node -e "const lib = require('./dist/cjs/index.js'); console.log(lib)". Протестируйте ESM: node --input-type=module --eval "import { Component } from './dist/esm/index.js'; console.log(Component)". Перед публикацией оба формата должны разрешаться без ошибок.

Поле exports поддерживает несколько точек входа: { '.': { import: './dist/esm/index.js', require: './dist/cjs/index.js' }, './utils': { import: './dist/esm/utils.js', require: './dist/cjs/utils.js' } }. Затем пользователи импортируют из 'your-lib' или 'your-lib/utils' и получают подходящий формат.

Каково основное назначение поля exports в package.json библиотеки?

ESM использует import/export и позволяет удалять неиспользуемый код. CJS использует require() для совместимости с Node.js. Поставляйте оба формата через поле exports в package.json с условиями import/require. Резервные варианты для старых инструментов: main (CJS) и module (ESM). Используйте расширения .mjs/.cjs или type: module для явного обозначения формата. После сборки протестируйте оба формата с помощью CLI node. Помните о риске двухформатного пакета при наличии состояния синглтона.