Package exports и условия: контракт публичного API

exports перекрывает main и запечатывает пакет

Классическое поле main называет одну точку входа и оставляет остальной пакет нараспашку: любой потребитель может require("pkg/src/internal/helper.js"), потому что разрешение просто идёт по файловой системе. Поле exports переворачивает это. В момент, когда пакет объявляет exports, разом вступают в силу три правила:

• Оно перекрывает main. Node сверяется с exports первым; main — лишь запасной вариант для пакетов без exports.
• Это белый список, а не подсказка. Любой подпуть, не указанный, становится недостижимым — ERR_PACKAGE_PATH_NOT_EXPORTED — даже если файл физически существует. Это инкапсуляция: автор пакета решает публичную поверхность, а внутренности можно свободно рефакторить, потому что их никто не мог легально импортировать.
• package.json нужно экспортировать явно, если потребители (или инструменты) его читают: "./package.json": "./package.json".

Вместе эти три правила превращают пакет из открытого-по-умолчанию в запечатанный-по-контракту. Без третьего правила инструменты молча ломаются; без второго — нет настоящей API-границы, и любой глубокий require("pkg/dist/internal"), работавший годами, продолжает работать, лишая тебя возможности безопасно рефакторить внутренности.

{
  "name": "mylib",
  "exports": {
    ".": "./dist/index.js",
    "./package.json": "./package.json"
  }
}

С этим import "mylib" разрешается в dist/index.js, а import "mylib/dist/anything-else.js" бросает — дверь глубоких импортов закрыта. Это и есть senior-причина добавлять exports осознанно: это единственный механизм, который Node даёт для проведения настоящей API-границы вокруг пакета, превращая «каждый файл публичен» в «публично лишь то, что я публикую».

Подпути-экспорты и шаблоны

Ключ . — корень пакета; дополнительные ключи задают подпути-экспорты — именованные точки входа, доступные потребителю как pkg/<подпуть>:

{
  "exports": {
    ".": "./dist/index.js",
    "./parser": "./dist/parser.js",
    "./utils/format": "./dist/utils/format.js"
  }
}

import "mylib/parser" теперь отображается в dist/parser.js — заметь, что публичное имя (/parser) отвязано от физического пути (dist/parser.js), поэтому файлы можно перемещать внутри, не ломая потребителей, пока карта стабильна. Для множества подпутей шаблоны с * избавляют от ручного перечисления. * — нежадный подстановочный знак, захватываемый слева и подставляемый справа:

{
  "exports": {
    ".": "./dist/index.js",
    "./features/*": "./dist/features/*.js"
  }
}

Здесь import "mylib/features/auth" разрешается в dist/features/auth.js. Шаблоны экспонируют целую директорию одним правилом, поэтому применяй их, когда действительно хочешь сделать это поддерево публичным — и помни о компромиссе инкапсуляции: широкий шаблон ./* вновь раскрывает пакет почти так же широко, как полное отсутствие exports.

Условные экспорты: один спецификатор, много целей

Значением подпути может быть объект условий вместо строки: Node проходит его ключи по порядку и берёт первый, чьё условие совпало с текущей средой. Так один пакет отдаёт ESM на import и CommonJS на require:

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "default": "./dist/index.mjs"
    }
  }
}

Порядок значим — выигрывает первое совпадение, а не самое специфичное — поэтому общепринятый порядок: types первым (инструменты читают его до запуска кода), затем рантайм-условия, затем default последним как заглушка-перехватчик. Частые условия:

Поле imports: приватные внутренние спецификаторы

Где exports определяет наружный API, родственное поле imports определяет внутренние псевдонимы — приватные спецификаторы, всегда с префиксом #, видимые только внутри самого пакета:

{
  "imports": {
    "#db": {
      "node": "./src/db/postgres.js",
      "default": "./src/db/memory.js"
    },
    "#internal/*": "./src/internal/*.js"
  }
}

Внутри пакета ты пишешь import db from "#db", и Node разрешает его через карту — с полной поддержкой условий, так что #db может указывать на реальную БД на Node и на in-memory-заглушку в другом месте. В отличие от относительного пути, спецификатор # стабилен независимо от глубины вложенности импортирующего файла, и в отличие от голого спецификатора он никогда не убегает в node_modules. Это чистый способ внутреннего алиасинга без сборщика и фокусов с tsconfig paths.

Dual-package hazard

Условные экспорты позволяют легко поставлять и ESM-, и CJS-сборку. Ловушка: если обе сборки несут состояние, приложение может загрузить обе — ESM-код достигает цели import, CJS-код достигает цели require — и теперь сосуществуют два отдельных экземпляра модуля твоего пакета, у каждого своя копия каждой переменной, реестра и instanceof-идентичности. Синглтоны молча двоятся; объект, созданный одной половиной, проваливает проверку instanceof в другой. Это dual-package hazard (ловушка двух экземпляров одного пакета).

// Приложение случайно загружает обе половины:
import { registry } from "mylib";        // → dist/index.mjs экземпляр A
const { registry: r2 } = require("mylib"); // → dist/index.cjs экземпляр B
// registry !== r2  — два состояния, hazard

Надёжные способы избежать, по убыванию предпочтительности: (1) поставлять только ESM и дать CJS-потребителям доступ через динамический import(), чтобы был ровно один экземпляр; либо (2) держать всю состояние-несущую логику в едином CJS- (или едином ESM-) ядре, а другое условие сделать тонкой обёрткой, реэкспортирующей тот же экземпляр, а не вторую копию. Антипаттерн — две независимые полные сборки, каждая со своим состоянием — именно эта конфигурация кусается.