npm: настройка зависимостей и скриптов в проектах Node.js

Раздел: Backend -> Node.js (базовый)

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

npm (Node Package Manager) является стандартным инструментом для управления зависимостями в проектах Node.js. Он позволяет устанавливать, обновлять, удалять и публиковать пакеты, а также управлять скриптами и версиями. Основная цель npm - упростить процесс работы с внешними модулями и их версионирование.

Как инициализировать проект и создать package.json?

Для начала работы с npm в проекте требуется файл package.json. Его можно создать интерактивно с помощью команды npm init.

npm init

Node js https (https в node.js)

После ввода ключевых полей (имя, версия, описание, точка входа, тесты, репозиторий, лицензия) будет создан файл package.json. Если требуется автоматическое создание с значениями по умолчанию, используется флаг -y или --yes.

npm init -y

Node js lts (версия node.js lts)

Пример полученного package.json:

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

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

Частая проблема: при вводе названия пакета с пробелами или заглавными буквами может возникнуть предупреждение о несовместимости с npm. Решение - использовать только строчные латинские буквы, дефисы или подчеркивания.

Как установить пакет и сделать его зависимостью?

Команда npm install (сокращённо npm i) устанавливает пакет и добавляет запись в package.json. Флаг --save (по умолчанию) помещает пакет в секцию dependencies. Для разработки (тесты, сборщики) используется флаг --save-dev, который добавляет пакет в devDependencies.

npm install express
npm install --save-dev jest

Node js scripts (скрипты node.js)

После установки в папке node_modules появляются файлы пакета, а в package.json добавляются строки:

"dependencies": {
    "express": "^4.18.2"
},
"devDependencies": {
    "jest": "^29.5.0"
}

Типичная ошибка: если пакет уже установлен глобально и локально, может возникнуть конфликт версий. Рекомендуется всегда устанавливать зависимости локально для каждого проекта.

Как установить конкретную версию пакета?

Указание версии после символа @ позволяет зафиксировать нужную версию. Это полезно для стабильности проекта, когда новая версия может сломать функциональность.

npm install lodash@4.17.21

В package.json появится строка: "lodash": "4.17.21" (без каретки). Если требуется диапазон, используются символы ^ (разрешает минорные обновления) или ~ (только патчи).

Как удалить пакет из проекта?

Команда npm uninstall (сокращённо npm un) удаляет пакет из node_modules и из package.json. Флаги --save и --save-dev работают аналогично установке, но чаще всего удаление происходит с теми же флагами, которые использовались при установке.

npm uninstall express

Если пакет был в devDependencies, команда npm uninstall jest --save-dev удалит его и из devDependencies.

Возможная сложность: после удаления иногда остаются лишние версии в node_modules, если пакет был установлен как транзитивная зависимость. Для очистки используется npm prune.

Как обновить все пакеты до последних версий?

Команда npm update обновляет пакеты в соответствии с заданными в package.json диапазонами версий. Если нужно обновить конкретный пакет, указывается его имя.

npm update
npm update lodash

Для просмотра устаревших пакетов используется npm outdated.

Как установить пакет глобально?

Флаг -g или --global устанавливает пакет в системную область, доступную из любого проекта. Обычно глобально устанавливают утилиты командной строки (например, nodemon, eslint, typescript).

npm install -g nodemon

Для просмотра глобально установленных пакетов: npm list -g --depth=0.

Проблема: глобальные пакеты могут конфликтовать между версиями Node.js. Рекомендуется использовать nvm для управления версиями Node и устанавливать глобальные пакеты для каждой версии отдельно.

Как использовать npx для запуска пакетов без установки?

Утилита npx, входящая в состав npm (начиная с версии 5.2), позволяет запускать команды пакетов без их глобальной установки. Если пакет не установлен локально, npx загрузит его из реестра во временную директорию.

npx create-react-app my-app
npx cowsay "Hello, Node.js!"

После выполнения команды временный пакет удаляется. Это удобно для одноразовых задач и для избежания загрязнения системы.

Как опубликовать собственный пакет в npm?

Для публикации требуется аккаунт на npmjs.com и авторизация через npm login. После подготовки package.json (включая уникальное имя) выполняется npm publish.

npm login
# ввод логина, пароля и email
npm publish

Если пакет имеет область (scoped), например @username/package, нужно передать флаг --access public для публичной публикации.

Типичная ошибка: при повторной публикации с тем же номером версии возникает ошибка. Для исправления нужно увеличить версию в package.json с помощью npm version patch (или minor, major).

Как запускать скрипты, определённые в package.json?

В разделе scripts можно задать команды, которые затем вызываются через npm run <имя>. Особые имена (start, test, stop, restart) можно запускать без run.

"scripts": {
    "dev": "node server.js",
    "build": "webpack --mode production",
    "lint": "eslint ."
}

npm run dev
npm test
npm run lint

Скрипты выполняются в оболочке, поэтому доступны все команды системы и программы из локальной папки node_modules/.bin.

