npm وإدارة الحزم في Node.js — دليل شامل 2026

في المقال السابق، تعلمت الوحدات ونظام الملفات. الآن سنتعمق في npm — مدير الحزم الذي يجعل Node.js بهذه القوة.

في هذا الدليل العملي، سنأخذك خطوة بخطوة لفهم npm وإدارة الحزم، مع تمارين وحلول.

ما هو npm؟

npm = Node Package Manager (مدير حزم Node.js).

npm هو:

• مستودع: أكبر مستودع حزم في العالم (2+ مليون حزمة).
• أداة CLI: لتثبيت وإدارة الحزم.
• سجل: يحتوي كل مكتبات JavaScript مفتوحة المصدر.

تشبيه بسيط: تخيل أن npm هو متجر تطبيقات (مثل App Store):

• تبحث عن تطبيق (مكتبة).
• تثبته (install).
• تحدّثه (update).
• تحذفه (uninstall).

لماذا npm؟

قبل أن نبدأ، دعنا نتفق على الأسباب:

• إعادة استخدام: لا تكتب كل شيء من الصفر.
• توفير الوقت: مكتبات جاهزة ومختبرة.
• الجودة: مكتبات يستخدمها ملايين المطورين.
• التحديثات: صيانة مستمرة.
• المجتمع: أكبر مستودع حزم في العالم.

المفاهيم الأساسية

المفهوم	الوصف
Package	مكتبة أو وحدة جاهزة
package.json	بطاقة تعريف المشروع
package-lock.json	قفل الإصدارات
node_modules	مجلد المكتبات المثبتة
dependencies	مكتبات الإنتاج
devDependencies	مكتبات التطوير

إنشاء package.json

الطريقة 1: npm init (تفاعلي)

npm init

سيطلب منك:

• name: اسم المشروع.
• version: الإصدار.
• description: الوصف.
• entry point: نقطة البداية.
• test command: أمر الاختبار.
• git repository: المستودع.
• keywords: الكلمات المفتاحية.
• author: المؤلف.
• license: الترخيص.

الطريقة 2: npm init -y (سريع)

npm init -y

النتيجة:

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

فهم package.json

{
  "name": "my-app",
  "version": "1.0.0",
  "description": "تطبيقي الأول",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "test": "jest"
  },
  "keywords": ["nodejs", "express"],
  "author": "أحمد",
  "license": "MIT",
  "dependencies": {
    "express": "^4.18.2",
    "dotenv": "^16.3.1"
  },
  "devDependencies": {
    "nodemon": "^3.0.1",
    "jest": "^29.7.0"
  }
}

شرح الحقول:

الحقل	الوصف
name	اسم المشروع
version	الإصدار (SemVer)
main	نقطة البداية
scripts	أوامر مخصصة
dependencies	مكتبات الإنتاج
devDependencies	مكتبات التطوير

تثبيت الحزم

1. تثبيت مكتبة (إنتاج)

npm install express

أو:

npm i express

النتيجة: تُضاف إلى dependencies.

2. تثبيت مكتبة (تطوير)

npm install --save-dev nodemon

أو:

npm i -D nodemon

النتيجة: تُضاف إلى devDependencies.

3. تثبيت عدة مكتبات

npm install express cors dotenv mongoose

4. تثبيت مكتبة عالمياً

npm install -g typescript

⚠️ نادراً ما تحتاجه.

5. تثبيت نسخة محددة

npm install [email protected]

6. تثبيت كل المكتبات

من package.json:

npm install

أو:

npm i

حذف الحزم

# حذف مكتبة
npm uninstall express

# حذف مكتبة تطوير
npm uninstall nodemon

تحديث الحزم

# عرض المكتبات القديمة
npm outdated

# تحديث مكتبة
npm update express

# تحديث الكل
npm update

رموز الإصدارات (SemVer)

SemVer = Semantic Versioning.

الصيغة: MAJOR.MINOR.PATCH (مثل: 1.4.2).

