package.json oddiy tilda: bog‘liqliklar, skriptlar va semver

package.json nima

package.json — JavaScript loyihasining ildiz papkasidagi fayl bo‘lib, loyihaning o‘zini va ishlashi uchun kerak bo‘lgan hamma narsani tavsiflaydi. npm, pnpm yoki yarn u orqali qaysi paketlarni o‘rnatishni, siz esa build, test va serverni qaysi buyruqlar bilan ishga tushirishni bilib olasiz.

Uni npm init -y buyrug‘i bilan yaratish mumkin, lekin ko‘pincha u framework shabloni bilan birga keladi.

Asosiy maydonlar

{
  "name": "my-app",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "test": "vitest"
  },
  "dependencies": {
    "react": "^18.2.0"
  },
  "devDependencies": {
    "typescript": "~5.4.0"
  },
  "engines": {
    "node": ">=20"
  }
}

• name va version — paket nomi va versiyasi. Kutubxona nashr qilsangiz, majburiy.
• private: true — npm ga tasodifan nashr qilinishdan himoya. Ilovalar uchun qo‘ying.
• type — Node.js .js fayllar uchun qaysi modul tizimini ishlatishi: "module" (ES Modules) yoki "commonjs" (standart).
• scripts — nomlangan buyruqlar. npm run dev orqali ishga tushadi, test va start esa shunchaki npm test va npm start.
• main / exports — paketingizni import qiladiganlar uchun kirish nuqtasi.
• engines — qo‘llab-quvvatlanadigan Node.js versiyalari. Mos kelmaslikni erta aniqlashga yordam beradi.

dependencies, devDependencies va peerDependencies

Bandlga yig‘iladigan frontend ilovada birinchi ikkisi orasidagi chegara shartli, lekin server kodi va kutubxonalar uchun u muhim: production’da --omit=dev bilan o‘rnatilganda devDependencies o‘rnatilmaydi.

peerDependencies kutubxona mualliflari uchun kerak. Agar komponentlar kutubxonangiz React’ning o‘z nusxasini o‘rnatsa, loyihada ikkita nusxa paydo bo‘ladi va bu xatolarga olib keladi. Shu sababli kutubxona React’ni peer sifatida e’lon qiladi va loyihada allaqachon bor versiyadan foydalanadi.

Versiyalarni qanday o‘qish kerak: semver

Versiya MAJOR.MINOR.PATCH formatida bo‘ladi, masalan 4.17.2:

• MAJOR — API ni buzadigan o‘zgarishlar.
• MINOR — hech narsani buzmaydigan yangi imkoniyatlar.
• PATCH — xatolarni tuzatish.

package.json dagi diapazonlar:

Muhim nuqta: 0.x versiyalarda karet qat’iyroq. ^0.4.2 faqat 0.4.x ga ruxsat beradi, chunki 1.0 gacha har qanday minor yangilanish API ni buzishi mumkin.

Semver — kelishuv, kafolat emas. Paket muallifi xato qilib, patch’da buzuvchi o‘zgarish chiqarishi mumkin. Bundan lock-fayl himoya qiladi.

Lock-fayl nima uchun kerak

package-lock.json (yoki pnpm-lock.yaml, yarn.lock) barcha paketlarning, shu jumladan ichki bog‘liqliklarning aniq versiyalarini qayd etadi. Usiz loyihani turli kunlarda o‘rnatgan ikki dasturchi har xil kod olishi mumkin.

Qoidalar:

• Lock-faylni har doim repozitoriyga commit qiling.
• CI va serverda npm ci dan foydalaning — u lock-faylda yozilganini qat’iy o‘rnatadi va lock bilan package.json mos kelmasa, xato beradi.
• Paket menejerlarini aralashtirmang: bitta loyiha — bitta lock-fayl.

Paketlarni xavfsiz yangilash

1. Nima eskirganini ko‘ring: npm outdated.
2. Ruxsat etilgan diapazonlar ichida yangilang: npm update.
3. Major versiyalarni changelog va migratsiya bo‘limini o‘qib, bittadan yangilang.
4. Har bir yangilanishdan keyin build va testlarni ishga tushiring.
5. Zaifliklarni tekshiring: npm audit. npm audit fix --force ni ko‘r-ko‘rona ishlatmang — u major versiyalarni ko‘tarib yuborishi mumkin.
6. package.json va lock-faylni birga commit qiling.

Buni Dependabot yoki Renovate kabi botlar bilan avtomatlashtirish qulay: ular har bir yangilanish uchun alohida pull request ochadi, CI esa nima buzilganini darhol ko‘rsatadi.

Ko‘p uchraydigan xatolar

• Lock-fayl .gitignore da — build’lar oldindan aytib bo‘lmaydigan bo‘lib qoladi.
• Serverda npm ci o‘rniga npm install — lock-fayl qayta yozilishi mumkin.
• Build vositalari dependencies da — production obrazi shishib ketadi.
• Lock-faylni qo‘lda tahrirlash — uni faqat paket menejeri orqali o‘zgartiring.