Краткая памятка по командам npm

npm-tooltips.md

Памятка по работе с npm

npm используется постоянно и потому полезно всегда иметь под рукой шпаргалку по наиболее частым командам. Настоящая памятка — подборка выдержек из официальной документации и личного опыта.

Исчерпывающая документация размещена тут npm Documentation.

Кратко об npm

npm (node package manager) — пакетный менеджер для node.js включает в себя:

• сайт npmjs.com,
• интерфейс командной строки,
• реестр.

На сайте можно удобно искать нужные пакеты, управлять учётной записью, доступностью пакетов и прочее.

Интерфейс командной строки — это основной интерфейс взаимодействия разработчиков с npm.

Реестр — огромная публичная база программных пакетов на JavaScript, и сопутствующих данных.

Ниже речь идёт именно о работе в командной строке.

Установка пакетов

Пакеты в npm могут быть установлены локально и глобльно.

При локальной установке пакет сохраняется в папку node_modules текущего проекта и может быть подключен как зависимость посредством require().

При глобальной установке файлы пакета сохраняются в глобальной папке %AppData%\Roaming\npm\node_modules (для Windows), а сам пакет становится доступен для вызова из командной строки.

Установка пакета осуществляется по команде npm install. У неё, как и у многих других команд и флагов, есть сокращённая форма npm i <package_name>. Здесь и далее, будут приведены команды в сокращённой форме.

Локальная установка

# Устанавливает пакет <package_name>
npm i <package_name>

# Устанавливает все пакеты, перечисленные в package.json
npm i

# Устанавливает <package_name> и вносит запись о нём в package.json в раздел dependencies
npm i <package_name> -S

# Устанавливает <package_name> и вносит запись о нём в package.json в раздел devDependencies
npm i <package_name> -D

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

# Устанавливает пакет <package_name> глобально
npm i <package_name> -g

#  Папка, в которую устанавливаются глобальные пакеты
npm root -g

Установка пакета определённой версии

npm i <package_name>@x.x.x

Установка пакета с GitHub

В примерах выше рассматривалась установка пакетов с сервера npm, но с помощью npm install пакеты можно устанавливать и из репозитория GitHub:

npm install git://github.com/user-name/package-name.git#v0.1.0

Работа с файлом package.json

Файл package.json — самый удобный способ управлять локально установленными пакетами.

Файл package.json располагается в корневой папке проекта и выполняет следующие функции:

• хранит список зависимостей проекта,
• позволяет указывать версии используемых в проекте пакетов,
• обеспечивает воспроизводимость сборки и, тем самым, упрощает обмен кодом.

В файле обязательно должны присутствовать название и версия проекта. Название пишется слитно строчными буквами с «-» или «_» вместо пробелов. Версия записывается формате SemVer: x.x.x.

К примеру:

{
  "name": "my-awesome-package",
  "version": "1.0.0"
}

Создание package.json

Для создания package.json в диалоговом режиме используется команда инициализации проекта:

npm init

Команда запустит опросник, по прохождении которого в папке проекта будет создан файл package.json.

Эту процедуру можно упростить и создать package.json со значениями по умолчанию на основании информации из текущей директории:

npm init -y

package.json в этом случае заполняется так:

• name: имя текущей директории
• version: 1.0.0 (по умолчанию )
• description: пустая строка или первая строка файла readme
• main: index.js ( по умолчанию )
• scripts: пустой скрипт test (по умолчанию)
• keywords: пусто
• author: пусто
• license: ISC (по умолчанию)
• bugs: информация из текущей директории, если есть
• homepage: информация из текущей директории, если есть

Некоторые значения для полей package.json можно задать глобально:

> npm set init.author.email "author-email"
> npm set init.author.name "author-name"
> npm set init.license "MIT"

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

В файле package.json перечислятся внешние зависимости проекта:

• в разделе dependencies для продакшн-версии приложения,
• в разделе devDependencies для разработки.

Пример:

