1.4npm: package.json والتبعيات والسكربتات والإصدارات
الأساسي في 30 ثانية
- package.json = البيان: الاسم، الإصدار، التبعيات، السكربتات — يُنشأ مع npm init، مرجع كل مشروع.
- الوصفة، لا النتيجة: نُصدِر package.json + package-lock.json (إصدارات دقيقة)، وnode_modules أبدًا (تُعاد توليدها عبر npm install).
- Semver + سكربتات + تدقيق: رئيسي.فرعي.تصحيحي (^ و~)، أوامر معيارية عبر npm run، وثغرات عبر npm audit.
حالة مستمرة — ساليم يهيئ مشروعه في الجزائر
يستلم ساليم مشروع الشركة الناشئة: مجلد فيه كود لكن دون package.json، ويرسل له زميل node_modules كمرفق. يبدأ بنظافة: npm init لإنشاء البيان، تثبيت الحزم (تبعيات مقابل devDependencies)، سكربتات start/dev/test، و.gitignore يستبعد node_modules، وأول npm audit يكشف تبعية مصابة يجب تحديثها. يصير المشروع قابلًا للتثبيت بأمر واحد: npm install.
الحلقة الأخيرة من الحالة 1.1-1.3 — يجهّز ساليم مشروعه بعد اللغة وغير المتزامن والوحدات.
1. package.json والتبعيات: البيان
يتيح npm الوصول إلى أكبر سجل مفتوح المصدر في العالم: نثبّت حزمًا بدل كتابة كل شيء. قلب المشروع هو package.json (الاسم، الإصدار، التبعيات، السكربتات)، يُنشأ مع npm init. npm install express تحمّل في node_modules وتضيف إلى التبعيات. نميّز dependencies (الإنتاج) وdevDependencies (التطوير فقط، -D). package-lock.json يجمّد الإصدارات الدقيقة (قابلية إعادة الإنتاج)؛ وnode_modules لا تُصدَّر (قابلة لإعادة التوليد).
يُطلق ساليم npm init -y، ويثبّت إطار العمل كتبعية وأداة إعادة التشغيل كـ devDependency: صار المشروع يُثبَّت بـ npm install واحدة على أي جهاز.
2. Semver والسكربتات والأمان
يتبع الترقيم الدلالي (semver) صيغة رئيسي.فرعي.تصحيحي: الرئيسي = تغييرات كاسرة، الفرعي = مزايا متوافقة، التصحيحي = أخطاء. ^4.18.2 تسمح بتحديثات الفرعي والتصحيحي، و~4.18.2 بالتصحيحية فقط. السكربتات (start وdev وtest) تُطلَق مع npm run <nom> وتوحّد الأوامر. وnpm audit تُبلغ عن ثغرات التبعيات — يجب مراقبتها، لأن ثغرات التبعيات خطر حقيقي.
يعرّف ساليم start وdev وtest في سكربتاته ويجعل npm audit منعكسه قبل كل نشر.
3. اختيار الحزم دون تعرّض
المنظومة الهائلة قوة (لا تعيدوا اختراع العجلة) وخطر (ثغرات، جودة متفاوتة، حزم مهجورة). للاختيار: الشعبية (التنزيلات، التبني)، الصيانة النشطة (تحديثات حديثة، قضايا مُعالَجة)، توثيق جدّي، نطاق أدنى (لا حزمة ضخمة لدالة تافهة). وفي Git: نُصدِر package.json + lock، ولا نُصدِر أبدًا node_modules ولا الأسرار (.env).
يتحقق ساليم من التنزيلات وآخر تحديث قبل التثبيت، ويضيف node_modules/ و.env إلى .gitignore منذ أول commit.
🔎 مثال ملموس — 🔎 مثال عملي — التهيئة والتثبيت
الأوامر الأساسية، بالترتيب.
npm init -y # ينشئ package.json
npm install express # تبعية (إنتاج)
npm install -D nodemon # تبعية تطوير (dev)
npm run dev # يُطلق السكربت "dev"
npm audit # الثغرات المعروفةالقراءة: -D تعلّم أدوات التطوير؛ وnpm run تُطلق سكربتات البيان.
الدرس: تجاهلوا node_modules و.env في .gitignore — منعكس منذ أول commit.
مفردات القسم
- npm والسجل (Registry)
- مدير حزم Node، يتيح الوصول إلى أكبر سجل مفتوح المصدر في العالم (مئات آلاف المكتبات القابلة لإعادة الاستعمال).
مثال بسيط: إطار الويب الذي ثبّته ساليم بدل إعادة كتابته.
ما ليس كذلك: إعادة كتابة موجّه HTTP أو عميل قاعدة بأنفسكم.
رد فعل: ابحثوا عن الحزمة المجرَّبة قبل إعادة الكتابة.
- package.json
- بيان المشروع: الاسم، الإصدار، التبعيات، السكربتات، البيانات الوصفية. يُنشأ مع npm init؛ مرجع كل مشروع Node.
مثال بسيط: الـ package.json الخاصة بساليم مع start وdev وtest.
ما ليس كذلك: مجلد كود دون بيان، لا يُثبَّت بنظافة.
رد فعل: npm init منذ اليوم الأول للمشروع.
- dependencies مقابل devDependencies
- dependencies: لازمة في الإنتاج. devDependencies: مفيدة في التطوير فقط (تُثبَّت مع -D). node_modules: مجلد الحزم المثبتة، لا يُصدَّر، قابل لإعادة التوليد.
مثال بسيط: إطار العمل في dependencies وأداة إعادة التشغيل في devDependencies لدى ساليم.
ما ليس كذلك: إرسال node_modules كمرفق إلى الزميل.
رد فعل: -D للأدوات، وGit يتجاهل node_modules.
- package-lock.json
- ملف يجمّد الإصدارات الدقيقة المثبتة؛ يضمن أن الجميع يثبّت بدقة الإصدارات نفسها (قابلية إعادة الإنتاج).
مثال بسيط: الـ lock الذي يجعل جهاز ساليم والإنتاج يثبّتان الشيء نفسه.
ما ليس كذلك: «يعمل لدي» مع إصدارات مختلفة في كل مكان.
رد فعل: أصدِروا الـ lock، ولا تحرّروه يدويًا أبدًا.
- semver وسكربتات npm
- ترقيم رئيسي.فرعي.تصحيحي (^ تسمح بالفرعية والتصحيحية، و~ بالتصحيحية فقط). السكربتات تعرّف أوامر قابلة لإعادة الاستعمال (npm run
). مثال بسيط: الـ ^ التي تسمح بمرور التصحيحات الأمنية لدى ساليم، وnpm run dev الخاصة به.
ما ليس كذلك: إصدارات مجمّدة للأبد أو أوامر مختلفة لكل مطور.
رد فعل: افهموا ^ / ~، ووحّدوا عبر السكربتات.
في التطبيق — عمليًا — إدارة مشروع مع npm
- هيّئوا مشروعًا مع npm init -y وافحصوا الـ package.json المولَّد (الاسم، الإصدار، السكربتات).
- ثبّتوا حزمة (npm install express) وتبعية تطوير (npm install -D nodemon)؛ ولاحظوا node_modules وpackage.json وpackage-lock.json.
- أضيفوا سكربتات إلى package.json ("start" و"dev") وأطلقوها مع npm start / npm run dev.
- افهموا semver (^ مقابل ~)، وتجاهلوا node_modules (.gitignore)، وأطلقوا npm audit لرصد الثغرات.
نص جاهز — تأطير نظافة npm في الفريق (30 ثانية)
«نُصدِر package.json والـ lock، ولا نُصدِر أبدًا node_modules — كل واحد يعيد التوليد مع npm install. أدوات التطوير تمر بـ -D، والأوامر في سكربتات، ونقوم بـ npm audit قبل كل تسليم.»
يُقال عند بدء المشروع؛ تحققوا من .gitignore عند أول commit.
نموذج نسخ ولصق — package.json أدنى + .gitignore
{
"name": "projet-salim",
"version": "1.0.0",
"scripts": {
"start": "node app.js",
"dev": "nodemon app.js",
"test": "jest"
},
"dependencies": {},
"devDependencies": {}
}
// .gitignore :
// node_modules/
// .envمشروع دون بيان
كما فعل ساليم: npm init -y، إعادة تثبيت الحزم واحدة واحدة مع التمييز بين الإنتاج و-D، إعادة إنشاء السكربتات — لا تستردوا أبدًا node_modules من شخص آخر.
فريق في الجزائر
سكربتات start/dev/test متماثلة للجميع: كل مطور يُطلق الأوامر نفسها، انتهى زمن «أنا كنت أفعل غير ذلك».
صعود إصدار حذر
اقرأوا ما تسمح به ^ و~ قبل التحديث؛ اختبروا بعد كل صعود فرعي، وجمّدوا عبر الـ lock.
تسليم وشيك
npm audit قبل التسليم: صحّحوا الثغرات المُبلَّغ عنها، وتحقّقوا أن .env وnode_modules خارج Git فعلًا.
✓ ممارسات جيدة
- أصدِروا json + lock، ولا تُصدِروا أبدًا node_modules.
- أدوات التطوير في -D، والأوامر في سكربتات.
- npm audit قبل كل تسليم.
✗ أخطاء شائعة
- إصدار node_modules.
- نسيان .env في .gitignore.
- تجاهل تنبيهات npm audit.
النقاط الأساسية
- يتيح npm الوصول إلى أكبر سجل مفتوح المصدر في العالم: تثبيت الحزم بدل كتابة كل شيء — مسرّع رئيسي.
- package.json = البيان (التبعيات، السكربتات)؛ وpackage-lock.json يجمّد الإصدارات الدقيقة. node_modules لا تُصدَّر (قابلة لإعادة التوليد).
- dependencies (الإنتاج) مقابل devDependencies (التطوير، -D)؛ والترقيم الدلالي رئيسي.فرعي.تصحيحي (^ للفرعية/التصحيحية، و~ للتصحيحية).
- سكربتات npm توحّد الأوامر؛ وnpm audit تُبلغ عن الثغرات (يجب مراقبتها).
تحدي 48 ساعة — طبّق غدًا
هيّئوا مشروعًا حقيقيًا (النموذج أعلاه): npm init -y، حزمة واحدة + تبعية تطوير واحدة (-D)، سكربتان، .gitignore (node_modules و.env)، ثم npm audit. تكفي 25 دقيقة.
- أستطيع شرح package.json والـ lock وnode_modules.
- أعرف التمييز بين dependencies وdevDependencies وsemver ^ / ~.
- لدي مشروع يُثبَّت عبر npm install ومُدقَّق.
أسئلة شائعة
ماذا يجب إصداره (Git) في مشروع Node، ولماذا لا node_modules؟
أصدِروا كودكم وpackage.json («الوصفة»: التبعيات، السكربتات) وpackage-lock.json (الإصدارات الدقيقة، بما فيها التبعيات الفرعية) — مع .gitignore وREADME والإعدادات. لا تُصدِروا أبدًا node_modules: فهي ضخمة (آلاف الملفات)، قابلة لإعادة التوليد بـ npm install انطلاقًا من البيانين، وأحيانًا خاصة بالمنصة. كما فعل ساليم: نشارك الوصفة (json + lock)، وكل واحد يعيد توليد النتيجة. استبعدوا أيضًا الأسرار (.env) والسجلات والمؤقتات.
منظومة npm هائلة: كيف نختار حزمًا جيدة؟
عدم إعادة اختراع العجلة ميزة رئيسية — لكن التبعيات خطر أيضًا (ثغرات، جودة متفاوتة، هجر). للاختيار: الشعبية (التنزيلات، النجوم — إشارة جيدة)، الصيانة النشطة (تحديثات حديثة، قضايا مُعالَجة)، توثيق جدّي، نطاق أدنى (لا حزمة ضخمة لتفاهة). ثم أديروا: أبقوا التبعيات محدَّثة (semver مفهوم)، وراقبوا npm audit، وفضّلوا قليلًا من التبعيات المجرَّبة على حشد من المجهولات.
ماذا يجب إصداره في Git لمشروع Node؟