package.json простыми словами: зависимости, скрипты и semver

Что такое package.json

package.json — файл в корне JavaScript-проекта, который описывает сам проект и всё, что ему нужно для работы. По нему npm, pnpm или yarn понимают, какие пакеты установить, а вы — какими командами запускать сборку, тесты и сервер.

Создать его можно командой npm init -y, но чаще он появляется вместе с шаблоном фреймворка.

Ключевые поля

{
  "name": "my-app",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "test": "vitest"
  },
  "dependencies": {
    "react": "^18.2.0"
  },
  "devDependencies": {
    "typescript": "~5.4.0"
  },
  "engines": {
    "node": ">=20"
  }
}

• name и version — имя и версия пакета. Обязательны, если вы публикуете библиотеку.
• private: true — защита от случайной публикации в npm. Ставьте для приложений.
• type — какую модульную систему использует Node.js для .js файлов: "module" (ES Modules) или "commonjs" (по умолчанию).
• scripts — именованные команды. Запускаются через npm run dev, а test и start — просто npm test и npm start.
• main / exports — точка входа для тех, кто импортирует ваш пакет.
• engines — какие версии Node.js поддерживаются. Помогает поймать несовместимость рано.

dependencies, devDependencies и peerDependencies

Для приложения, которое собирается в бандл, граница между первыми двумя условна, но для серверного кода и библиотек она важна: при установке в продакшене с флагом --omit=dev devDependencies не ставятся.

peerDependencies нужны авторам библиотек. Если ваша библиотека компонентов поставит собственную копию React, в проекте окажутся две копии — это приводит к ошибкам. Поэтому библиотека объявляет React как peer и использует ту версию, что уже есть у проекта.

Как читать версии: semver

Версия в формате MAJOR.MINOR.PATCH, например 4.17.2:

• MAJOR — ломающие изменения API.
• MINOR — новые возможности без поломок.
• PATCH — исправления ошибок.

Диапазоны в package.json:

Важная деталь: для версий 0.x каретка строже. ^0.4.2 разрешает только 0.4.x, потому что до 1.0 любое minor-обновление может ломать API.

Semver — договорённость, а не гарантия. Автор пакета может ошибиться и выпустить поломку в патче. От этого защищает lock-файл.

Зачем нужен lock-файл

package-lock.json (или pnpm-lock.yaml, yarn.lock) фиксирует точные версии всех пакетов, включая вложенные зависимости. Без него два разработчика, установившие проект в разные дни, могут получить разный код.

Правила:

• Коммитьте lock-файл в репозиторий всегда.
• На CI и сервере используйте npm ci — он ставит строго то, что записано в lock-файле, и падает, если lock и package.json расходятся.
• Не смешивайте менеджеры пакетов: один проект — один lock-файл.

Как безопасно обновлять пакеты

1. Посмотрите, что устарело: npm outdated.
2. Обновите в пределах диапазонов: npm update.
3. Мажорные версии обновляйте по одной, предварительно прочитав changelog и раздел о миграции.
4. После обновления запустите сборку и тесты.
5. Проверьте уязвимости: npm audit. Не применяйте npm audit fix --force вслепую — он может поднять мажорные версии.
6. Закоммитьте package.json и lock-файл вместе.

Удобно автоматизировать это ботами вроде Dependabot или Renovate: они открывают отдельный pull request на каждое обновление, и CI сразу показывает, что сломалось.

Частые ошибки

• lock-файл в .gitignore — сборки становятся непредсказуемыми.
• npm install вместо npm ci на сервере — lock-файл может перезаписаться.
• Сборочные инструменты в dependencies — продакшен-образ раздувается.
• Ручное редактирование lock-файла — меняйте его только через менеджер пакетов.