{
  "name": "my_package",
  "version": "1.0.0",
  "dependencies": {
    "my_dep": "^1.0.0"
  },
  "devDependencies" : {
    "my_test_framework": "^3.1.0"
  }
}

Зависимости можно прописывать вручную в файле, но удобнее это делать посредством команд npm:

# Добавление записи в раздел dependencies
npm install <package_name> [--save-prod]
# Синоним
npm i <package_name> -S

# Добавление записи в раздел devDependencies
npm install <package_name> --save-dev
# Синоним
npm i <package_name> -D

# Установить только продакшн-зависимости
npm i --only=production

Дабы не утруждать себя, каждый раз указывая --save, можно прописать:

# Все - теперь все устанавливаемый пакеты будут автоматом прописываться в package.json
npm config set save true
# Короче
npm c set save true

Управление пакетами

Получение списка установленных пакетов

# Список локально установленных пакетов
npm list --depth=0

# Список глобально установленных пакетов
npm list --depth=0 -g

Отображение установленной версии пакета

npm list <package_name>

Обновление локальных пакетов

Полезно время от времени проверять не устарели ли зависимости, используемые в проекте. Чем совершеннее зависимости, тем совершеннее проект в целом.

Алгоритм обновления такой:

# Выявляем пакеты, требующие обновления
npm outdated --depth=0
# Запускаем обновление
npm up
# Проверяем, всё ли обновилось: результат должен быть пустым
npm outdated

Обновление конкретного пакета

# Выявляем пакеты, требующие обновления
npm outdated -g --depth=0
# Обновляем все пакеты
npm up -g
# Обновляем конкретный пакет
npm up -g <package_name>

Обновление глобальных пакетов

npm outdated -g --depth=0

Удаление локальных пакетов

Фактически это удаление папки с названием пакета из директории node_modules и изменение соответствующей записи в файле package.json:

npm uninstall <package_name>
# Сокращения: remove, rm, r, un, unlink

В режиме глобального удаления, менеджер удаляет указанный пакет глобально:

npm r <package_name> -g

Команда npm uninstall принимает 3 альтернативных необязательных флага, изменяющих файл package.json:

• -S, --save: пакет удаляется из продакшн-зависимостей,
• -D, --save-dev: пакет удаляется из дев-зависимостей,
• -O, --save-optional: пакет удаляется из опциональных зависимостей,
• --no-save: пакет не будет удалён из package.json.

При запуске npm uninstall будет также обновлён файл npm-shrinkwrap.json.

Другие возможности

Фиксация версий зависимостей

Прежде чем передавать продукт в промышленную эксплуатацию, необходимо зафиксировать точные версии пакетов, с которыми всё 100% работает. Следующая команда так и сделает. После её выполнения будет создан shrinkwrap.json, в котором будут прописаны точные версии ваших пакетов, теперь npm install будет устанавливать именно их.

# Теперь можно передавать в продакшен
npm shrinkwrap

Обновление версии npm

# Текущая версия npm
npm -v
# NPM вполне может обновлять сама себя
npm i npm@latest -g

Удаление неиспользуемых пакетов

npm prune

# Удалить все дев-зависимости из node_modules
npm prune --production

Удаление дубликатов

npm dedupe

Работа с кэшем пакетов

# Вывести список кэшированных пакетов
npm cache ls

# Установить пакет из кэша
npm install --cache-min 999999 package-name

# Очистить кэш npm
npm cache clean -f

Перечень всех настроек

# Выведет список всех возможных настроек
npm config ls -l
# Если короче
npm c ls -l

Аудит безопасности

Аудит безопасности — проверка зависимостей пакетов на наличие уязвимостей. Аудит позволяет пользователей приложения, благодаря поиску и исправлению известных уязвимостей в зависимостях, которые могут привести к потере данных, недоступности сервисов, НСД и другим.

# Команда выявляет уязвимости
npm audit
# Устранение уязвисомтей
npm audit fix