Node.js و Express

إدارة الحزم باستخدام NPM

18 دقيقة الدرس 6 من 40

فهم NPM (مدير حزم Node)

NPM هو مدير الحزم الافتراضي لـ Node.js وأكبر سجل للبرمجيات في العالم. يسمح للمطورين بمشاركة واكتشاف واستخدام حزم الكود التي أنشأها المجتمع. NPM ضروري لتطوير Node.js الحديث، حيث يوفر الوصول إلى مئات الآلاف من الحزم القابلة لإعادة الاستخدام.

ما هي الحزمة؟

الحزمة هي قطعة من الكود قابلة لإعادة الاستخدام يمكن مشاركتها واستخدامها عبر مشاريع مختلفة. يمكن أن تتراوح الحزم من دوال بسيطة إلى أطر عمل معقدة مثل Express.js أو React. يجعل NPM من السهل تثبيت وتحديث وإدارة هذه الحزم في مشاريعك.

ملاحظة: يتم تثبيت NPM تلقائيًا عند تثبيت Node.js. يمكنك التحقق من إصدار NPM الخاص بك عن طريق تشغيل npm --version أو npm -v في الطرفية الخاصة بك.

تهيئة مشروع Node.js

يبدأ كل مشروع Node.js يستخدم NPM بملف package.json. يحتوي هذا الملف على معلومات وصفية حول مشروعك ويدير تبعياته.

إنشاء package.json

لإنشاء ملف package.json جديد، انتقل إلى دليل مشروعك وقم بتشغيل:

npm init

سيطالبك هذا الأمر بعدة أسئلة حول مشروعك (الاسم، الإصدار، الوصف، نقطة الدخول، إلخ). يمكنك الضغط على Enter لقبول القيم الافتراضية لأي سؤال.

التهيئة السريعة

لإنشاء ملف package.json بجميع القيم الافتراضية دون الإجابة على الأسئلة:

npm init -y

هذا ينشئ ملف package.json أساسي يمكنك تحريره لاحقًا:

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

تثبيت الحزم

يوفر NPM عدة طرق لتثبيت الحزم حسب احتياجاتك.

التثبيت المحلي

لتثبيت حزمة محليًا في مشروعك:

npm install package-name

أو باستخدام الاختصار:

npm i package-name

هذا الأمر:

يقوم بتنزيل الحزمة من سجل NPM
يثبتها في مجلد node_modules
يضيفها إلى قسم dependencies في package.json
ينشئ أو يحدث package-lock.json لتثبيت إصدارات التبعيات

مثال: تثبيت Express

npm install express

بعد التثبيت، سيتضمن package.json الخاص بك:

"dependencies": {
  "express": "^4.18.2"
}

التثبيت العام

بعض الحزم مخصصة للتثبيت عالميًا، عادةً أدوات سطر الأوامر:

npm install -g package-name

أمثلة على الحزم المثبتة عالميًا:

npm install -g nodemon
npm install -g typescript
npm install -g create-react-app

تحذير: قد تتطلب التثبيتات العامة امتيازات المسؤول (sudo على Mac/Linux). استخدم التثبيت العام بحذر—يجب تثبيت معظم الحزم محليًا لتجنب تعارضات الإصدارات بين المشاريع.

التبعيات مقابل تبعيات التطوير

يميز NPM بين نوعين من التبعيات بناءً على متى تكون مطلوبة.

التبعيات (Dependencies)

هذه هي الحزم المطلوبة لتشغيل تطبيقك في الإنتاج:

npm install express
npm install mongoose
npm install dotenv

يتم إدراج هذه الحزم ضمن "dependencies" في package.json.

تبعيات التطوير (DevDependencies)

هذه هي الحزم المطلوبة فقط أثناء التطوير (أدوات الاختبار، أدوات البناء، أدوات التدقيق):

npm install --save-dev nodemon
npm install --save-dev jest
npm install --save-dev eslint

أو باستخدام الاختصار:

npm i -D nodemon

يتم إدراج هذه الحزم ضمن "devDependencies" في package.json:

{
  "dependencies": {
    "express": "^4.18.2",
    "mongoose": "^7.0.3"
  },
  "devDependencies": {
    "nodemon": "^2.0.22",
    "jest": "^29.5.0"
  }
}

