re:re:actable
Урок 022 минуты чтения

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
defaultfallback

Подводные камни

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.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам