npm и сторонние пакеты

В корне проекта лежит файл package.json — обычный JSON, который npm читает перед каждой командой. Там записано, как проект называется, какая у него версия, какие пакеты ему нужны и какие команды он умеет запускать. Создаётся файл командой npm init -y, а дальше растёт сам по мере установки пакетов.

const pkg = JSON.parse(`{
  "name": "my-blog",
  "version": "1.0.0",
  "dependencies": { "dayjs": "^1.11.10" }
}`);
console.log(pkg.name);
console.log(pkg.dependencies.dayjs);

Отдельного внимания стоит поле scripts — словарь коротких имён для длинных команд. Написали npm run test, npm нашёл строку в словаре и выполнил её в терминале. Это способ не держать в голове флаги сборщика и не пересылать их коллегам в чат.

const scripts = { dev: "next dev", test: "vitest run" };
// npm run test выполнит ровно эту строку
console.log(scripts.test);

Команда npm install dayjs выглядит мгновенной, но делает сразу несколько вещей: спрашивает у реестра registry.npmjs.org, где лежит пакет с таким именем, скачивает архив, распаковывает его в папку node_modules, дописывает строчку в dependencies и запоминает точную скачанную версию в файле package-lock.json.

Дальше имя пакета работает как адрес: свой файл вы подключаете путём — ./utils.js, а пакет просто именем — import dayjs from "dayjs". Внутри пакет устроен ровно так же, как ваши модули: файл, который что-то экспортирует. Никакой магии, просто чужой код рядом с вашим.

// примерно так выглядит крошечный пакет изнутри
const slugify = (text) => text.toLowerCase().split(" ").join("-");
console.log(slugify("Привет из npm"));

// голое имя пакета без помощи: браузер не знает, где лежит "dayjs"
import("dayjs")
  .then(() => console.log("загрузилось"))
  .catch((error) => console.log(error.name));

// карта импортов в подложке сказала браузеру: "dayjs" — вот этот адрес
import("dayjs").then((module) => console.log(module.default("2026-09-14")));

$ cat index.html

В dependencies попадает то, без чего приложение не работает у пользователя: библиотека дат, валидатор, сам фреймворк. В devDependencies — инструменты, нужные только вам за компьютером: сборщик, линтер, тестовый фреймворк, типы для TypeScript. Флаг -D (он же --save-dev) как раз кладёт пакет во второй список.

Разница становится заметной на сервере: npm ci --omit=dev ставит только боевые пакеты, и образ приложения худеет в разы. Ошибка «положил линтер в dependencies» ничего не сломает сразу — она просто утяжелит сборку и добавит лишнего чужого кода туда, где он никому не нужен.

const pkg = {
  dependencies: { dayjs: "^1.11.10", zod: "^3.23.8" },
  devDependencies: { vitest: "^2.0.5", eslint: "^9.9.0" }
};
const prod = Object.keys(pkg.dependencies);
console.log(prod.length);
console.log(prod.includes("vitest"));

Версия пакета — три числа через точку: 2.4.1. Это соглашение называется семантическим версионированием, semver. Последнее число меняют, когда починили ошибку; среднее — когда добавили новое, но старое продолжает работать; первое — когда что-то сломали намеренно, и обновление потребует правок в вашем коде.

Поэтому в package.json хранится не версия, а диапазон. Значок ^, который npm ставит по умолчанию, означает «бери свежее, но не переходи через мажорную границу».

// проверка диапазона ^1.4.2, упрощённо
const fits = (v) => {
  const [major, minor, patch] = v.split(".").map(Number);
  return major === 1 && (minor > 4 || (minor === 4 && patch >= 2));
};
console.log(fits("1.9.0"));
console.log(fits("2.0.0"));

node_modules — это склад, куда npm распаковывает скачанное. Его не коммитят в git: папка целиком восстанавливается из package.json и package-lock.json, поэтому её имя одним из первых попадает в .gitignore.

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

const tree = { app: ["a", "b"], a: ["c"], b: ["c", "d"], c: [], d: [] };
const seen = new Set();
const walk = (name) => tree[name].forEach((dep) => {
  if (!seen.has(dep)) { seen.add(dep); walk(dep); }
});
walk("app");
console.log(seen.size);

Устанавливая пакет, вы пускаете чужой код в проект с теми же правами, что и у собственного. История помнит показательные случаи: автор удалил из реестра крошечный left-pad — и сборки посыпались по всему миру; в популярный event-stream новый сопровождающий добавил код, охотившийся на криптокошельки. Это не повод бояться npm, это повод смотреть, что ставишь.

Перед установкой полезно потратить минуту на страницу пакета: когда был последний релиз, сколько своих зависимостей он тянет, отвечают ли на issues, есть ли типы для TypeScript, понятна ли лицензия. И самый честный вопрос — точно ли задача не решается десятком своих строк. В следующей статье, «Живой ли пакет», эта минута разложена на шесть вопросов вместо привычных звёзд и загрузок.

// прежде чем ставить пакет, прикиньте: это точно не три строки?
const unique = (list) => [...new Set(list)];
console.log(unique([1, 2, 2, 3, 1]));

Каждая зависимость — обещание жить с ней годами: обновлять, чинить, объяснять новичкам. Иногда десять своих строк дешевле.