package.json
Тема дорожной карты · Node.js
package.json — это файл манифеста в корне каждого проекта Node.js, описывающий метаданные, версии зависимостей, npm-скрипты и конфигурацию для среды выполнения JavaScript и экосистемы инструментов. Ключевые поля package.json включают name и version для идентификации пакета, main и exports для точек входа модуля, scripts для команд жизненного цикла, dependencies для npm-пакетов времени выполнения, devDependencies для инструментов, нужных только при разработке, и engines для объявления минимальной поддерживаемой версии Node.js. Поле type в package.json — установленное в "module" или отсутствующее (CommonJS по умолчанию) — определяет, как Node.js интерпретирует файлы .js в этом пакете, что делает его одним из наиболее важных полей при миграции на TypeScript и ESM. Современные конфигурации package.json также используют карту exports для определения условных точек входа пакета для потребителей CommonJS и ESM одновременно, а поле workspaces — для управления пакетами монорепозитория с помощью npm или pnpm. Владение конфигурацией package.json необходимо для серверной разработки, публикации npm-пакетов и воспроизводимой настройки проектов Node.js.
Как это работает
package.json имеет два формата: CommonJS (legacy дефолт, require/module.exports, синхронный) и ES Modules (import/export, асинхронный, browser-compatible). Файлы резолвятся загрузчиком модулей: относительные пути → обход node_modules → встроенные. "type": "module" в package.json переключает дефолт для .js; расширения .mjs и .cjs форсируют формат. Conditional exports (exports в package.json) позволяют пакету поставлять оба формата.
Когда применять
Для новых проектов ESM — это стандарт JS, поддерживает top-level await, ожидается бандлерами/тулингом. CommonJS — только когда legacy-зависимости требуют или цена миграции запретительная. import("./mod.js") — для динамической / условной загрузки. Бандлер (esbuild, tsup) — только если публикуете пакет в обоих форматах; backend-сервисы обычно гоняют исходник.
Типичные ошибки
Ловушки package.json: пропущенное расширение .js в ESM-импортах (тихо ломается); циклические импорты (A → B → A — одна сторона получает partial export); случайный бандл CommonJS-only пакета в ESM-проект (interop болезненный); __dirname/__filename отсутствуют в ESM (используйте import.meta.url). Прочтите доку Node.js ESM перед битвой с "unexpected token".