package.json, npm, semver и lock-файлы

package.json: манифест намерения

package.json — это контракт Node-проекта: идентичность, скрипты и от чего он зависит. Поля, которые отрабатывают свой хлеб на уровне middle+:

{
  "name": "billing-service",
  "version": "2.4.1",
  "type": "module",
  "engines": { "node": ">=20" },
  "exports": { ".": "./dist/index.js" },
  "scripts": { "build": "tsc", "test": "vitest run" },
  "dependencies": { "pino": "^9.0.0" },
  "devDependencies": { "vitest": "~2.1.0", "typescript": "5.6.3" },
  "peerDependencies": { "react": ">=18" },
  "optionalDependencies": { "fsevents": "^2.3.0" }
}

"type": "module" решает, как Node трактует .js-файлы (ESM vs CommonJS — прошлый урок). "exports" — современная карта входов: она задаёт ровно те пути, которые потребителям разрешено импортировать, и прячет всё остальное, поэтому глубокие импорты в твои внутренности перестают работать — она вытесняет старое одиночное поле "main". "engines" объявляет диапазон Node, который ты поддерживаешь; со строгой конфигурацией установщика это может жёстко уронить установку на неверном runtime, а не падать загадочно во время выполнения.

Четыре корзины зависимостей не взаимозаменяемы:

• dependencies — нужны в runtime любому, кто ставит твой пакет. Отгружаются.
• devDependencies — нужны только для сборки и тестов (компиляторы, тест-раннеры, линтеры). Ставятся локально, пропускаются при npm install --omit=dev / NODE_ENV=production.
• peerDependencies — «я работаю вместе с этим, но host-приложение должно его предоставить». React-плагин указывает react здесь, чтобы делить единственную копию хоста, а не тащить второй, дублирующий React.
• optionalDependencies — установка пробуется, но провал не фатален; твой код обязан подстраховаться на случай отсутствия. Используется для платформенных нативных аддонов вроде fsevents (только macOS).

Semver: диапазон — это обещание, а не пин

Версии — это MAJOR.MINOR.PATCH, и по спеке npm каждая цифра — обещание потребителям: PATCH = обратно-совместимые багфиксы (1.0.0 → 1.0.1), MINOR = обратно-совместимые новые фичи (1.0.0 → 1.1.0), MAJOR = изменения, ломающие обратную совместимость (1.0.0 → 2.0.0). Версия может нести prerelease-тег вроде 1.0.0-beta.2, который сортируется до 1.0.0 и исключается из обычных диапазонов, пока ты явно не попросишь.

То, что ты пишешь в package.json, — обычно диапазон, и оператор решает, сколько дрейфа ты принимаешь на следующей установке:

^ — это то, что npm install <pkg> пишет по умолчанию, потому что он подхватывает багфиксы и новые фичи автоматически, при этом обещая никогда не пересекать мажор. Риск прямо в хуке: это обещание зависит от того, версионирует ли мейнтейнер честно. Библиотека, выкатившая ломающее изменение как minor — или просто случайную регрессию в patch — потечёт прямо в твоё дерево на следующей не-запиненной установке. ^ решает потолок того, что может войти. Что реально вошло в прошлый раз, решает кое-что другое.

Lockfile: что реально установилось

package.json отвечает на «что я готов принять?» package-lock.json отвечает на «что я получил?» Когда npm разрешает твои диапазоны, он обходит весь граф зависимостей — твои зависимости, их зависимости, до самого низа — выбирает конкретную версию для каждого узла и пишет всё уплощённое дерево в lockfile: точные версии, разрешённый URL registry и хэш integrity (SHA в духе Subresource Integrity для tarball’а). На следующей установке npm может пересобрать байт-в-байт идентичный node_modules и проверить каждую загрузку против её хэша.

Это и есть граница между двумя командами установки, и это сеньорный пойнт урока:

Сеньорное правило вытекает из таблицы. Коммить lockfile, и в CI запускай npm ci, а не npm install. npm ci детерминирован (игнорирует диапазоны и ставит ровно то, что залокано), чист (сначала стирает node_modules, так что не остаётся обрывков состояния), быстр (пропускает шаг разрешения) и — критично — падает громко, если package-lock.json и package.json разошлись, вместо того чтобы молча переписать lock, как сделал бы npm install. Это падение — фича: оно ловит вручную отредактированный манифест, который никто не перелочил, до того как он уедет.

# Локально: меняем deps, что обновляет package.json И package-lock.json
npm install lodash      # добавляет "^4.x" в deps, пишет разрешённое дерево в lock
git add package.json package-lock.json   # коммить ОБА, вместе

# CI / Dockerfile: воспроизводим залоканное дерево точно, падаем при дрейфе
npm ci                  # чисто, детерминированно, ошибка если lock рассинхронен

node_modules: уплощение, hoisting и фантомы

npm ставит в node_modules как плоское дерево там, где может: вместо вложения каждой зависимости внутрь родителя он поднимает (hoist) общие, совместимые версии наверх, чтобы много пакетов делили одну копию. Это держит дерево мелким и маленьким — но оно протекает. Пакет, который твоё приложение никогда не объявляло, может оказаться поднятым на верх node_modules, и require("that-package") сработает на твоей машине. Это фантомная зависимость: ты используешь то, чего нет в твоём package.json. В день, когда апгрейд зависимости перестанет её поднимать — или свежая установка разрешит другое дерево — твой импорт исчезнет, и сборка сломается, а в манифесте ничего не объяснит почему.

Это одна из причин, по которой существует pnpm: он строит строгий, симлинкованный node_modules, где пакет видит только то, что явно объявил, превращая фантомные зависимости в жёсткую ошибку, а не в тихий костыль. Yarn — другая крупная альтернатива, со своим lockfile (yarn.lock) и, в современных версиях, режимом Plug’n’Play, который вообще убирает node_modules. Все три решают ту же задачу, что и npm; различаются форматом lockfile и тем, насколько агрессивно изолируют дерево. Переносимый урок не зависит от инструмента: объявленная зависимость плюс закоммиченный lockfile — единственная комбинация, которая воспроизводится.