نصيحة: عند النشر إلى الإنتاج، يمكنك تثبيت تبعيات الإنتاج فقط باستخدام npm install --production، مما يتخطى devDependencies ويقلل من وقت التثبيت والحجم.

فهم إصدار الدلالات (Semantic Versioning)

يستخدم NPM إصدار الدلالات (semver) لإدارة إصدارات الحزم. تتبع أرقام الإصدارات التنسيق: MAJOR.MINOR.PATCH

تنسيق رقم الإصدار

MAJOR: تغييرات جذرية (تغييرات API غير متوافقة)
MINOR: ميزات جديدة (متوافقة مع الإصدارات السابقة)
PATCH: إصلاحات الأخطاء (متوافقة مع الإصدارات السابقة)

مثال: 4.18.2 يعني الإصدار الرئيسي 4، الإصدار الفرعي 18، إصدار التصحيح 2

رموز نطاق الإصدار

يستخدم NPM رموزًا خاصة لتحديد نطاقات الإصدارات المقبولة:

"express": "4.18.2"     // الإصدار الدقيق فقط
"express": "^4.18.2"    // متوافق مع 4.18.2 (تحديثات فرعية وتصحيح مسموحة)
"express": "~4.18.2"    // مكافئ تقريبًا (تحديثات التصحيح فقط مسموحة)
"express": "*"          // أحدث إصدار (غير موصى به)
"express": ">=4.18.2"   // أكبر من أو يساوي 4.18.2

ملاحظة: علامة الإقحام (^) هي الافتراضية عند تثبيت الحزم. تسمح بالتحديثات التي لا تغير الرقم الأيسر غير الصفري. على سبيل المثال، ^4.18.2 تسمح بإصدارات مثل 4.19.0 أو 4.25.1، ولكن ليس 5.0.0.

إدارة الحزم المثبتة

عرض الحزم المثبتة

لعرض جميع الحزم المثبتة محليًا:

npm list

لعرض الحزم من المستوى الأعلى فقط (بدون التبعيات):

npm list --depth=0

لعرض الحزم المثبتة عالميًا:

npm list -g --depth=0

تحديث الحزم

لتحديث جميع الحزم إلى أحدث إصداراتها المسموح بها (مع احترام semver):

npm update

لتحديث حزمة معينة:

npm update express

للتحقق من الحزم القديمة:

npm outdated

إلغاء تثبيت الحزم

لإزالة حزمة:

npm uninstall package-name

هذا يزيل الحزمة من node_modules و package.json. الاختصار:

npm un package-name

سكريبتات NPM

تسمح لك سكريبتات NPM بتعريف أوامر مخصصة في ملف package.json الخاص بك. هذه ميزة قوية لأتمتة المهام.

تعريف السكريبتات

يتم تعريف السكريبتات في قسم "scripts" من package.json:

{
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "test": "jest",
    "build": "webpack --mode production"
  }
}

تشغيل السكريبتات

لتشغيل سكريبت:

npm run script-name

على سبيل المثال:

npm run dev
npm run test
npm run build

السكريبتات الخاصة

بعض أسماء السكريبتات لها معنى خاص ويمكن تشغيلها بدون run:

npm start    // يشغل سكريبت "start"
npm test     // يشغل سكريبت "test"
npm stop     // يشغل سكريبت "stop"

سكريبتات ما قبل وما بعد

يشغل NPM تلقائيًا سكريبتات pre و post إذا كانت موجودة:

{
  "scripts": {
    "prestart": "echo Starting application...",
    "start": "node index.js",
    "poststart": "echo Application started!"
  }
}

تشغيل npm start سينفذ جميع السكريبتات الثلاثة بالترتيب.

نصيحة: يمكنك تمرير معاملات إلى السكريبتات باستخدام --. على سبيل المثال: npm start -- --port=3000 يمرر --port=3000 إلى السكريبت الخاص بك.

فهم package-lock.json

يتم إنشاء ملف package-lock.json تلقائيًا عند تثبيت الحزم. يخدم عدة أغراض مهمة:

إصدارات دقيقة: يسجل الإصدار الدقيق لكل حزمة مثبتة، بما في ذلك التبعيات
الاتساق: يضمن تثبيت جميع أعضاء الفريق وبيئات النشر لإصدارات متطابقة
تثبيتات أسرع: يمكن لـ NPM تخطي بعض خطوات الحل عندما يكون هذا الملف موجودًا
الأمان: يتضمن تجزئات التكامل للتحقق من محتويات الحزمة

