Блок 7 · Урок 2 из 4

Зависимости: чужие детали в вашем проекте

Что такое npm-пакеты, зачем нужен package.json и почему у всего есть версии.

⏱ ≈ 6 минут 📦 npm, package.json, версии 🎯 цель: понимать слова агента про пакеты и оценивать риск обновлений

Зачем это вам

Агент постоянно говорит «поставлю пакет», «это в package.json», «обнови зависимости», «конфликт версий», «уязвимость в зависимости», «удали node_modules и переустанови». Не понимая этих слов, вы не можете оценить, что именно делает агент и какой в этом риск. После урока вы будете понимать смысл каждой из этих фраз — и сможете задавать агенту правильные уточняющие вопросы.

Суть

Ваш проект не пишется с нуля — он собирается из готовых частей

Любое современное веб-приложение использует чужой готовый код. Этот чужой код называется зависимостью (dependency) — потому что ваш проект «зависит» от него: без этого кода он не заработает.

Зависимости — это пакеты (packages): готовые библиотеки для работы с датами, компоненты интерфейса, инструменты авторизации и тысячи других вещей. Их публикуют и берут из единого каталога — npm1 (менеджер и каталог пакетов для Node.js и JavaScript). Команда npm install имя-пакета скачивает пакет из этого каталога в ваш проект.

Все скачанные пакеты попадают в папку node_modules — она может весить сотни мегабайт и содержать тысячи файлов. Именно поэтому её никогда не кладут в гит: она восстанавливается автоматически по описи проекта.

Этой описью является package.json — текстовый файл в корне проекта. В нём записано: какие пакеты нужны и какую именно версию каждого из них брать. По package.json любой разработчик (или агент на новом компьютере) может одной командой восстановить ровно тот же набор зависимостей.

У каждого пакета есть версия — номер вида 4.2.1. Новые версии добавляют возможности и чинят ошибки, но обновление иногда ломает совместимость — отсюда «конфликт версий». Поэтому агент не обновляет пакеты без причины, а вы можете попросить его проверить риски перед обновлением.

Отдельная тема — безопасность2: в чужом коде иногда находят уязвимости. Их закрывают новой версией пакета. Именно поэтому «обнови зависимости» может быть не просто улучшением, а патчем безопасности.

📌 Правило: node_modules нет в гите. Если вы клонируете проект и что-то не запускается — первым делом выполните npm install (или pnpm install). Это скачает все зависимости по package.json.

Аналогия, которую можно пересказать

Готовые детали из каталога

Зависимости— готовые детали и узлы из каталога поставщика: берёте готовый календарь, библиотеку графиков, кнопки — и не изобретаете их заново
npm— сам каталог поставщика, откуда заказываете детали одной командой
package.json— спецификация изделия: полный список деталей с артикулами (версиями), чтобы собрать точно такое же ещё раз
node_modules— склад с уже полученными деталями; его не везут при переезде — проще заказать заново по спецификации
Конфликт версий— новая модель детали не встаёт на старое место: поставщик сменил форм-фактор, пришлось адаптировать
Уязвимость в пакете— отзыв бракованной детали: поставщик нашёл брак, выпустил исправленную версию — её нужно поставить

Собирать приложение полностью с нуля — как точить каждый болт самому. Зависимости дают готовые узлы, package.json — чертёж сборки, npm — каталог поставщика.

Запомните одно

package.json — опись проекта; node_modules — склад, который всегда можно восстановить по ней

Пока есть package.json, вы не потеряете зависимости: одна команда npm install — и склад (node_modules) собран заново. Именно поэтому «удали node_modules и переустанови» — это не катастрофа, а стандартный метод починки.

Что это даёт на практике

Фраза агента → что он имеет в виду

«Поставлю пакет / зависимость»
Скачаю готовую библиотеку из npm и добавлю запись в package.json — ваш код не пишет это сам.
«Это в package.json»
Зависимость уже записана в описи проекта; при следующем npm install она поставится автоматически.
«Обнови зависимости»
Возьмём свежие версии пакетов — это может закрыть уязвимости, но стоит проверить, что ничего не сломалось.
«Удали node_modules и переустанови»
Пересоберём папку пакетов заново по package.json — частый способ починить странные ошибки зависимостей.

Зависимость (dependency) — чужой готовый код (пакет), который использует ваш проект.

npm — каталог и менеджер пакетов JavaScript (аналоги: yarn, pnpm).

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

node_modules — папка со скачанными пакетами; в гите не хранится, восстанавливается по package.json.

Версия — номер выпуска пакета (например, 4.2.1); обновление может нарушить совместимость.

Проверьте себя

Четыре вопроса с мгновенной проверкой

1. Что такое зависимость (dependency) в проекте?

2. Зачем нужен файл package.json?

3. Почему обновление зависимости иногда рискованно?

4. Агент говорит: «удали node_modules и переустанови». Что это значит?

Куда мы идём

Программа курса — 7 блоков