Пакетный менеджер npm и package.json

Программисты редко пишут всё с нуля: для форматирования дат, красивых уведомлений или сборки проекта уже есть готовые библиотеки. В этом уроке познакомимся с npm — пакетным менеджером, который скачивает и обновляет такие библиотеки, разберём файл package.json — «паспорт» проекта, — и соберём первый проект с пакетами и сборщиком Vite.

Для работы нужен установленный Node.js — если вы ещё не поставили его, вернитесь к уроку про REST API и установку Node.js.

Что такое пакет и пакетный менеджер

Пакет (package, библиотека, зависимость) — это готовый код, который кто-то написал и опубликовал, чтобы другие могли им пользоваться. Например:

• dayjs — работа с датами;
• lodash — полезные функции для массивов и объектов;
• vite — инструмент для запуска и сборки фронтенд-проектов;
• react — библиотека для интерфейсов, которую мы будем изучать в следующем месяце.

npm (Node Package Manager) — программа, которая:

• скачивает пакеты из общего хранилища — реестра npm (npmjs.com, там миллионы пакетов);
• запоминает, какие пакеты и каких версий нужны проекту;
• обновляет и удаляет их;
• запускает команды проекта (скрипты).

Аналогия — магазин приложений в телефоне. Вы не пишете калькулятор сами, а устанавливаете готовый одной кнопкой. npm — такой же «магазин», только для кода, и «кнопка» — это команда в терминале.

Создаём проект: npm init

Создайте папку и откройте её в терминале (в VS Code — меню Terminal → New Terminal):

mkdir my-first-npm
cd my-first-npm
npm init -y

• npm init создаёт файл package.json и задаёт вопросы о проекте.
• Флаг -y («yes») отвечает «да» на все вопросы и сразу создаёт файл с настройками по умолчанию.

Появится файл package.json.

package.json — паспорт проекта

Откройте package.json. После установки пакетов и небольшой настройки он будет выглядеть примерно так:

{
  "name": "my-first-npm",
  "version": "1.0.0",
  "description": "Мой первый проект с npm",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "dayjs": "^1.11.13"
  },
  "devDependencies": {
    "vite": "^7.1.0"
  }
}

Разберём поля:

Номера версий в вашем файле будут другими — npm всегда ставит актуальные.

Устанавливаем пакеты

npm install

npm install dayjs

Что произошло:

1. npm скачал пакет dayjs из реестра.
2. Положил его в папку node_modules/.
3. Добавил запись в раздел dependencies в package.json.
4. Создал (или обновил) файл package-lock.json.

Короткая форма команды — npm i dayjs. Можно ставить несколько пакетов сразу: npm i dayjs lodash.

Зависимости для разработки

Инструменты, которые нужны только вам как разработчику, а не пользователю сайта, ставят с флагом -D (--save-dev):

npm install -D vite

Пакет попадёт в devDependencies. Например, Vite нужен, чтобы запускать и собирать проект, но в готовый сайт он не попадает.

Основные команды npm

Папка node_modules и package-lock.json

node_modules

В node_modules/ лежит код всех установленных пакетов — и их собственных зависимостей. Эта папка бывает огромной: сотни мегабайт и десятки тысяч файлов.

node_modules/
dist/
.env

Когда вы скачиваете чужой проект с GitHub (или свой на другом компьютере), папки node_modules там нет. Восстанавливается она одной командой:

npm install

package-lock.json

package-lock.json записывает точные версии всех установленных пакетов, включая вложенные. Благодаря ему у вас, у ментора и на сервере стоят одинаковые версии, и проект ведёт себя одинаково.

• Этот файл добавляют в Git.
• Руками его не редактируют — npm обновляет его сам.

Версии пакетов: что значит ^1.11.13

Версии пакетов записываются по правилам семантического версионирования (SemVer): МАЖОР.МИНОР.ПАТЧ.

1.11.13
│  │  └── ПАТЧ — исправили ошибки, ничего не сломали
│  └───── МИНОР — добавили новые возможности, старое работает
└──────── МАЖОР — большие изменения, старый код может сломаться

Символ перед версией говорит, какие обновления разрешены:

По умолчанию npm ставит ^ — это разумный компромисс между свежестью и стабильностью.

Скрипты: npm run

В разделе scripts хранятся команды проекта. Их запускают так:

npm run dev
npm run build

