npm и package.json
dependencies или devDependencies, semver и диапазоны, lock-файл, команды.
Обновлено
Что такое npm
npm — это две вещи: онлайн-реестр с более чем 3 миллионами JavaScript-пакетов (библиотек, написанных другими) и программа в терминале, которой их устанавливают. Когда вы пишете npm i react, npm скачивает React и все пакеты, от которых он зависит, в папку node_modules.
Альтернативы программе npm с тем же реестром: pnpm (быстрый, экономит место), yarn, bun. На проект выбирают один — по lock-файлу видно какой.
package.json — паспорт проекта
{
"name": "learn-js",
"type": "module",
"scripts": {
"dev": "next dev",
"build": "next build",
"lint": "eslint"
},
"dependencies": {
"next": "16.4.0",
"react": "19.3.0"
},
"devDependencies": {
"typescript": "^5",
"eslint": "^9"
}
}| Поле | Роль |
|---|---|
scripts |
команды, запускаемые через npm run <имя> (dev, build, test) |
dependencies |
пакеты, нужные приложению для работы (react, next, zod) |
devDependencies |
пакеты, нужные только при разработке / сборке (typescript, eslint, vitest, типы @types/*) |
type: "module" |
файлы .js — ES-модули (import/export) |
engines |
какая версия Node нужна |
Версии: semver и диапазоны
Версии следуют semver: MAJOR.MINOR.PATCH. В package.json пишут диапазон — какие версии вы принимаете:
| Диапазон | Принимает | Пример для 1.4.2 |
|---|---|---|
1.4.2 |
ровно эту версию | только 1.4.2 |
^1.4.2 |
тот же major — новые minor и patch | 1.4.2 … 1.99.x, не 2.0.0 |
~1.4.2 |
тот же minor — только patch | 1.4.2 … 1.4.x |
* / latest |
любую | опасно |
^ ставится по умолчанию при npm i. Для приложений многие команды предпочитают точные версии (npm i -E) + контролируемые обновления (Renovate, Dependabot).
Lock-файл
package-lock.json (или pnpm-lock.yaml) записывает точную версию каждого установленного пакета, включая косвенные зависимости. Итог: вы, коллеги, CI и Vercel устанавливают одно и то же.
| Правило | Почему |
|---|---|
| lock-файл кладут в Git | одинаковые установки везде |
node_modules не кладут в Git |
восстанавливается из lock-файла |
в CI используют npm ci |
ставит строго по lock-файлу, падает при несовпадении |
Команды на каждый день
| Команда | Что делает |
|---|---|
npm i |
устанавливает всё из package.json / lock-файла |
npm i zod / npm i -D vitest |
добавляет зависимость / devDependency |
npm run dev |
запускает скрипт dev |
npx <пакет> |
запускает программу без глобальной установки (npx create-next-app) |
npm outdated |
у каких пакетов есть новые версии |
npm uninstall <пакет> |
удаляет |
npm audit |
известные уязвимости |
Как выбрать пакет
Перед npm i проверьте: он поддерживается (свежий релиз)? сколько у него скачиваний в неделю? насколько он большой (bundlephobia / pkg-size)? есть ли типы TypeScript? И лучший вопрос: он мне действительно нужен? — Intl, structuredClone, fetch, crypto.randomUUID есть нативно.
Коротко
package.json= скрипты + зависимости;devDependencies— только для разработки.^принимает minor и patch;~— только patch; точная версия = без сюрпризов.- Lock-файл — в Git,
node_modules— никогда;npm ciв CI.