إطار Next.js

إعداد مشروع Next.js

20 دقيقة الدرس 2 من 40

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

قبل إنشاء مشروع Next.js الأول، تأكد من تثبيت ما يلي على جهازك:

Node.js: الإصدار 16.8 أو أحدث (تحقق بـ node --version)
npm أو yarn: npm يأتي مع Node.js، أو يمكنك تثبيت yarn بشكل منفصل
محرر أكواد: يُنصح بشدة بـ Visual Studio Code
الطرفية: واجهة سطر الأوامر (Terminal على Mac/Linux، Command Prompt أو PowerShell على Windows)

نصيحة احترافية: إذا لم يكن لديك Node.js مثبت، قم بتحميله من nodejs.org. يُنصح بإصدار LTS (الدعم طويل الأمد) لمعظم المستخدمين.

إنشاء مشروع Next.js الأول

يوفر Next.js أداة سطر أوامر تسمى create-next-app تقوم بإعداد كل شيء تلقائيًا. هذه هي الطريقة الموصى بها لإنشاء تطبيق Next.js جديد.

استخدام create-next-app

افتح الطرفية وقم بتشغيل أحد الأوامر التالية:

# باستخدام npx (يأتي مع npm)
npx create-next-app@latest my-next-app

# باستخدام yarn
yarn create next-app my-next-app

# باستخدام pnpm
pnpm create next-app my-next-app

علامة @latest تضمن أنك تستخدم أحدث إصدار من create-next-app. استبدل "my-next-app" بأي اسم تريد إطلاقه على مشروعك.

الإعداد التفاعلي

بعد تشغيل الأمر، ستُطرح عليك عدة أسئلة لتكوين مشروعك:

✔ Would you like to use TypeScript? › No / Yes
✔ Would you like to use ESLint? › No / Yes
✔ Would you like to use Tailwind CSS? › No / Yes
✔ Would you like to use `src/` directory? › No / Yes
✔ Would you like to use App Router? (recommended) › No / Yes
✔ Would you like to customize the default import alias? › No / Yes

لنفهم كل خيار:

TypeScript: يضيف أمان النوع إلى كود JavaScript (موصى به للمشاريع الكبيرة)
ESLint: يساعد في اكتشاف الأخطاء وفرض نمط الكود (موصى به بشدة)
Tailwind CSS: إطار CSS قائم على الأدوات (اختياري، حسب التفضيل)
src/ directory: ينظم كودك في مجلد src منفصل (موصى به للمشاريع الكبيرة)
App Router: نظام التوجيه الجديد المقدم في Next.js 13+ (موصى به)
Import alias: يتيح لك استخدام مسارات استيراد مخصصة مثل @/components بدلاً من ../components

للمبتدئين: إذا كنت بدأت للتو، نوصي بالإجابة "لا" على TypeScript وTailwind CSS، لكن "نعم" على ESLint وApp Router. يمكنك دائمًا إضافة هذه الميزات لاحقًا.

بدء خادم التطوير

بمجرد اكتمال التثبيت، انتقل إلى مجلد مشروعك وابدأ خادم التطوير:

# الانتقال إلى مجلد المشروع
cd my-next-app

# بدء خادم التطوير
npm run dev
# أو
yarn dev
# أو
pnpm dev

يجب أن ترى إخراجًا مشابهًا لهذا:

  ▲ Next.js 14.1.0
  - Local:        http://localhost:3000
  - Network:      http://192.168.1.5:3000

✓ Ready in 2.3s

افتح متصفحك وانتقل إلى http://localhost:3000. يجب أن ترى صفحة الترحيب من Next.js!

إعادة التحميل الساخنة: يدعم خادم التطوير التحديث السريع، مما يعني أن أي تغييرات تجريها على كودك ستظهر تلقائيًا في المتصفح دون الحاجة إلى إعادة تحميل الصفحة يدويًا.

فهم بنية المشروع

لنستكشف الملفات والمجلدات التي أنشأها create-next-app لنا. تعتمد البنية على ما إذا اخترت App Router أو Pages Router:

بنية مشروع App Router (Next.js 13+)

my-next-app/
├── app/
│   ├── favicon.ico
│   ├── globals.css
│   ├── layout.js
│   └── page.js
├── public/
│   ├── next.svg
│   └── vercel.svg
├── node_modules/
├── .eslintrc.json
├── .gitignore
├── jsconfig.json
├── next.config.js
├── package.json
└── README.md

شرح الملفات والمجلدات الرئيسية

1. مجلد app/

هذا هو المكان الذي يعيش فيه كل كود تطبيقك عند استخدام App Router:

