Што на самай працо робіць npm install: реестр, package.json і файлы блокавання

Практычна кожны проект на JavaScript, незалежна ад таго, чы робіць ён на Node.js, React чы Next.js, пачынаецца з аднаго і тога ж каманды, і багато разработчыкаў выкананяюць яе ўсё дзень без чыткага розуміння таго, што яна рабіць. Знанне таго, звядзе дыюць пакеты, як npm выбірае, што інсталаваць, і для чаго праграмістуюць package.json, package-lock.json і node_modules, дапамагае легчэй дыягноставаць проблемы пад час інсталляціі. Шэры рукаводзець раскрывае кожны аспект, ад першай інсталляціі да публікацыі савага пакета.

Каманды, якія вводзі ўсе

Найболей звычны спосаб — інсталляція всага, што ўжо заявленае ў проекте:

npm install

Таксама распашчасты ў спосабе — дадаванне бібліятэкі па імени, напрыклад, веб-фреймворка Express:

npm install express

чы і HTTP-кліента Axios:

npm install axios

За гэтымі простымі запісамі крыюцься калькі пытанняў. Звядзе код заванося? Як npm ведае, чым практыкуе проект? Для чаго існуе package.json? І чаму папка node_modules становіцца такой вялікай?

Што такое npm

npm — это стандартны менеджер пакетаў для Node.js, які поставляецца разам з ям. Ён даёт вам доступ да вялічезнага каталогу пакетаў, якія можна перызначыць і якія публікуюць іншыя разработчыкі, тады вы можете запрашаць апробаваны код у свой проект замест таго, каб пісаць яго самі.

Уявіце сабе гэта як публічную бібліятэку коду. Падазроўваю, што бэкенд на Node.js патрабуе HTTP-сервера. Умест таго, каб самі ствараць механізмы маршрутацыі та проміжнага обробкі, вы можаце адключыць Express:

npm install express

Патрэбны іншыя API? Дадзіце HTTP-кліента:

npm install axios

Праверкю прыходзячых дадзенняў па схеме выкарыстоўваецца Zod:

npm install zod

А bcrypt абсалютная пасварды:

npm install bcrypt

Гэта яшчэ большая сіле экасистемы: калі існуе добра працаваная рашэння, рэдкая прычына пісаць сваё. Але ў той жа час кожны інсталаваны пакет — это код, якому вы тепер дазваляеце довяроўваць, таму лепш выбіраць падтрымваныя, шырока вжываныя бібліятэкі і трэба старацца, каб ўхідны список быў мінімальны. Аб тым, чаму гэта важна, прачытайце як функціонуюць атакі на ланцоўку постачання npm.

Экасистема, а не просто команда

Новачкі часта вважаюць npm проста словам, яке пішчыцаецца ў тэрмінал. На самай працы гэта назва абходзіць кальколька взаімаўпрацоўваючых частак:

• Рэжыстры npm: публічная служба, дзе пакеты публікуюцца і завантажваюцца.
• CLI npm: інструмент у командной лініи, які вярбуецца з рэжыстры і караціць залежнасці.

Пакеты: самыя воспрыемныя единіцы коду.

package.json: дакумент, які описвае ваш проект і тое, чым ён залежыць.

Публічныя пакеты ўжо безкоштовны: вы можете запісаць будзь-канфігурацыю публічнага пакета без аднароджэння. Гэты низкі бар’ер спадзяўся на тое, што JavaScript з адкрытым кодам распрасіўся па всім свету. Аднароджэння патрабуецца толькі для публікацыі.

Што адбываецца, калі вы запускаеце npm install

Возьмім проект, які дадае Express:

npm install express

У загальных рысах:

1. npm шукае пакет у рэжыстре і выбірае версію, якая падходзіць да запрошанага дыапазона (найновейшую, якщо ніякога не задана).
2. Ён разгледвае сабэйшыя залежнасці пакета і залежнасці тых, якія ў ёму, і стварае цэлы «дрэва» залежнасцяў.
3. Ён завантажае тое, што ўжо не знаходзіцца у кэшы, і размешчае гэта ў node_modules.

Ён фіксуе залежнасці ў package.json і точную структуру, яка была вырашана, ў package-lock.json.

Самэй так адна короткая команда прыносіць цэлую структуру функцыйнальнасці.

package.json: маніфест проекта

У цэнтры кожнага проекта Node.js знаходзіцца адны файл:

