npm — основы менеджера пакетов

Зачем нужно

npm (Node Package Manager) -- крупнейший в мире реестр программных пакетов (2M+ пакетов). Он позволяет устанавливать чужие библиотеки одной командой, управлять зависимостями проекта и публиковать свой код. Без npm пришлось бы вручную скачивать библиотеки, следить за их версиями и обновлять вручную.

Где используется

Установка библиотек (express, lodash, react, typescript)
Управление зависимостями проекта (package.json + lock-файл)
Запуск скриптов (npm run build, npm test)
Публикация собственных пакетов
Аудит безопасности зависимостей

Предпосылки

Установка и nvm — Node.js установлен, npm доступен
Что такое Node.js — модульная система
Базовые навыки работы с терминалом

Проверка установки

# npm устанавливается вместе с Node.js
node -v    # v22.12.0
npm -v     # 10.9.0

# Обновить npm до последней версии
npm install -g npm@latest

npm init — создание проекта

# Интерактивное создание package.json
npm init
# name: my-app
# version: 1.0.0
# description: My first Node.js project
# entry point: index.js
# ...

# Быстрое создание с дефолтами
npm init -y
# Создаёт package.json с defaults

{
  "name": "my-app",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": ,
  "author": "",
  "license": "ISC"
}

npm install — установка пакетов

Локальная установка (в проект)

# Установка в dependencies (--save по умолчанию с npm 5+)
npm install express
npm i express              # сокращение

# Установка в devDependencies
npm install --save-dev jest
npm i -D jest              # сокращение

# Установка конкретной версии
npm install lodash@4.17.21

# Установка диапазона
npm install react@^18.0.0

# Установка нескольких пакетов
npm install express cors helmet morgan

Куда устанавливается

my-project/
├── node_modules/          ← все пакеты (не коммитить!)
│   ├── express/
│   ├── lodash/
│   └── ... (может быть 1000+ папок)
├── package.json           ← список зависимостей
└── package-lock.json()      ← точные версии (коммитить!)

dependencies vs devDependencies

# dependencies — нужны в production
npm install express mongoose dotenv
# Использование: код приложения, серверный runtime

# devDependencies — нужны только при разработке
npm install -D jest eslint prettier nodemon typescript
# Использование: тесты, линтинг, сборка, hot-reload

# При деплое: установить ТОЛЬКО production-зависимости
npm install --production
# Или:
NODE_ENV=production npm install
# node_modules будет меньше — devDeps не установлены

Глобальная установка

# Установка глобально (-g) — доступна из любой директории
npm install -g nodemon
npm install -g typescript
npm install -g pm2

# Где хранятся глобальные пакеты
npm root -g
# /home/user/.nvm/versions/node/v22.12.0/lib/node_modules

# Список глобальных пакетов
npm list -g --depth=0
# /home/user/.nvm/versions/node/v22.12.0/lib
# ├── nodemon@3.0.2
# ├── npm@10.9.0
# └── typescript@5.3.3

Удаление, обновление, список

npm uninstall

# Удалить пакет из проекта
npm uninstall lodash
npm un lodash              # сокращение

# Удалить глобальный пакет
npm uninstall -g nodemon

npm update

# Обновить все пакеты (в рамках semver-диапазонов из package.json)
npm update

# Обновить конкретный пакет
npm update express

# Проверить устаревшие пакеты
npm outdated
# Package   Current  Wanted  Latest  Location
# express    4.18.2  4.18.3  4.19.2  my-app
# lodash    4.17.21 4.17.21  4.17.21 my-app

npm list

# Дерево зависимостей проекта
npm list
# my-app@1.0.0
# ├── express@4.18.2
# └── lodash@4.17.21

# Только верхний уровень
npm list --depth=0

# Только production
npm list --prod

# Почему пакет установлен (кто от него зависит)
npm explain mime

npm audit — безопасность

# Проверить зависимости на известные уязвимости
npm audit
# found 3 vulnerabilities (1 moderate, 2 high)

# Подробный отчёт
npm audit --json

# Автоматическое исправление (обновление пакетов)
npm audit fix

# Принудительное исправление (может сломать совместимость)
npm audit fix --force

npm cache

# npm кэширует скачанные пакеты для офлайн-установки

# Проверить целостность кэша
npm cache verify

# Очистить кэш (редко нужно)
npm cache clean --force

# Путь к кэшу
npm config get cache
# ~/.npm

npm registry

# По умолчанию — https://registry.npmjs.org

# Посмотреть текущий registry
npm config get registry