الرمز	المعنى	المثال
^	تحديث Minor و Patch	^1.4.2 → 1.x.x
~	تحديث Patch فقط	~1.4.2 → 1.4.x
بدون	نسخة محددة	1.4.2
*	أي نسخة	*

الشرح:

• 1.4.2 → 1.4.5: Patch (إصلاح أخطاء).
• 1.4.2 → 1.5.0: Minor (ميزات جديدة، متوافق).
• 1.4.2 → 2.0.0: Major (تغييرات كاسرة).

السكربتات (Scripts)

في package.json:

{
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "test": "jest",
    "lint": "eslint .",
    "build": "tsc"
  }
}

التشغيل:

npm start          # npm run start (اختصار)
npm run dev
npm run test
npm run lint
npm run build

⚠️ ملاحظة: start و test لهما اختصارات (npm start بدلاً من npm run start).

المكتبات الشائعة

1. Express — إطار ويب

npm install express

الاستخدام:

const express = require("express");
const app = express();

app.get("/", (req, res) => {
  res.send("مرحباً!");
});

app.listen(3000);

2. dotenv — متغيرات البيئة

npm install dotenv

الاستخدام:

require("dotenv").config();

const PORT = process.env.PORT || 3000;

3. CORS — السماح بالطلبات

npm install cors

الاستخدام:

const cors = require("cors");
app.use(cors());

4. Nodemon — إعادة تشغيل تلقائية

npm install -D nodemon

الاستخدام:

"scripts": {
  "dev": "nodemon index.js"
}

5. Mongoose — MongoDB

npm install mongoose

الاستخدام:

const mongoose = require("mongoose");
await mongoose.connect("mongodb://localhost:27017/mydb");

6. bcrypt — تشفير كلمات المرور

npm install bcrypt

الاستخدام:

const bcrypt = require("bcrypt");
const hash = await bcrypt.hash("password", 10);

7. jsonwebtoken — JWT

npm install jsonwebtoken

الاستخدام:

const jwt = require("jsonwebtoken");
const token = jwt.sign({ userId: 1 }, "secret");

.gitignore — مهم جداً!

لا ترفع node_modules إلى Git!

أنشئ .gitignore:

node_modules/
.env
*.log
.DS_Store
dist/
build/
coverage/

مجلد node_modules

⚠️ مهم:

• لا تعدّله يدوياً.
• لا ترفعه لـ Git.
• يمكن حذفه وإعادة تثبيته بـ npm install.

الحجم: يمكن أن يصل إلى مئات الميجابايت!

package-lock.json

يحتوي على:

• الإصدارات الدقيقة لكل مكتبة.
• شجرة التبعيات الكاملة.

⚠️ مهم:

• ارفعها لـ Git.
• لا تعدّلها يدوياً.
• تضمن نفس الإصدارات لفريق العمل.

مثال عملي: مشروع Express

1. إنشاء المشروع

mkdir express-demo
cd express-demo
npm init -y
npm install express dotenv
npm install -D nodemon

2. إنشاء .env

PORT=3000
NODE_ENV=development

3. إنشاء index.js

require("dotenv").config();
const express = require("express");

const app = express();
const PORT = process.env.PORT || 3000;

app.use(express.json());

app.get("/", (req, res) => {
  res.json({ message: "مرحباً من Express!" });
});

app.get("/health", (req, res) => {
  res.json({ status: "OK", timestamp: new Date().toISOString() });
});

app.listen(PORT, () => {
  console.log(`🚀 السيرفر يعمل على http://localhost:${PORT}`);
});

4. تعديل package.json

"scripts": {
  "start": "node index.js",
  "dev": "nodemon index.js"
}

5. التشغيل

npm run dev

النتيجة:

🚀 السيرفر يعمل على http://localhost:3000

افتح المتصفح على http://localhost:3000 — سترى:

{ "message": "مرحباً من Express!" }

🎉 مبروك! بنيت أول سيرفر Express!

تمارين عملية

تمرين 1: إنشاء مشروع

أنشئ مشروعاً جديداً مع package.json.

الحل:

mkdir my-project
cd my-project
npm init -y

تمرين 2: تثبيت مكتبة

ثبّت lodash كمكتبة إنتاج.

الحل:

npm install lodash

تمرين 3: تثبيت مكتبة تطوير

ثبّت nodemon كمكتبة تطوير.

الحل:

npm install -D nodemon

تمرين 4: السكربتات

أضف سكربت dev لتشغيل nodemon.

الحل:

"scripts": {
  "dev": "nodemon index.js"
}

تمرين 5: استخدام lodash

استخدم lodash لعكس مصفوفة.

الحل:

const _ = require("lodash");

const reversed = _.reverse([1, 2, 3, 4, 5]);
console.log(reversed);  // [5, 4, 3, 2, 1]

تمرين 6: مشروع Express بسيط

أنشئ مشروع Express مع 3 مسارات.

الحل:

const express = require("express");
const app = express();

app.get("/", (req, res) => res.send("الرئيسية"));
app.get("/about", (req, res) => res.send("من نحن"));
app.get("/contact", (req, res) => res.send("اتصل بنا"));

app.listen(3000, () => console.log("🚀 يعمل"));

تمرين 7: متغيرات البيئة

استخدم dotenv لقراءة PORT من .env.

الحل:

require("dotenv").config();
const express = require("express");

const app = express();
const PORT = process.env.PORT || 3000;

app.listen(PORT, () => console.log(`🚀 على ${PORT}`));

تمرين 8: مشروع كامل

أنشئ مشروعاً كاملاً مع Express, dotenv, nodemon.

الحل: (راجع المثال العملي أعلاه)

حل المشاكل الشائعة

🔴 المشكلة 1: npm install بطيء

الحل: استخدم مرآة أسرع:

npm config set registry https://registry.npmmirror.com

للرجوع:

npm config set registry https://registry.npmjs.org

🔴 المشكلة 2: EACCES: permission denied

الحل (ماك/لينكس):

sudo chown -R $(whoami) ~/.npm

🔴 المشكلة 3: Cannot find module 'xxx'

الحل:

npm install

🔴 المشكلة 4: تعارض الإصدارات

الحل:

rm -rf node_modules package-lock.json
npm install

🔴 المشكلة 5: npm ERR! peer dep missing

الحل:

npm install --legacy-peer-deps

جدول أوامر npm

الأمر	الوظيفة
npm init -y	إنشاء package.json
npm install	تثبيت كل المكتبات
npm i <package>	تثبيت مكتبة
npm i -D <package>	تثبيت للتطوير
npm i -g <package>	تثبيت عالمي
npm uninstall <package>	حذف مكتبة
npm update	تحديث المكتبات
npm outdated	عرض القديمة
npm list	عرض المثبتة
npm run <script>	تشغيل سكربت

قائمة تحقق نهائية

المهمة	الحالة
إنشاء package.json	⬜
تثبيت مكتبة إنتاج	⬜
تثبيت مكتبة تطوير	⬜
فهم SemVer	⬜
إنشاء سكربتات	⬜
إنشاء .gitignore	⬜
بناء مشروع Express	⬜
حل التمارين الثمانية	⬜

ماذا بعد هذا المقال؟

الآن بعد أن أتقنت npm، أنت جاهز للمقال التالي:

1. بناء HTTP Server — أول سيرفر بدون Express.
2. Express.js — إطار العمل الكامل.
3. بناء REST API — واجهات برمجية.

الخلاصة

في هذا المقال، تعلمت:

• ✅ ما هو npm ولماذا نحتاجه.
• ✅ إنشاء package.json.
• ✅ تثبيت وحذف وتحديث الحزم.
• ✅ رموز الإصدارات (SemVer).
• ✅ السكربتات (Scripts).
• ✅ المكتبات الشائعة.
• ✅ .gitignore و node_modules.
• ✅ بناء مشروع Express.
• ✅ حل 8 تمارين عملية.

تذكر: npm هو سلاحك السري في Node.js. أتقنه جيداً.