package.json

Ён выступае як карточка аідэнтыфікацыі і настройкі вашага проекта адночасна, ў яму зберагліся назва, версія, апісанне, скрыпты, залежнасці для работы і розвітку, а таксама дакументацыя пра автора. Мінімальны прыклад выказвае файл-вхід у main, адны скрыпт і адну залежнасць:

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "My Node.js application",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "express": "^5.1.0"
  }
}

name

name ідэнтыфікуе проект або пакет. Якщо вы яго публікуеце, людзі запішуць гэта значэнне, каб яго установіць, таму ёно павінна быць унікальным у реестре.

"name": "my-project"

version

version зберагае текущую версію пакета.

"version": "1.0.0"

Гэта мае вялікое значэнне пад час публікацыі. npm выкорыстоўвае сэмантычнае версіяванне (MAJOR.MINOR.PATCH): змены, якія нарабляюць брэйкы, паднімаюць значэнне мажорной версіі, сумесныя функцыі — значэнне мінорной, а практычныя правкі — значэнне патч-версіі.

опіс

description — это однай-лінейны ўзмацненне таго, што робіць проект, якое паказваецца ў рэзультатах пошуку у реестры.

"description": "My Node.js application"

скрыпты

scripts визначае іменаваныя скорачэнні для часта викорыстоўваных каманд. Хутчэй start запускае галоўны файл:

"scripts": {
  "start": "node index.js"
}

Без яго павінны быць введзеныя всі элементы каманды:

node index.js

З ягом ўсё выконваецца так сама:

npm start

Цэннае значэнне — це адносна стабільнасць: кожны учаснік і кожная задача CI выконвае тую ж самую іменаваную каманду. Адзінаковыя назвы, такія як build, выконваюцца за дапамою npm run build.

Залежнасці: на чым базуецца ваш проект

Уявіце платформу для доставкі ласоў. Їё бэкенд можа викорыстоваць:

• Express для API
• Zod для пераканалення данных
• bcrypt для хэшавання пароў
• бібліятэку JSON Web Token для аутантыкацыі
• Mongoose для MongoDB

Кожны з іх ёсць залежнасцю. Калі вы інсталюеце якую-небудзь з іх:

npm install express

npm дадае ентрыту ў package.json:

"dependencies": {
  "express": "^5.1.0"
}

Знак кареткі ў ^5.1.0 пазначае дыапазон: прыймаюцца всі новейшыя версіі 5.x, але не 6.0.0. Цей энтрыт паведамляе всіх, хто чытае проект, што для його роботы патрэбен Express. Адзінкі інструменты, якія патрэбны толькі пад час разработкі, напрыклад, тэст-раннеры, кладуцца ў devDependencies за дапамогою команды npm install --save-dev.

Чаму адна команда можа прызначыцца цэлай камандзе

Спадзяйцеся, што вы прыўязаліся да каманды і клонавалі ўсе яе рэпозітары. Ніхто не чакае, што вы вручную запрашаеце пяцьдзiesять бібліятэкаў. Вы запускаеце:

npm install

npm чытае заявленыя залежнасці і інсталюе ўсія яны. Самэльга з таго, што пакетныя менеджеры неабходны для стварэння рабочай среды на адповідачныя ваказанні.

node_modules: дзе знаходзіцца інсталаваны код

Пасля інсталяціі з’являецца новы папка:

node_modules/

У яй знаходзяцца пакеты, якія вы запрашавалі, а таксама всё, чым яны залежная, і самэльга таму ёй становіцца вяліка. Тыпавая структура:

my-project/
│
├── node_modules/
├── package.json
├── package-lock.json
└── index.js

Не кэмітуйце node_modules у Git. Ён вялікі, можа мець версіі, прызначаныя для конкрэтных платформ, і яго завжды можна перзаснаваць. Паказвайце яго ў .gitignore і кэмітуйце заместа яго гэтыя файлы:

package.json
package-lock.json

Потым будзь-хто іншы можа запусціць:

npm install

і практычна отрымаць тыя ж залежнасці.

package-lock.json: точны фікс

Дзеўяты файл знаходзіцца празаўсёды ля маніфесту:

package-lock.json

Чаму і тое, і другое? Коротка версія:

• package.json паказвае, што патрэбна проекту, зазвычай у відметках.
• package-lock.json фіксуе самэ exactly тое, што было установлена: кожная версія пакета ў всім дрэве, а таксама хешы целаснасці.

