Навигация

npm и экосистема пакетов

Первый npm install обычно проходит незаметно, а первая сломанная сборка после него — нет: локально всё работает, в CI падает, у коллеги ставится другая версия транзитивной зависимости. Причина почти всегда в одном из трёх: слишком широкий диапазон версий, отсутствие lockfile или неявная зависимость, которую никто не объявлял. Разберём, как npm выбирает версии, что именно фиксирует lockfile и как устроен монорепо, чтобы обновления оставались предсказуемыми.

Содержание

  1. Что такое npm и кто ещё есть на рынке
  2. package.json: контракт пакета
  3. semver: как читать диапазоны версий
  4. Типы зависимостей
  5. Lockfile и воспроизводимость сборки
  6. npm install, npm ci и npx
  7. Скрипты и lifecycle-хуки
  8. pnpm и workspaces
  9. Обновления, аудит и цепочка поставок
  10. Эксперименты, которые объясняют npm
  11. Ключевые тезисы для интервью
  12. Заключение
  13. Полезные ссылки

Что такое 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.x1.2.9, но не 1.3.0
^1.2.3минор и патч внутри 1.x1.9.0, но не 2.0.0
^0.2.3только 0.2.x0.2.9, но не 0.3.0
^0.0.3только 0.0.3следующая версия уже ломающая
>=1.2.3 <2.0.0явный диапазон1.9.1
1.xто же, что ^1.0.01.9.1
*любую стабильнуюнепредсказуемо

Два правила, которые чаще всего забывают:

  1. Ноль — особая зона. До 1.0.0 публичного контракта нет, поэтому ^0.2.3 не разрешает 0.3.0: каждый минор может быть ломающим.
  2. Пререлизы не подпадают под обычные диапазоны. ^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.

Полезные ссылки