ملاحظة: قم دائمًا بإيداع package-lock.json في التحكم في الإصدار. يضمن إنشاءات قابلة للتكرار عبر بيئات مختلفة.

NPX - منفذ حزم Node

NPX هو أداة تأتي مع NPM (الإصدار 5.2+) تسمح لك بتنفيذ الحزم دون تثبيتها عالميًا.

فوائد NPX

تشغيل الحزم دون التثبيت العالمي
استخدام أحدث إصدار من الحزمة دائمًا
تنفيذ الحزم من عناوين URL البعيدة
تشغيل إصدارات مختلفة من نفس الحزمة للاختبار

استخدام NPX

بدلاً من تثبيت حزمة عالميًا:

// الطريقة القديمة
npm install -g create-react-app
create-react-app my-app

// طريقة NPX
npx create-react-app my-app

تشغيل الملفات الثنائية المحلية

يمكن لـ NPX أيضًا تشغيل الحزم المثبتة محليًا:

npx nodemon index.js
npx jest
npx eslint .

تحديد إصدارات الحزم

يمكنك تشغيل إصدارات معينة من الحزم:

npx node@14 script.js
npx create-react-app@4.0.0 my-app

نصيحة: NPX مثالي للأوامر لمرة واحدة وتجنب تلويث الحزم العامة. استخدمه للأدوات التي لا تحتاج إلى تثبيتها بشكل دائم.

نشر حزمك الخاصة

يسمح لك NPM بنشر حزمك الخاصة ليستخدمها الآخرون.

المتطلبات الأساسية

إنشاء حساب NPM في npmjs.com
تسجيل الدخول من سطر الأوامر:

npm login

إعداد حزمتك

تأكد من أن package.json الخاص بك يحتوي على الحقول المطلوبة:

{
  "name": "my-awesome-package",
  "version": "1.0.0",
  "description": "وصف موجز لحزمتك",
  "main": "index.js",
  "keywords": ["keyword1", "keyword2"],
  "author": "اسمك",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourusername/your-repo"
  }
}

النشر

لنشر حزمتك:

npm publish

لتحديث حزمتك، قم بزيادة رقم الإصدار وانشر مرة أخرى:

npm version patch    // 1.0.0 ← 1.0.1
npm version minor    // 1.0.1 ← 1.1.0
npm version major    // 1.1.0 ← 2.0.0
npm publish

تحذير: يجب أن تكون أسماء الحزم فريدة في سجل NPM. لا يمكنك نشر حزمة باسم موجود بالفعل. فكر في استخدام الحزم المحددة النطاق (@username/package-name) للمشاريع الشخصية.

أفضل الممارسات لإدارة الحزم

1. حافظ على التبعيات محدثة

تحقق بانتظام من التحديثات وقم بتثبيتها لإصلاح الثغرات الأمنية:

npm audit
npm audit fix

2. استخدم .npmignore

أنشئ ملف .npmignore لاستبعاد الملفات من حزمتك المنشورة:

node_modules/
tests/
.env
.git/
*.log

3. حدد متطلبات المحرك

حدد إصدارات Node.js و NPM التي تتطلبها حزمتك:

{
  "engines": {
    "node": ">=14.0.0",
    "npm": ">=6.0.0"
  }
}

4. استخدم ملفات القفل

قم دائمًا بإيداع package-lock.json لضمان تثبيتات متسقة.

5. التثبيتات النظيفة

لاستكشاف الأخطاء وإصلاحها، استخدم التثبيت النظيف الذي يتبع ملف القفل بدقة:

npm ci

تمرين: أنشئ مشروع Node.js جديد ومارس إدارة الحزم:

قم بتهيئة مشروع جديد باستخدام npm init -y
قم بتثبيت Express كتبعية
قم بتثبيت Nodemon كتبعية تطوير
أنشئ سكريبتات مخصصة: "start" (يعمل مع node) و "dev" (يعمل مع nodemon)
اختبر كلا السكريبتين
استخدم npm list --depth=0 لعرض حزمك
تحقق من الحزم القديمة باستخدام npm outdated
جرب استخدام NPX لتشغيل حزمة دون تثبيتها: npx cowsay Hello NPM!