Паколькі відметкі можа падходзіць да новыях выданняў з часам, файл блокавання дапамагае ноутбукам, колегам і системам CI застаўляць ідэнтычныя версіі. Зберагуйце яго, і ў системах CI вярніцеся да npm ci, які установляе толькі на адной основе файлу блокавання.

Команды npm, якія варта знать

Дадзеце пакет:

npm install express

Установіце все, што заявляе проект:

npm install

Адчыніце пакет з node_modules і package.json:

npm uninstall express

Апдэйтаваце пакеты да найновыях версіяў, якія дазволяюць відметкі (гэта не будзе пераходу на большую версію):

npm update

Адрукуйце версію npm:

npm -v

Адрукуйце версію Node.js:

node -v

Апраўцуйце інфармацыю пра аккаунт npm, пад якім вы заўважаны:

npm whoami

З корыстніка на апублікавальніка

Вы таксама можете дапамагаць у стварэнні пакетаў. Апублікуйце корыстную бібліятэку, і іншыя зможуць ўстановіць яе як і будзь-яю іншую:

npm install your-package

Этот цыкл падтрымляе жыццё адкрытага кода: вы будуеце на роботе іншых, ствараеце свою власную і дзеліцеся ёю знову.

Этапы апублікацыі

Вам патрэбен аккаунт npm. Заўважыцеся з тэрміналу:

npm login

Падтвердзіце, які аккаунт ў дзейнасці:

npm whoami

Перайдзіце да проекту:

cd myproject

Убедзіцеся, што ён мае правільны файл manifest з унікальным name і version:

package.json

Потым апублікуйце:

npm publish

Пакет тепер доступны для всіх. Два патронтаў: спачатку запустыце npm pack --dry-run, ўбачыце, якія файлы будуць дапаможаны, і зменшыце version пасля кожнага выпуску, таму што выпусканая версія не можа быць перызналена. Пераканайцеся ў актуальных інструкцыях npm па трэбаваннях да безпекі аднойчынкі, такіх як двухфакторная аутэнтыкацыя.

Як усе взаімаюцца

Весь процес выглядае так:

Developer
    ↓
npm install
    ↓
npm Registry
    ↓
Package + Dependencies
    ↓
node_modules
    ↓
package.json
    ↓
Your Application

Вы запускаеце каманду, CLI заўзявае пакеты з рэжыстру, код апыходзіць у node_modules, маніфест і файл з блокаванням фіксуюць гэта, а ваша прыемліка імпортуе яго. Самэўсёла гэта ланцоўка дазволяе разработчыкам эфектыва перызналяць, карманаваць, дзеліцца і выпускаць код.

Ключовыя выводы

npm можа выглядаць як скупка каманд тэрміналу, але калі вы зразумеце, што вядзецца за гэтай камандай:

npm install

Система становіцца простай для розумеў. JavaScript з’являецца як мова, Node.js – як среда выканання, а npm – як екасістэма для аднароджэння коду. У практыцы:

• package.json адзначае намеры; package-lock.json фіксуе рэальны стан. Зберагаюцься оба файлы.
• Ніколі не зберагайце node_modules.
• Діапазон кареткі дазволяе выканаць мелкія та патч-апдэйты, пры чым npm update застаецца ў межах гэтага діапазона.
• Для точных установак у автаматызацыі вжывайце npm ci.
• Дадзіце залежнасці свядома; кожная з іх – це код, якому вы давайце доверлівасць.

Так што наступны раз, калі вы будете пісаць:

npm install

Памятайце, што вы паў’язуеце свой проект з екасістэмай, створанай разработчыкамі з усьго света.

Спадневаная літэратура

• Што JSON.stringify таямніча паскае, ператварае і адкладае серыяваць — Дазвольце дазнацца, якія значэння JavaScript JSON.stringify прыхоўчвае або зменяе, як toJSON, заменнікі і функцыі вярнення выправляюць гэта, і калі structuredClone ёсць лепшым адпаведнікам.
• Што насправды гарантуе async/await і шта ён залишае вам — Зрозумейце, што насправды паставляе await, як ухіліцца ад серыяваных запитоў, і чаму для падтрымкі кешаўкае, анулювання, правільнага рэйтарынгу і павторных спроб трэбуюцься рашэнні, якія выходзяць за межы async/await.