npm и экосистема пакетов
Первый npm install обычно проходит незаметно, а первая сломанная сборка после него — нет: локально всё работает, в CI падает, у коллеги ставится другая версия транзитивной зависимости. Причина почти всегда в одном из трёх: слишком широкий диапазон версий, отсутствие lockfile или неявная зависимость, которую никто не объявлял. Разберём, как npm выбирает версии, что именно фиксирует lockfile и как устроен монорепо, чтобы обновления оставались предсказуемыми.
Содержание
- Что такое npm и кто ещё есть на рынке
- package.json: контракт пакета
- semver: как читать диапазоны версий
- Типы зависимостей
- Lockfile и воспроизводимость сборки
- npm install, npm ci и npx
- Скрипты и lifecycle-хуки
- pnpm и workspaces
- Обновления, аудит и цепочка поставок
- Эксперименты, которые объясняют npm
- Ключевые тезисы для интервью
- Заключение
- Полезные ссылки
Что такое npm и кто ещё есть на рынке
Слово «npm» обозначает три разные вещи, и путаница между ними мешает понимать происходящее:
- реестр —
registry.npmjs.org, хранилище пакетов с метаданными и tarball-архивами; - CLI — команда
npm, которая ставит, публикует и обновляет пакеты; - сайт — витрина с документацией и статистикой.
CLI входит в поставку Node.js, поэтому отдельно устанавливать его не нужно. Но реестр — открытый протокол, и работать с ним умеют альтернативные менеджеры:
| Менеджер | Особенность |
|---|---|
| npm | эталон, входит в Node, плоский node_modules |
| pnpm | строгое дерево симлинков, общий content-addressable store |
| Yarn | исторически свой lockfile и PnP, сейчас ближе к остальным |
| Bun | менеджер вместе с рантаймом, ставит очень быстро |
Пакет в реестре — это архив с файлами плюс метаданные в package.json. Всё остальное в экосистеме выводится из этих двух вещей: как найти зависимости, какую версию считать совместимой и какой код выполнится при установке.
Практический вывод: выбор менеджера влияет на структуру node_modules и скорость, но контракт package.json и правила semver общие для всех.
package.json: контракт пакета
package.json — не просто список зависимостей, а описание того, как пакет подключается, собирается и публикуется.
{
"name": "@acme/taskflow-api",
"version": "1.4.0",
"private": true,
"type": "module",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.js",
"require": "./dist/index.cjs"
},
"./testing": "./dist/testing.js"
},
"files": ["dist"],
"engines": { "node": ">=22" },
"scripts": {
"dev": "node --watch src/server.js",
"test": "node --test",
"lint": "eslint ."
},
"dependencies": { "express": "^5.1.0" },
"devDependencies": { "eslint": "^9.20.0" }
}
| Поле | Зачем нужно |
|---|---|
name, version | идентичность пакета в реестре; вместе образуют уникальный ключ |
private | запрещает случайный npm publish |
type | "module" включает ESM для .js-файлов пакета |
exports | какие подпути и в каком формате доступны потребителю |
main | точка входа для старых резолверов; при наличии exports почти не используется |
files | что попадёт в tarball при публикации (белый список) |
scripts | команды для npm run и lifecycle-хуки |
engines | требуемая версия Node; проверяется при engine-strict |
packageManager | фиксирует менеджер и его версию для команды |
exports — это инкапсуляция
Пока в пакете нет exports, потребитель может импортировать любой файл: import x from 'pkg/dist/internal/helpers.js'. Как только exports объявлен, доступны только перечисленные подпути, а всё остальное закрыто.
Это ломает чужие глубокие импорты, и в этом смысл: внутренняя структура перестаёт быть публичным API, файлы можно перекладывать без мажорного релиза. Заодно exports решает задачу двойного формата: условия import и require отдают разные сборки одного пакета.
Порядок условий важен: резолвер берёт первое совпадение, поэтому types ставят первым, а default — последним. Подробнее о разрешении модулей — в статье про CommonJS и ESM этого раздела.
Приложение тоже описывается package.json
У сервиса нет публикации, но есть private: true, engines и packageManager — они защищают команду от запуска на чужой версии Node и от установки зависимостей другим менеджером с другим lockfile.
semver: как читать диапазоны версий
Версия MAJOR.MINOR.PATCH кодирует обещание:
- major — несовместимые изменения;
- minor — новая функциональность без поломок;
- patch — исправления без нового API.
Диапазон в package.json — это не версия, а правило выбора. Конкретную версию выбирает резолвер в момент установки.
| Запись | Что разрешает | Пример |
|---|---|---|
1.2.3 | ровно эту версию | 1.2.3 |
~1.2.3 | патчи внутри 1.2.x | 1.2.9, но не 1.3.0 |
^1.2.3 | минор и патч внутри 1.x | 1.9.0, но не 2.0.0 |
^0.2.3 | только 0.2.x | 0.2.9, но не 0.3.0 |
^0.0.3 | только 0.0.3 | следующая версия уже ломающая |
>=1.2.3 <2.0.0 | явный диапазон | 1.9.1 |
1.x | то же, что ^1.0.0 | 1.9.1 |
* | любую стабильную | непредсказуемо |
Два правила, которые чаще всего забывают:
- Ноль — особая зона. До
1.0.0публичного контракта нет, поэтому^0.2.3не разрешает0.3.0: каждый минор может быть ломающим. - Пререлизы не подпадают под обычные диапазоны.
^1.0.0не выберет1.5.0-beta.1, даже если она новее: беты подключают явно.
Главная оговорка: semver — обещание мейнтейнера, а не техническая гарантия. Патч может изменить поведение, минор — поменять тип или формат ответа. Поэтому диапазоны сочетают с lockfile: диапазон говорит, что допустимо, lockfile — что реально стоит.
Для приложений разумна стратегия «диапазон в манифесте, точная версия в lockfile». Для библиотек — наоборот: слишком узкий диапазон в зависимостях приводит к дублям в чужом дереве.
Формат можно закрепить в .npmrc:
save-exact=true
engine-strict=true
Первый параметр заставляет npm install pkg записывать точную версию, второй — падать при несовпадении engines.
Типы зависимостей
Все поля зависимостей отвечают на разные вопросы, и путать их — источник проблем в проде.
| Поле | Когда использовать | Попадает в прод |
|---|---|---|
dependencies | код, нужный в рантайме | да |
devDependencies | тесты, линтеры, сборка, типы | нет |
peerDependencies | пакет расширяет другую библиотеку | ставит потребитель |
optionalDependencies | платформенные бинарники, необязательные фичи | да, но сбой установки терпим |
dependencies и devDependencies
Граница проходит по вопросу «выполняется ли этот код в проде». express — да, eslint — нет. Отсюда и флаг --omit=dev при установке в контейнер.
Типичная ошибка — положить в devDependencies то, что нужно в рантайме, и получить MODULE_NOT_FOUND только после деплоя. Обратная ошибка — притащить в прод линтер и тестовый фреймворк, раздув образ на сотни мегабайт.
peerDependencies
Плагин объявляет, что работает рядом с библиотекой, но не приносит её с собой:
{
"name": "my-express-middleware",
"peerDependencies": { "express": "^5.0.0" }
}
Смысл в единственном экземпляре: два разных React или два DI-контейнера ломают хуки, токены и синглтоны, потому что у каждого своё состояние. Начиная с npm 7 неудовлетворённые peer-зависимости устанавливаются автоматически, а конфликт версий виден сразу в дереве, а не всплывает в рантайме. Если совместимость необязательна, пакет помечают в peerDependenciesMeta как optional.
optionalDependencies
Нужны для пакетов вроде esbuild или sharp: на неподдерживаемой платформе установка просто пропускается, а не валит весь npm install. Код обязан уметь работать без такого пакета — require может бросить исключение.
Lockfile и воспроизводимость сборки
package-lock.json (или pnpm-lock.yaml, yarn.lock) — снимок полного дерева зависимостей, а не только прямых.
Что в нём фиксируется:
- точная версия каждого пакета, включая транзитивные;
- URL, откуда он взят (
resolved); - хеш содержимого (
integrity, sha-512); - пометки
devиoptional; - структура дерева: кто от кого зависит.
Последний пункт объясняет, зачем файл нужен даже при точных версиях: одинаковый набор пакетов можно собрать в разную иерархию, и от неё зависит, какой экземпляр получит require.
Почему lockfile коммитят
- Воспроизводимость. Локально, в CI и в проде ставится одно и то же дерево.
- Предсказуемость обновлений. Новая версия появляется отдельным коммитом, который видно на ревью.
- Целостность. Если содержимое пакета в реестре подменили,
integrityне сойдётся и установка упадёт. - Скорость. Резолверу не нужно опрашивать реестр для каждой транзитивной зависимости.
Обратная сторона: lockfile конфликтует при мерже, потому что это машинно-сгенерированный файл. Правильное решение — перегенерировать его (npm install) после мержа package.json, а не воевать с конфликтными маркерами вручную.
Форматы и версии
package-lock.json версии 3 (npm 9+) хранит пакеты плоским списком с полями node_modules/.... pnpm-lock.yaml устроен иначе: отдельно описание импортёров (пакетов монорепо) и общий набор разрешённых версий, потому что pnpm хранит пакеты централизованно и не дублирует их на диске.
Форматы несовместимы, и это нормально: lockfile принадлежит менеджеру. Поэтому в проекте фиксируют менеджер полем packageManager, а в CI ставят зависимости только им.
npm install, npm ci и npx
Три команды, которые постоянно путают.
npm install
Режим разработки: читает package.json, разрешает диапазоны, при необходимости обновляет lockfile, достраивает node_modules. Может поставить версию новее той, что была, — именно так в проект попадают незапланированные обновления.
Полезные варианты:
npm install # всё, и dev, и prod
npm install --omit=dev # только прод-зависимости
npm install express@^5 # добавить и записать в dependencies
npm install --package-lock-only # обновить только lockfile
npm ci
Режим CI: ставит строго по lockfile.
npm ci --omit=dev
Отличия, которые важно помнить:
- требует наличия lockfile и падает, если он не совпадает с
package.json; - удаляет
node_modulesперед установкой — чистый слепок, без остатков; - не меняет ни
package.json, ни lockfile; - обычно быстрее за счёт отсутствия разрешения версий.
Логика простая: если сборка воспроизводима, то установка не должна ничего решать. npm install в CI — источник «работало вчера, упало сегодня».
npx
npx запускает бинарник из пакета, не добавляя его в проект. Сначала ищет в node_modules/.bin, затем скачивает во временный кэш.
npx eslint . # локальная версия, если установлена
npx --yes create-vite # скачать и запустить без вопросов
npx eslint@9 . # зафиксировать версию
Две привычки, которые экономят время:
- фиксируйте версию для одноразовых запусков:
npx pkg@1.2.3, иначе завтра приедет мажор; - не запускайте
npxот чужого имени в CI без понимания, что именно скачается: это установка и запуск произвольного кода.
Глобальные установки (npm i -g) оправданы только для CLI, которым вы пользуетесь вне проектов. Для всего остального локальная версия надёжнее: она зафиксирована в lockfile и одинакова у всей команды.
Скрипты и lifecycle-хуки
npm run — тонкая обёртка над shell-командой, но с двумя важными свойствами: в PATH добавляется node_modules/.bin, а скрипты с префиксами pre и post вызываются автоматически.
{
"scripts": {
"build": "tsc -p tsconfig.json",
"prebuild": "rimraf dist",
"test": "node --test",
"check": "npm run lint && npm run test"
}
}
Практические детали:
&&останавливается на первой ошибке,;— нет;- параллельный запуск удобнее через
concurrentlyилиnpm-run-all, а не через&, который ведёт себя по-разному в Windows и Unix; - аргументы передаются после
--:npm run test -- --watch; - для сервера хватает встроенных возможностей Node:
node --watchвместоnodemon,node --testвместо отдельного раннера.
Lifecycle-хуки
Помимо pre/post, npm вызывает специальные хуки:
| Хук | Когда выполняется |
|---|---|
preinstall, install, postinstall | сразу после установки пакета |
prepare | при локальной установке из git и перед публикацией |
prepublishOnly | только перед npm publish |
prepack | перед сборкой tarball |
postinstall — удобный инструмент (скачать бинарник, собрать нативный модуль) и одновременно главный вектор атаки на цепочку поставок: код выполняется с вашими правами ещё до того, как вы запустили приложение. Отсюда практика npm ci --ignore-scripts в CI и ignore-scripts=true в .npmrc для сред, где хуки не нужны.
prepare — частый источник сюрпризов: он запускается при npm install внутри самого пакета, поэтому тяжёлая сборка может стартовать в неожиданный момент. Хуки должны быть быстрыми и идемпотентными.
pnpm и workspaces
Пока проект один, разница между менеджерами — вопрос скорости. В монорепо она становится вопросом архитектуры.
Проблема монорепо
Несколько пакетов в одном репозитории хотят:
- ссылаться друг на друга без публикации в реестр;
- не дублировать общие зависимости на диске;
- обновлять версии согласованно;
- запускать команды только для затронутых пакетов.
npm workspaces
{
"name": "taskflow",
"private": true,
"workspaces": ["packages/*"]
}
npm создаёт симлинки на локальные пакеты в корневом node_modules и поднимает (hoisting) общие зависимости наверх. Удобно, но есть побочный эффект — phantom dependencies: пакет может импортировать библиотеку, которую не объявлял, просто потому что она оказалась в корне из чужой зависимости. Локально всё работает, после публикации — нет.
pnpm
pnpm решает обе задачи иначе:
- пакеты лежат в глобальном content-addressable store и подключаются жёсткими ссылками, поэтому одинаковые версии не занимают место дважды;
node_modules— строгое дерево симлинков: пакет видит только то, что объявил;- монорепо описывается в
pnpm-workspace.yaml:
packages:
- "apps/*"
- "packages/*"
Локальные связи объявляются явно протоколом workspace:*:
{
"dependencies": {
"@acme/shared": "workspace:*"
}
}
Полезные команды:
pnpm install --frozen-lockfile # аналог npm ci
pnpm --filter @acme/api test # команда только для одного пакета
pnpm --filter "...[origin/main]" build # для изменённых пакетов
pnpm dlx create-vite # аналог npx
Что выбрать
- Один сервис — npm: он уже стоит, возможностей хватает.
- Монорепо или несколько приложений — pnpm: строгость к зависимостям и экономия диска окупаются быстро.
- Yarn — если проект уже на нём; миграция ради миграции ничего не даёт.
Главное — один менеджер и один lockfile на репозиторий. Смешивать npm install и pnpm install в одном проекте нельзя: они по-разному раскладывают пакеты и перезаписывают чужой lockfile.
Обновления, аудит и цепочка поставок
Зависимости — это код, который вы не писали, но исполняете. Поэтому обновления и проверки — часть разработки, а не разовая акция.
Плановые обновления
npm outdated # что устарело и до какой версии можно подняться
npm update # обновить в рамках диапазонов
npm dedupe # схлопнуть дубли, если они появились
npm explain debug # почему в дереве именно эта версия
npm outdated показывает три версии: текущую, допустимую по диапазону (wanted) и последнюю (latest). Мажорные обновления делают осознанно, читая changelog и прогоняя тесты.
Автоматизация — Dependabot или Renovate: они открывают PR с обновлением и lockfile, а ревью сводится к проверке диффа и зелёного CI.
Аудит
npm audit --omit=dev # уязвимости в прод-зависимостях
npm audit fix # попытка починить в рамках диапазонов
Если исправленная версия лежит за пределами допустимого диапазона, помогает overrides:
{
"overrides": {
"minimist": "^1.2.8"
}
}
Это точечная хирургия: она меняет дерево для всех, кто тянет пакет, и требует проверки, что совместимость не сломалась.
Цепочка поставок
Что реально снижает риск:
- lockfile в git и ревью его диффа — новая версия или новый источник видно до установки;
--ignore-scriptsтам, где хуки не нужны;- фиксация версий в CI и
npx pkg@version; integrityи, для критичных пакетов, проверка provenance-аттестации;- скоуп-токены и 2FA при публикации, приватный реестр для внутренних пакетов;
- минимум зависимостей: каждая новая библиотека — это её транзитивное дерево и её хуки.
Перед публикацией полезно посмотреть, что именно уедет в реестр:
npm pack --dry-run
Белый список в files обычно лучше, чем .npmignore: забыть исключить секретный .env проще, чем забыть добавить dist.
Эксперименты, которые объясняют npm
Три коротких опыта, которые переводят теорию в наблюдаемое поведение.
1. Увидеть, откуда взялась версия
npm explain express
Команда показывает цепочку: кто требует пакет и какой диапазон разрешил текущую версию. Это первое, что стоит делать при «почему тут не та версия».
2. Проверить, что npm ci не прощает рассинхрон
rm -rf node_modules package-lock.json
npm ci
# npm error: The `npm ci` command can only install with an existing package-lock.json
Теперь то же самое, но npm install — он создаст lockfile и поставит всё. Разница в поведении и есть разница между воспроизводимой и «как получится» установкой.
3. Поймать phantom dependency
В проекте с npm workspaces создайте пакет, который импортирует библиотеку, объявленную только в соседнем пакете. Локально импорт сработает — зависимость поднялась в корень. В чистой установке без соседа тот же код упадёт. pnpm такое не позволяет по построению: пакет видит только своё объявленное дерево.
Ключевые тезисы для интервью
package.json— контракт пакета: зависимости, точка входа,exports, скрипты иengines; для приложения это ещё и фиксация менеджера и версии Node.- Диапазон версий задаёт допустимое множество, а не конкретную версию:
^1.2.3разрешает любой1.x,^0.2.3— только0.2.x, пререлизы не подпадают. - semver — обещание мейнтейнера; воспроизводимость даёт не он, а lockfile с точными версиями, URL и
integrity-хешами. npm installразрешает диапазоны и обновляет lockfile,npm ciставит строго по нему, не меняя манифест, и падает при рассинхроне — поэтому в CI только второй.peerDependenciesгарантируют единственный экземпляр общей библиотеки; npm 7+ ставит их автоматически, а плагин не приносит хост с собой.exportsзакрывает внутренности пакета и разводит ESM/CJS-сборки; после его появления глубокие импорты перестают работать — это часть контракта.- pnpm делает
node_modulesстрогим и запрещает phantom dependencies, а workspaces связывают пакеты монорепо протоколомworkspace:*без публикации.
Заключение
Экосистема npm держится на двух идеях: манифест описывает намерения, а lockfile фиксирует факт. Пока оба файла согласованы и лежат в git, обновление зависимостей — управляемое изменение, а не лотерея. Диапазоны версий задают политику обновлений, типы зависимостей — границу прод-кода, а менеджер пакетов определяет, насколько строго эта граница соблюдается. Дальше эти знания понадобятся везде: сборка образа, CI, публикация библиотеки и разбор конфликта версий начинаются с package.json и lockfile.
Полезные ссылки
- npm: документация CLI — команды, конфигурация,
npm ciиnpm install - package.json: описание полей —
exports,files,engines, зависимости - semver.org — спецификация версионирования
- node-semver — полный синтаксис диапазонов
- pnpm: документация — store, строгий
node_modules, workspaces - Node.js: как устроен рантайм — почему версия Node в
enginesвообще важна