main, exports, imports и conditional exports в package.json
На этой странице
main, exports и imports управляют тем, какие файлы пакета доступны для загрузки. main задает старую точку входа, exports явно описывает публичный API пакета, а imports задает внутренние алиасы.
Conditional exports позволяют пакету отдавать разные файлы в зависимости от способа загрузки или окружения: import, require, node, browser, default и других условий.
Вопрос
Что такое main, exports, imports и conditional exports в package.json?
main
main - классический способ указать entry point пакета.
{
"name": "my-lib",
"main": "./dist/index.cjs"
}Если другой проект сделает require('my-lib'), Node.js пойдет в этот файл.
exports
exports современнее и строже. Он ограничивает, какие пути доступны извне.
{
"name": "my-lib",
"exports": {
".": "./dist/index.js",
"./format": "./dist/format.js"
}
}Теперь можно:
import { format } from 'my-lib/format';Но нельзя импортировать случайный внутренний файл, если он не экспортирован.
imports
imports задает приватные алиасы внутри пакета. Такие имена начинаются с #.
{
"imports": {
"#db": "./src/db.js"
}
}import { db } from '#db';Conditional exports
Один пакет может поддерживать и ESM, и CommonJS.
{
"name": "my-lib",
"exports": {
".": {
"import": "./dist/index.js",
"require": "./dist/index.cjs"
}
}
}ESM-код получит один файл:
import lib from 'my-lib';CommonJS-код получит другой:
const lib = require('my-lib');Частые условия
| Условие | Когда применяется |
|---|---|
import | при ESM import |
require | при CommonJS require |
node | в Node.js |
default | fallback |
Подводные камни
Conditional exports могут создать dual package hazard: ESM и CJS-версии пакета могут иметь разные экземпляры состояния.
// Если разные entry points создают разные singleton-объекты,
// состояние может разъехаться между import и require.Что важно помнить
- При наличии
exportsон имеет приоритет надmainи закрывает недекларированные пути. - Условия проверяются по порядку:
typesставят первым,default— последним. importsс префиксом#— приватные алиасы внутри пакета.- Добавление
exportsв существующую библиотеку может сломать пользователей — это breaking change.
Мини-шпаргалка
main- старая точка входа.exports- явный публичный API пакета.imports- внутренние алиасы пакета.exportsпомогает не ломать пользователей случайными internal imports.- Для библиотек
exportsпочти всегда полезен. - Conditional exports выбирают файл по условию.
- Это важно для библиотек, которые поддерживают CJS и ESM.
- Порядок условий имеет значение.
defaultиспользуют как fallback.- Следи, чтобы разные entry points не ломали общий state.
Документация
Node.js: Package entry points, Node.js: Conditional exports, Node.js: Subpath imports.