layout.js: التخطيط الجذري الذي يلف جميع الصفحات. يحتوي على بنية HTML والعناصر العامة
page.js: مكون الصفحة الرئيسية. يمثل هذا الملف المسار الجذري (/)
globals.css: أنماط CSS العامة التي تنطبق على تطبيقك بالكامل
favicon.ico: الأيقونة الصغيرة التي تظهر في علامات تبويب المتصفح

// app/page.js - مثال على الصفحة الرئيسية
export default function Home() {
  return (
    <main>
      <h1>مرحبًا بك في Next.js!</h1>
    </main>
  )
}

// app/layout.js - التخطيط الجذري
export default function RootLayout({ children }) {
  return (
    <html lang="ar">
      <body>{children}</body>
    </html>
  )
}

2. مجلد public/

الملفات الثابتة التي يمكن تقديمها مباشرة. الملفات في هذا المجلد يمكن الوصول إليها من عنوان URL الجذري:

الصور والخطوط والأصول الثابتة الأخرى توضع هنا
يتم تقديم الملفات في المسار الجذري، مثلاً public/logo.png يصبح /logo.png
لا تضع أبدًا معلومات حساسة هنا—كل شيء متاح للعامة

مهم: لا تسمِّ الملفات في مجلد public/ بنفس أسماء الملفات في مجلدات app/ أو pages/، حيث يمكن أن يسبب ذلك تعارضات.

3. node_modules/

يحتوي على جميع تبعيات مشروعك. يتم إنشاء هذا المجلد تلقائيًا عند تشغيل npm install ويجب ألا يتم تحريره يدويًا أو رفعه إلى التحكم في الإصدار.

4. ملفات التكوين

package.json: قلب مشروع Node.js. يحتوي على بيانات وصفية عن مشروعك ويسرد جميع التبعيات.