Зачем это нужно: вместо того чтобы помнить длинные команды, все в команде пишут одинаково npm run dev. Открыв любой проект, первым делом загляните в scripts — там видно, как его запускать.

Для скриптов start и test слово run можно опустить: npm start, npm test.

Собираем проект с Vite

Соединим всё вместе: страница, которая показывает дату через пакет dayjs и запускается через Vite.

Шаг 1. Установка

npm i dayjs
npm i -D vite

Шаг 2. Скрипты

Добавьте в package.json раздел scripts (и поле "type": "module"), как в примере выше.

Шаг 3. Файлы проекта

<!-- index.html -->
<!DOCTYPE html>
<html lang="ru">
<head>
  <meta charset="UTF-8">
  <title>npm + Vite</title>
</head>
<body>
  <h1 id="today"></h1>
  <p id="deadline"></p>
  <script type="module" src="/main.js"></script>
</body>
</html>

// main.js
import dayjs from "dayjs";
import "dayjs/locale/ru";

dayjs.locale("ru");

const today = dayjs();
document.querySelector("#today").textContent = today.format("D MMMM YYYY, dddd");

const deadline = today.add(30, "day");
document.querySelector("#deadline").textContent =
  `Проект нужно сдать до ${deadline.format("D MMMM")}`;

Разбор:

• import dayjs from "dayjs" — подключаем пакет по имени, без пути к файлу. Найти его в node_modules поможет Vite.
• import "dayjs/locale/ru" — подключаем русский язык для названий месяцев и дней.
• today.format(...) — форматирует дату по шаблону; add(30, "day") — прибавляет 30 дней.
• type="module" в теге script разрешает использовать import.

Шаг 4. Запуск

npm run dev

В терминале появится адрес вида http://localhost:5173. Откройте его — вы увидите сегодняшнюю дату по-русски. Vite следит за файлами: сохраните изменения в main.js, и страница обновится сама. Остановить сервер — Ctrl+C.

Шаг 5. Сборка

npm run build

Vite соберёт готовый к публикации сайт в папку dist/: склеит и сожмёт файлы, подключит код из пакетов. Именно содержимое dist/ выкладывают на хостинг — об этом в уроке про презентацию проектов. Посмотреть собранную версию локально можно через npm run preview.

npx — запуск без установки

npx запускает программу из npm-пакета, не устанавливая её навсегда:

npx cowsay "Привет, npm!"

npm скачает пакет во временную папку, выполнит его и всё. Так удобно запускать генераторы проектов и одноразовые утилиты.

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

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

• npm ERR! enoent ... package.json — команда запущена не в той папке. Проверьте, что терминал открыт в корне проекта, где лежит package.json.
• Failed to resolve import "dayjs" — пакет не установлен. Выполните npm install.
• Cannot use import statement outside a module — забыли type="module" у script или "type": "module" в package.json для Node.js.
• node_modules в репозитории — забыли .gitignore.
• Ставили пакет глобально (npm i -g) вместо локального. Почти всегда пакеты ставят в проект.

Документация: docs.npmjs.com, Vite: начало работы.

Практика

1. Первый package.json. Создайте папку, выполните npm init -y, откройте package.json и поменяйте description на описание своего проекта. Добавьте поле "type": "module".
2. Установка и удаление. Установите lodash, убедитесь, что он появился в dependencies и в node_modules. Затем удалите его командой npm uninstall lodash и проверьте, что запись исчезла.
3. Восстановление. Удалите папку node_modules целиком и выполните npm install. Убедитесь, что всё вернулось. Создайте .gitignore с node_modules/.
4. Свой скрипт. Создайте файл hello.js с console.log и добавьте в scripts команду "hello": "node hello.js". Запустите её через npm run hello.
5. Проект с Vite. Повторите проект из урока: Vite + dayjs. Добавьте на страницу строку «До Нового года осталось N дней» (подсказка: dayjs("2027-01-01").diff(dayjs(), "day")). Соберите проект через npm run build и найдите результат в папке dist.

Итоги

• npm — пакетный менеджер: скачивает библиотеки из реестра и следит за их версиями.
• package.json — паспорт проекта: имя, скрипты, dependencies и devDependencies.
• npm i пакет — для приложения, npm i -D пакет — для разработки.
• node_modules не коммитим, восстанавливаем через npm install; package-lock.json коммитим.
• Версии — по SemVer МАЖОР.МИНОР.ПАТЧ, ^ разрешает минорные обновления.
• Команды проекта живут в scripts и запускаются через npm run имя.