npm — команды, зависимости и lock-файлы

ОБЯЗАТЕЛЬНОДЛЯ НОВИЧКОВ

Разработчику

---

npm — менеджер пакетов Node.js

npm (Node Package Manager) идёт вместе с Node.js и отвечает за три вещи: установку библиотек, запуск скриптов проекта и публикацию пакетов в реестр npmjs.com. Без уверенной работы с npm сложно подключить Express, тесты или TypeScript — вы будете копировать команды из README, не понимая, что они делают.

Теория runtime и event loop — в Node.js — серверный JavaScript. Структура папок и package.json поля — в Структура Node-проекта. Шпаргалка команд — в Справочник по Node.

Маршрут по блоку Node.js

Шаг	Статья
1	Первая программа — npm init, npm run
2	Node.js — основы
3	Вы здесь — npm углублённо
4	Структура проекта
5	Express

---

Проверка npm

node -v
npm -v

Разбор:

• npm ставится вместе с Node.js с nodejs.org (LTS).
• Версия npm влияет на формат lock-файла и поведение npm audit.
• На Linux не используйте устаревший apt install nodejs без официального репозитория — часто нет актуального npm.

---

Инициализация проекта

mkdir my-api && cd my-api
npm init
npm init -y

Разбор:

• npm init задаёт вопросы интерактивно (имя, версия, лицензия).
• npm init -y создаёт package.json с дефолтами — удобно для учебных проектов.
• Файл package.json — манифест: имя пакета, скрипты, зависимости. Подробнее о полях — 266.md.

Минимальный пример после npm init -y:

{
  "name": "my-api",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node src/index.js"
  }
}

Поле "type": "module" включает ESM (import / export) в .js-файлах. Без него Node по умолчанию ожидает CommonJS (require).

---

Установка зависимостей

Команда	Действие
npm install	Всё из package.json по lock-файлу
npm install express	Пакет в dependencies
npm install -D jest	Пакет в devDependencies (--save-dev)
npm install -g typescript	Глобально (редко нужно в проектах)
npm uninstall express	Удалить из манифеста и node_modules
npm ci	Чистая установка только по lock (CI/CD)

Разбор:

• dependencies — нужны при запуске приложения (Express, pg).
• devDependencies — только для разработки (eslint, vitest, nodemon).
• npm ci удаляет node_modules и ставит версии строго из package-lock.json — используйте в пайплайнах, не npm install.

После установки пакеты лежат в node_modules/. Папку не коммитят — восстанавливают командой npm install или npm ci.

Как npm раскладывает пакеты

С версии npm 3+ дерево плоское: общие зависимости поднимаются в корневой node_modules. При конфликте версий npm может создать вложенный node_modules внутри пакета-«виновника».

my-api/
├── node_modules/
│   ├── express/
│   ├── debug/          ← общая транзитивная зависимость
│   └── .bin/           ← CLI: nodemon, tsc, …
├── package.json
└── package-lock.json

require('express') или import … from 'express' ищут модуль в node_modules, поднимаясь от текущего файла к корню проекта.

---

Версии: SemVer и символы в package.json

Формат SemVer: MAJOR.MINOR.PATCH (например 4.19.2).

Запись в package.json	Диапазон
1.2.3	Точная версия
~1.2.3	Патчи: >=1.2.3 <1.3.0
^1.2.3	Минор + патч: >=1.2.3 <2.0.0
*	Любая (не используйте в production)

Практика:

• в библиотеках — осторожно с ^;
• в приложениях — фиксируйте lock-файл и проверяйте npm outdated перед обновлениями.

npm outdated
npm update

npm update поднимает версии в пределах диапазонов из package.json и обновляет lock.

---

Скрипты в package.json

{
  "scripts": {
    "dev": "nodemon src/index.js",
    "start": "node src/index.js",
    "test": "node --test",
    "lint": "eslint ."
  }
}

npm run dev
npm start
npm test

Разбор:

• npm run <имя> выполняет команду из scripts и добавляет node_modules/.bin в PATH.
• npm start и npm test — сокращения для npm run start / npm run test (если скрипт объявлен).
• Префиксы pre / post: prebuild запустится перед build, postinstall — после npm install.

Переменные окружения в скриптах:

• Unix: NODE_ENV=production node app.js
• Windows cmd: set NODE_ENV=production && node app.js
• Кроссплатформенно: пакет cross-env — cross-env NODE_ENV=production node app.js

Подробнее про порядок скриптов в команде — CLI и деплой.

---

Безопасность и аудит

npm audit
npm audit fix
npm audit fix --force

Разбор:

• npm audit сравнивает дерево зависимостей с базой уязвимостей.
• npm audit fix обновляет совместимые патчи автоматически.
• --force может поднять major-версии — проверяйте тесты после.

Дополнительно: Dependabot, Snyk, политики в корпоративном npm Enterprise.

npm license

Показывает лицензии зависимостей — важно для compliance.

---

Публикация пакета

Если вы делаете библиотеку для других команд, после npm login достаточно npm publish на npmjs.com (для открытых пакетов — бесплатно). Имя в package.json должно быть уникальным; поле "files" задаёт, что попадёт в архив.

npm login
npm publish

В учебных API-проектах публикация в npm обычно не требуется — храните код в Git.

---

npm, yarn и pnpm

Критерий	npm	Yarn (Berry)	pnpm
Lock-файл	package-lock.json	yarn.lock	pnpm-lock.yaml
Скорость	Хорошая	Очень быстрая (Berry)	Часто самая быстрая
Диск	Дубли версий	Зависит от режима	Один store + ссылки
Workspaces	npm 7+	Да	Стабильные monorepo
Когда брать	Стандарт, GitHub Packages	Zero-install, strict	Monorepo, CI с лимитом диска

Все три читают один package.json. Смена менеджера: удалить node_modules и чужой lock, затем install новым инструментом.

---

Типичные ошибки

Симптом	Причина	Решение
Cannot find module	Нет установки	npm install в корне с package.json
Разные версии у коллег	Нет lock в Git	Коммитить package-lock.json, в CI — npm ci
ERESOLVE	Конфликт peer dependencies	Читать лог, выровнять версии или --legacy-peer-deps (временно)
Скрипт не найден	Опечатка в scripts	npm run без аргумента покажет список
Глобальный пакет не находится в PATH	PATH	npx или локальный devDependency

npx create-vite@latest my-app

npx скачивает и запускает CLI без глобальной установки.

---

Связанные материалы

Тема	Материал
Папки src/, config/, конвенции	266.md
node --watch, Docker, PM2	267.md
Первая программа с Express	262.md
Таблицы API	261.md

---

Основа по протоколу

Базовый разбор HTTP и HTTPS — HTTP как основа веб-интеграций.