{
  "name": "my-next-app",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "next": "14.1.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}

next.config.js: ملف تكوين لتخصيص سلوك Next.js. في البداية معظمه فارغ، لكن يمكن توسيعه بخيارات عديدة.

/** @type {import('next').NextConfig} */
const nextConfig = {}

module.exports = nextConfig

.eslintrc.json: تكوين ESLint لفحص جودة الكود.

.gitignore: يخبر Git بالملفات التي يجب تجاهلها (مثل node_modules و.next).

jsconfig.json أو tsconfig.json: يكوّن خيارات مترجم JavaScript/TypeScript وأسماء المسارات المستعارة.

فهم سكريبتات package.json

قسم السكريبتات في package.json يحدد الأوامر التي يمكنك تشغيلها بـ npm run:

سكريبت التطوير

npm run dev

يبدأ خادم التطوير مع التحديث السريع. استخدم هذا أثناء تطوير تطبيقك. يراقب الخادم تغييرات الملفات ويعيد التحميل تلقائيًا.

سكريبت البناء

npm run build

ينشئ بناءً محسّنًا للإنتاج لتطبيقك. هذا الأمر:

يترجم كودك
يحسّن الأصول
يولد صفحات ثابتة (إذا كنت تستخدم SSG)
ينشئ مجلد .next جاهز للإنتاج

سكريبت البدء

npm run start

يبدأ خادم الإنتاج. يجب تشغيل npm run build قبل استخدام هذا الأمر. استخدم هذا لاختبار بناء الإنتاج محليًا.

سكريبت Lint

npm run lint

يشغل ESLint للتحقق من كودك للأخطاء المحتملة ومشاكل النمط.

سير عمل التطوير: أثناء التطوير، أبقِ npm run dev يعمل في طرفية واحدة. عندما تكون جاهزًا للنشر، شغل npm run build لإنشاء بناء الإنتاج، ثم اختبره بـ npm run start.

مجلد .next

بعد تشغيل npm run dev أو npm run build، ستلاحظ ظهور مجلد .next جديد. هذا هو مجلد إخراج بناء Next.js:

يحتوي على كود مترجم ومحسّن
يجب ألا يتم تحريره يدويًا أبدًا
يُضاف تلقائيًا إلى .gitignore
يمكن حذفه وإعادة إنشائه في أي وقت

إنشاء صفحتك المخصصة الأولى

لنعدل الصفحة الرئيسية لإنشاء شيء مخصص. افتح app/page.js واستبدل المحتوى بـ:

export default function Home() {
  return (
    <main style={{ padding: '2rem' }}>
      <h1>مرحبًا Next.js!</h1>
      <p>هذا هو تطبيق Next.js الأول الخاص بي.</p>
      <button onClick={() => alert('مرحبًا بك!')}>
        انقر هنا
      </button>
    </main>
  )
}

احفظ الملف وشاهد متصفحك يتحدث تلقائيًا بالمحتوى الجديد. هذا هو التحديث السريع في العمل!

إضافة أنماط عامة

يمكنك تعديل الأنماط العامة في app/globals.css. يتم استيراد هذا الملف في تخطيطك الجذري وينطبق على جميع الصفحات:

/* app/globals.css */
* {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
}

body {
  font-family: system-ui, -apple-system, sans-serif;
  background-color: #f5f5f5;
  color: #333;
}

h1 {
  color: #0070f3;
}

تثبيت حزم إضافية

يمكنك تثبيت حزم npm إضافية في أي وقت باستخدام npm أو yarn أو pnpm:

# تثبيت حزمة
npm install package-name

# تثبيت كتبعية تطوير
npm install --save-dev package-name

# إلغاء تثبيت حزمة
npm uninstall package-name

على سبيل المثال، لإضافة مكتبة التاريخ الشهيرة date-fns:

npm install date-fns

متغيرات البيئة

يتمتع Next.js بدعم مدمج لمتغيرات البيئة. أنشئ ملف .env.local في جذر مشروعك:

# .env.local
API_URL=https://api.example.com
NEXT_PUBLIC_SITE_NAME=تطبيق Next.js الخاص بي

مهم: متغيرات البيئة المسبوقة بـ NEXT_PUBLIC_ معروضة للمتصفح. المتغيرات بدون هذا البادئة متاحة فقط على جانب الخادم.

الوصول إلى متغيرات البيئة في كودك:

// من جانب الخادم فقط
const apiUrl = process.env.API_URL

// متاح في المتصفح أيضًا
const siteName = process.env.NEXT_PUBLIC_SITE_NAME

تحذير أمني: لا تعرض أبدًا معلومات حساسة (مفاتيح API، كلمات مرور قاعدة البيانات) باستخدام بادئة NEXT_PUBLIC_. هذه المتغيرات مضمنة في حزمة المتصفح ومرئية لأي شخص.

أوامر التطوير الشائعة

إليك بعض الأوامر المفيدة التي ستستخدمها بشكل متكرر:

# مسح ذاكرة التخزين المؤقت لـ Next.js (إذا واجهت مشاكل)
rm -rf .next

# مسح node_modules وإعادة التثبيت (يحل العديد من مشاكل التبعية)
rm -rf node_modules package-lock.json
npm install

# تحديث Next.js إلى أحدث إصدار
npm install next@latest react@latest react-dom@latest

# التحقق من الحزم القديمة
npm outdated

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

المنفذ قيد الاستخدام بالفعل

إذا كان المنفذ 3000 محجوزًا بالفعل، يمكنك تحديد منفذ مختلف:

npm run dev -- -p 3001

أخطاء الوحدة غير الموجودة

إذا حصلت على أخطاء الوحدة غير الموجودة، جرب:

حذف node_modules وpackage-lock.json
تشغيل npm install مرة أخرى
إعادة تشغيل خادم التطوير

التحديث السريع لا يعمل

إذا لم تنعكس التغييرات تلقائيًا:

تحقق من أخطاء بناء الجملة في كودك
تأكد من أنك تحرر ملفات داخل مجلد app/ أو pages/
حاول إيقاف وإعادة تشغيل خادم التطوير

تمارين عملية:

أنشئ مشروع Next.js جديد باستخدام create-next-app بإعداداتك المفضلة
ابدأ خادم التطوير وشاهد تطبيقك في المتصفح
عدل الصفحة الرئيسية لعرض اسمك ومقدمة موجزة
أضف بعض الأنماط المخصصة إلى globals.css وشاهدها مطبقة
أنشئ ملف .env.local مع متغير NEXT_PUBLIC_WELCOME_MESSAGE واعرضه على صفحتك
ثبت حزمة مثل date-fns واستخدمها لعرض التاريخ الحالي
شغل npm run build لإنشاء بناء إنتاج واختبره بـ npm run start

الخلاصة

في هذا الدرس، تعلمت كيفية إعداد مشروع Next.js من الصفر باستخدام create-next-app. استكشفنا بنية المشروع، وفهمنا الغرض من كل ملف ومجلد. تعلمت عن سكريبتات package.json للتطوير والبناء وبدء تطبيقك. غطينا أيضًا كيفية تخصيص مشروعك وإضافة أنماط عامة وتثبيت الحزم واستخدام متغيرات البيئة.

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