Как работать с package-lock.json?

Файл package-lock.json автоматически создаётся при установке для фиксации точных версий всех зависимостей, включая транзитивные. Это гарантирует воспроизводимость установки на разных машинах.

Не рекомендуется редактировать этот файл вручную. Для обновления lock-файла используется npm update или npm install с новыми версиями.

npm install

Если lock-файл удалить, npm создаст новый на основе текущих установленных версий, что может привести к незначительным отличиям.

Дополнительно: команда npm cache clean --force для очистки кэша, npm audit для проверки безопасности зависимостей, npm ci для быстрой установки точно по lock-файлу (подходит для CI/CD).

Расширенные примеры работы с npm

Установка пакета с указанием диапазона версий

Пример установки пакета express с диапазоном, разрешающим только патч-обновления (тильда):

Пример

npm install express@~4.18.0

В package.json появится запись: "express": "~4.18.0". При будущем запуске npm update будут установлены только версии 4.18.x, но не 4.19.0.

Создание и использование локальной ссылки с npm link

Позволяет разрабатывать пакет локально и подключать его к другому проекту без публикации. В папке пакета:

Пример

cd ~/projects/my-local-package
npm link

Теперь в другом проекте:

Пример

cd ~/projects/my-app
npm link my-local-package

В папке node_modules появится символическая ссылка на локальный пакет. Изменения в исходном коде пакета сразу отражаются в проекте.

Для отмены используется npm unlink my-local-package или удаление ссылки в глобальной области: npm unlink -g my-local-package.

Упаковка пакета в tarball с помощью npm pack

Команда создаёт архив .tgz, который можно установить из файла:

Пример

npm pack
npm install ./my-package-1.0.0.tgz

Это удобно для передачи пакета без публикации в реестре. После упаковки выводится список файлов, включённых в архив.

Оптимизация node_modules с npm dedupe

При установке разных версий одного пакета npm может дублировать их. npm dedupe пытается поднять общие зависимости на верхний уровень, удаляя дубликаты:

Пример

npm dedupe

Команда анализирует дерево зависимостей и перемещает пакеты, чтобы минимизировать количество копий. Результат можно увидеть с помощью npm ls.

Использование npm audit для проверки безопасности

npm аудит сканирует зависимости на наличие известных уязвимостей и предлагает автоматические исправления:

Пример

npm audit
npm audit fix

Пример вывода:

                       === npm audit security report ===                                
# Run  npm install lodash@4.17.21  to resolve 1 vulnerability
┌───────────────┬─────────────────────────────────────────────────────┐
│ High          │ Prototype Pollution                                 │
├───────────────┼─────────────────────────────────────────────────────┤
│ Package       │ lodash                                               │
├───────────────┼─────────────────────────────────────────────────────┤
│ Resolution    │ Upgrade to version 4.17.21                          │
└───────────────┴─────────────────────────────────────────────────────┘

Работа с .npmrc и аутентификацией для приватных реестров

Файл .npmrc может содержать настройки реестров, токены авторизации. Пример для работы с GitHub Packages:

Пример

//npm.pkg.github.com/:_authToken=YOUR_TOKEN
@username:registry=https://npm.pkg.github.com

После этого можно устанавливать пакеты из приватного реестра: npm install @username/private-package.

Скрипты с передачей аргументов через npm

Аргументы можно передавать с помощью --:

Пример

"scripts": {
    "greet": "echo Hello $NAME"
}
npm run greet --NAME=World

После выполнения выведется: Hello World (название переменной в скрипте зависит от оболочки, здесь используется bash).

Использование npm ci для точной воспроизводимой установки

Команда npm ci (clean install) удаляет существующую папку node_modules и устанавливает зависимости строго по package-lock.json. Это быстрее, чем npm install, и гарантирует идентичное окружение на всех машинах.

Пример

npm ci

Если package-lock.json отсутствует, команда завершится ошибкой. Это особенно полезно в CI/CD.

Просмотр устаревших пакетов с npm outdated

Команда показывает текущую, желаемую и последнюю доступную версии для каждого пакета:

Пример

npm outdated

Package  Current  Wanted  Latest  Location
lodash   4.17.20  4.17.21 4.17.21  my-project
express  4.17.1   4.18.2  4.18.2   my-project

Столбец "Wanted" соответствует версии, которая будет установлена при npm update.

Управление версией пакета с npm version

Команда npm version увеличивает номер версии в package.json и создаёт git-тег (если репозиторий инициализирован). Аргументы: patch, minor, major, prepatch и т.д.

Пример

npm version patch
npm version minor --no-git-tag-version

Пример изменения: версия 1.2.3 при npm version minor станет 1.3.0.

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

Команда удаляет из node_modules пакеты, которые не указаны в package.json:

Пример

npm prune

Если после установки удалить пакет из package.json вручную, его файлы останутся до выполнения npm prune.

Менеджер пакетов npm в Node.js - comments

Node js npm (javascript)