npm: package.json, скрипты и установка пакетов с нуля

К концу этой инструкции у вас будет рабочий проект на npm: файл package.json, установленные зависимости в node_modules, зафиксированные версии в package-lock.json и пара своих команд, которые запускаются одной строкой. На всё уйдёт минут двадцать-тридцать, если Node.js уже стоит. Если нет — установка Node добавит ещё десять минут.

npm — это менеджер пакетов, который ставится вместе с Node.js. Он тянет чужой код из реестра npmjs.com, следит за версиями и запускает ваши команды сборки и тестов. Всё это описывается в одном файле package.json в корне проекта.

Что нужно до начала

Проверьте, что у вас есть всё необходимое, прежде чем создавать проект. Иначе рискуете узнать на третьем шаге, что npm вообще не установлен.

• Node.js версии 18 или новее. npm идёт в комплекте. Актуальные LTS-версии на момент написания — Node 20.x и 22.x.
• Терминал. На Windows — PowerShell или встроенный терминал VS Code, на macOS и Linux — любой.
• Пустая папка под проект. Не запускайте инициализацию в домашней директории или на рабочем столе — файлы разлетятся.

Проверить версии можно двумя командами:

node --version
npm --version

Если обе выводят номера версий (например, v20.11.0 и 10.2.4) — всё на месте. Если терминал пишет command not found или не является внутренней командой, сначала поставьте Node.js с сайта nodejs.org.

Шаг за шагом

1. Создайте и откройте папку проекта.

   mkdir my-project
   cd my-project

   Проверка: команда pwd (или cd без аргументов на Windows) покажет путь, заканчивающийся на my-project.

2. Инициализируйте package.json. Флаг -y соглашается со всеми значениями по умолчанию, чтобы не отвечать на вопросы вручную.

   npm init -y

   Проверка: в папке появился файл package.json. Откройте его — внутри будет объект с полями name, version, main, scripts и другими.

3. Установите первую зависимость. Для примера возьмём dayjs — небольшую библиотеку для работы с датами.

   npm install dayjs

   Проверка: появилась папка node_modules и файл package-lock.json, а в package.json добавился раздел dependencies со строкой вроде "dayjs": "^1.11.10".

4. Установите инструмент только для разработки. Флаг --save-dev (или -D) кладёт пакет в отдельный раздел — такие зависимости не нужны в продакшене.

   npm install --save-dev nodemon

   Проверка: в package.json появился раздел devDependencies с nodemon.

5. Напишите код, который что-то делает. Создайте файл index.js:

   // index.js — выводит текущую дату в читаемом формате
   const dayjs = require('dayjs');
   
   const now = dayjs().format('DD.MM.YYYY HH:mm');
   console.log('Сейчас:', now);

   Проверка: запустите node index.js — в терминале появится строка вида Сейчас: 12.06.2024 14:30.

6. Добавьте свои npm-скрипты. Откройте package.json и приведите раздел scripts к такому виду:

   "scripts": {
     "start": "node index.js",
     "dev": "nodemon index.js"
   }

   Проверка: команда npm start запустит скрипт, а npm run dev — режим с автоперезапуском при изменении файла.

Почему start запускается без run, а dev — с run

npm знает несколько «встроенных» имён скриптов: start, test, stop, restart. Их можно вызывать без слова run: npm start, npm test. Все остальные имена, включая dev и build, требуют явного npm run. Это единственная разница — путать её с чем-то большим не нужно.

dependencies или devDependencies — куда что класть

Это первое, на чём спотыкаются новички. Правило простое: если пакет нужен коду во время работы приложения — это dependencies. Если только для сборки, тестов или удобства разработки — это devDependencies.

Когда кто-то склонирует ваш репозиторий и выполнит npm install, npm поставит оба раздела. А на сервере с флагом --omit=dev (в npm 8 и новее) поставятся только продовые зависимости — образ приложения получится легче.

Главное, что стоит запомнить про package-lock.json: его коммитят в репозиторий. Именно он гарантирует, что у вас и у коллеги установятся одни и те же версии вложенных зависимостей, а не просто «что-то подходящее под ^1.11».

Что значат символы перед версией

В строке "dayjs": "^1.11.10" важен первый символ:

• ^ (карет) — разрешает обновления до новых минорных и патч-версий, но не мажорных: поставится 1.12.0, но не 2.0.0.
• ~ (тильда) — разрешает только патчи: 1.11.11, но не 1.12.0.
• без символа — строго эта версия, ничего другого.

Именно поэтому одна строка в package.json может дать разные версии на разных машинах, а package-lock.json прибивает их гвоздями.

Если не получилось

Самые частые ошибки при первом запуске и что с ними делать.

• npm ERR! code ENOENT ... package.json — вы запустили команду не в той папке или забыли сделать npm init. Проверьте, что в текущей директории есть package.json.
• Error: Cannot find module 'dayjs' — пакет не установлен или удалена папка node_modules. Выполните npm install — он восстановит зависимости по package-lock.json.
• npm ERR! missing script: dev — вы вызвали npm run dev, но такого скрипта нет в scripts. Проверьте написание имени в package.json.
• EACCES: permission denied при -g — глобальная установка упирается в права. Не решайте это через sudo: лучше настройте менеджер версий (nvm, fnm) или измените каталог для глобальных пакетов по инструкции из документации npm.
• Установка зависает или падает по сети — проверьте, какой реестр используется: npm config get registry. Должен быть https://registry.npmjs.org/, если вы не настраивали корпоративный прокси намеренно.

Что делать дальше

Базовый проект готов. Дальше по мере роста пригодится следующее:

• Добавьте файл .gitignore со строкой node_modules — эту папку в репозиторий не коммитят, она восстанавливается из lock-файла.
• Разберитесь с npm ci — эта команда ставит зависимости строго по package-lock.json и используется в CI и на серверах вместо npm install.
• Проверяйте зависимости на уязвимости командой npm audit, а исправляйте осознанно — npm audit fix иногда меняет мажорные версии.

Управление версиями самого Node и глобальные пакеты — отдельная тема, здесь мы её не разворачиваем. Для одного проекта хватит того, что уже настроено.