# Сменить на другой (например, корпоративный)
npm config set registry https://registry.company.com

# Для одного запроса
npm install express --registry https://registry.company.com

# Вернуть на дефолтный
npm config set registry https://registry.npmjs.org

Scoped пакеты (@scope/pkg)

# Scoped пакеты принадлежат организации или пользователю
npm install @types/node          # @types — организация DefinitelyTyped
npm install @babel/core          # @babel — организация Babel
npm install @my-company/utils    # приватный пакет организации

# Создать scoped пакет
npm init --scope=@my-org

# Публикация scoped пакета (по умолчанию приватный)
npm publish                      # приватный (нужна подписка)
npm publish --access public      # публичный

Полезные команды

# Информация о пакете
npm info express
npm info express version         # текущая latest версия
npm info express versions        # все версии

# Поиск пакетов
npm search json validator

# Открыть страницу пакета
npm docs express                 # откроет docs/homepage
npm repo express                 # откроет GitHub
npm bugs express                 # откроет issues

# Запуск скриптов из package.json
npm run build
npm run dev
npm test                         # сокращение для npm run test
npm start                        # сокращение для npm run start

# Создать ссылку на локальный пакет (для разработки)
cd my-library && npm link
cd my-app && npm link my-library

Альтернативы npm

yarn (Facebook/Meta):
  - Параллельная установка (быстрее npm v5)
  - yarn.lock вместо package-lock.json()
  - yarn add / yarn remove вместо npm install / npm uninstall
  - Workspaces для монорепозиториев

pnpm (performant npm):
  - Использует hard links (экономия диска)
  - Строгая структура node_modules (нет phantom deps)
  - В 2-3 раза быстрее npm на больших проектах
  - pnpm-lock.yaml

Bun (Jarred Sumner):
  - Runtime + пакетный менеджер + бандлер в одном
  - Самая быстрая установка пакетов
  - bun.lockb (бинарный lock-файл)
  - Совместим с npm-пакетами

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

Коммитят node_modules в git — директория огромная, добавь node_modules/ в .gitignore
Не коммитят package-lock.json() — без него npm install у коллеги поставит другие версии
Глобальная установка библиотек для проекта — npm i -g express неправильно, нужно локально
Путают dependencies и devDependencies — jest в dependencies увеличивает production-сборку
Игнорируют npm audit — уязвимости в зависимостях могут быть критическими
Удаляют node_modules и ставят заново — rm -rf node_modules && npm install вместо анализа проблемы

Практика

Создать проект с npm init -y, установить express и nodemon (как devDep)
Проверить что package.json содержит правильные dependencies/devDependencies
Запустить npm audit и изучить отчёт
Использовать npm list --depth=0 и npm outdated
Настроить npm-скрипт "dev": "nodemon index.js" и запустить через npm run dev

Связанные темы

Установка и nvm — установка Node.js и npm
npx — запуск пакетов без установки
package.json — структура файла конфигурации
Версионирование — semver и lock-файлы

Ресурсы

🎓 Источник: Настройка среды Node.js, npm, git, eslint

📅 2018-10-01 · YouTube · [Marp](../../../Documents/TimurShemsedinov/2018-10-01 — 💻 Настройка среды Node.js, npm, git, eslint (hSyA7tcNaCE).md)
Тезисы:
- npm i pkg --save — раньше нужен был флаг, с npm 5 по умолчанию
- Катастрофа left-pad (2016) — автор удалил 11-строчный пакет, упало пол-интернета → npm запретил удалять опубликованные пакеты
- package-lock.json хранит SHA-512 хеши + точные версии каждой транзитивной зависимости
- npm audit показывает CVE в зависимостях — но не паникуй, чаще false positive в devDeps
- 792 тысячи пакетов (на 2018) — 95% мусора, читай код того что ставишь
- Маска ^4.18.0 означает «совместимый минор», ~4.18.0 — «только патчи»
- npm publish отправляет пакет в реестр — нужен npm-аккаунт + npm login
Цитата: «Не доверяй ни одной зависимости, у которой меньше 5 contributors»

🎓 Источник: Летняя школа 2017 — Настройка среды

📅 2019-11-14 · YouTube
Тезисы:
- Раньше коммитили node_modules целиком — пока не появился package-lock.json
- npm test запускает lint + tap (или другой test runner)
- В npm 95% мусора — выбирай зависимости по числу contributors и недавним коммитам
- Дерево зависимостей может быть огромным: один Express тянет 30+ пакетов транзитивно