الدرس 2 / 6⏱ 25 دقيقة

إعداد Clerk مع Next.js

تثبيت وضبط Clerk في مشروعك

الخطوة 1: إنشاء مشروع Next.js

نبدأ بإنشاء مشروع Next.js جديد باستخدام الأمر التالي:

bash
npx create-next-app@latest my-app --yes

هذا الأمر سينشئ مشروع جديد باسم my-app مع جميع الإعدادات الافتراضية (JavaScript, App Router, TypeScript).

💡 ملاحظة:

خيار --yes يوافق تلقائياً على جميع الخيارات الافتراضية. يمكنك إزالته إذا أردت تخصيص الإعدادات يدوياً.

الخطوة 2: تثبيت Clerk SDK

انتقل إلى مجلد المشروع ثم ثبّت حزمة Clerk:

bash
cd my-app
npm install @clerk/nextjs

حزمة @clerk/nextjs هي الحزمة الرسمية لـ Clerk مع Next.js، وتوفر جميع المكونات والدوال اللازمة للمصادقة.

الخطوة 3: إنشاء ملف .env.local

أنشئ ملف .env.local في جذر المشروع وأضف مفاتيح Clerk من لوحة التحكم:

bash
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxx
CLERK_SECRET_KEY=sk_test_xxx
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL=/
NEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL=/

💡 مفتاح مهم:

احصل على هذه المفاتيح من لوحة تحكم Clerk على dashboard.clerk.com → اختر مشروعك → API Keys.

✅ شرح المتغيرات:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY - المفتاح العام (يظهر في الكود العميل). CLERK_SECRET_KEY - المفتاح السري (يُستخدم فقط على الخادم).

الخطوة 4: إنشاء middleware.ts

أنشئ ملف middleware.ts في جذر المشروع (بجانب مجلد app) لحماية جميع المسارات:

bash
// middleware.ts
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';

const isPublicRoute = createRouteMatcher([
  '/',
  '/learn(.*)',
  '/sign-in(.*)',
  '/sign-up(.*)',
]);

export default clerkMiddleware(async (auth, request) => {
  if (!isPublicRoute(request)) {
    await auth.protect();
  }
});

export const config = {
  matcher: [
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    '/(api|trpc)(.*)',
  ],
};

💡 ما هو middleware؟:

الـ middleware يُنفَّذ قبل كل طلب. في هذه الحالة، يتحقق Clerk من هوية المستخدم قبل السماح بالوصول للصفحات المحمية.

🔍 المسارات العامة:

الصفحة الرئيسية (/) والمنهج (/learn) وصفحات تسجيل الدخول والتسجيل مفتوحة للجميع without authentication.

الخطوة 5: إضافة ClerkProvider في layout.js

عدّل ملف app/layout.js للف التطبيق بـ ClerkProvider:

bash
import { ClerkProvider } from '@clerk/nextjs';

export default function RootLayout({ children }) {
  return (
    <ClerkProvider>
      <html lang="ar" dir="rtl">
        <body>{children}</body>
      </html>
    </ClerkProvider>
  );
}

💡 لماذا ClerkProvider؟:

يُوفّر ClerkProvider سياق (context) لجميع مكونات Clerk في التطبيق. بدونه، لن تعمل مكونات المصادقة.

الخطوة 6: إنشاء صفحة Sign-In

أنشئ ملف app/sign-in/[[...sign-in]]/page.js:

bash
// app/sign-in/[[...sign-in]]/page.js
import { SignIn } from '@clerk/nextjs';

export default function SignInPage() {
  return (
    <div className="flex justify-center items-center min-h-screen">
      <SignIn />
    </div>
  );
}

🔍 ما هو [[...sign-in]]؟:

هذا هو Catch-all route في Next.js. المكون [[...sign-in]] يلتقط جميع المسارات الفرعية التي تبدأ بـ /sign-in.

الخطوة 7: إنشاء صفحة Sign-Up

أنشئ ملف app/sign-up/[[...sign-up]]/page.js:

bash
// app/sign-up/[[...sign-up]]/page.js
import { SignUp } from '@clerk/nextjs';

export default function SignUpPage() {
  return (
    <div className="flex justify-center items-center min-h-screen">
      <SignUp />
    </div>
  );
}

الخطوة 8: إنشاء صفحة Dashboard محمية

أنشئ ملف app/dashboard/page.js مع حماية تلقائية:

bash
// app/dashboard/page.js
import { currentUser } from '@clerk/nextjs/server';
import { auth } from '@clerk/nextjs/server';
import { redirect } from 'next/navigation';

export default async function DashboardPage() {
  // حماية الصفحة - إذا لم يكن المستخدم مسجلاً، يُحوّل لصفحة تسجيل الدخول
  const { userId } = await auth();
  if (!userId) {
    redirect('/sign-in');
  }

  // جلب بيانات المستخدم
  const user = await currentUser();

  return (
    <div className="container mx-auto p-8">
      <h1 className="text-3xl font-bold mb-4">مرحباً {user.firstName}</h1>
      <p className="mb-2">البريد الإلكتروني: {user.emailAddresses[0].emailAddress}</p>
      <p>معرف المستخدم: {user.id}</p>
    </div>
  );
}

💡 طرقا للحماية:

1) auth() - للتحقق من userId يدوياً. 2) auth.protect() - للحماية التلقائية (يرمي خطأ إذا لم يكن المستخدم مسجلاً).

الخطوة 9: تعديل الصفحة الرئيسية

عدّل app/page.js لإظهار محتوى مختلف حسب حالة تسجيل الدخول:

bash
// app/page.js
import { SignedIn, SignedOut, SignInButton, UserButton } from '@clerk/nextjs';

export default function Home() {
  return (
    <div className="container mx-auto p-8">
      <h1>مرحباً بك في تطبيقنا</h1>

      {/* يظهر للمستخدم غير المسجل */}
      <SignedOut>
        <p>سجّل دخولك للوصول لل Dashboard</p>
        <SignInButton />
      </SignedOut>

      {/* يظهر للمستخدم المسجل */}
      <SignedIn>
        <p>أنت مسجل الدخول!</p>
        <UserButton />
        <a href="/dashboard">الذهاب لل Dashboard</a>
      </SignedIn>
    </div>
  );
}

✅ المكونات الشرطية:

SignedIn يعرض محتواه فقط للمستخدم المسجل. SignedOut يعرض محتواه فقط للمستخدم غير المسجل.

ملخص الدرس

أنشئ مشروع Next.js بـ npx create-next-app@latest my-app --yes

ثبّت Clerk بـ npm install @clerk/nextjs

أنشئ .env.local بمفاتيح Clerk من لوحة التحكم

أنشئ middleware.ts لحماية المسارات

أضف ClerkProvider في app/layout.js

أنشئ صفحات Sign-In و Sign-Up باستخدام المكونات المدمجة

أنشئ Dashboard محمي باستخدام auth() و currentUser()

استخدم SignedIn و SignedOut للمحتوى الشرطي

❓Quiz

ما هو الأمر الذي ينشئ مشروع Next.js جديد؟

❓Quiz

أين تحصل على مفاتيح Clerk؟

❓Quiz

ما هو ملف middleware.ts؟

🎯步骤 1-5: الإعداد الأساسي

أنشئ مشروع Next.js جديد، ثبّت Clerk، أنشئ .env.local، أنشئ middleware.ts، وأضف ClerkProvider في layout.js.

الحل:

bash
# الخطوة 1: إنشاء مشروع Next.js جديد
npx create-next-app@latest my-app --yes

# الخطوة 2: تثبيت Clerk
cd my-app
npm install @clerk/nextjs

# الخطوة 3: إنشاء ملف .env.local
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxx
CLERK_SECRET_KEY=sk_test_xxx
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL=/
NEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL=/

# الخطوة 4: إنشاء middleware.ts في جذر المشروع

# الخطوة 5: إضافة ClerkProvider في app/layout.js

# الخطوة 6: إنشاء صفحة Sign-In
# app/sign-in/[[...sign-in]]/page.js

# الخطوة 7: إنشاء صفحة Sign-Up
# app/sign-up/[[...sign-up]]/page.js

# الخطوة 8: إنشاء صفحة Dashboard محمية
# app/dashboard/page.js

# الخطوة 9: تعديل الصفحة الرئيسية
# app/page.js مع SignedIn و SignedOut

# شغّل المشروع
npm run dev

📋ملخص إعداد Clerk الشامل

الخطوات:

1. npx create-next-app@latest my-app --yes
2. npm install @clerk/nextjs
3. إنشاء .env.local بمفاتيح Clerk
4. إنشاء middleware.ts لحماية المسارات
5. إضافة ClerkProvider في layout.js
6. إنشاء صفحة Sign-In
7. إنشاء صفحة Sign-Up
8. إنشاء Dashboard محمي
9. تعديل الصفحة الرئيسية مع SignedIn/SignedOut

الكود الأساسي:

typescript
// .env.local
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxx
CLERK_SECRET_KEY=sk_test_xxx

// middleware.ts
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
const isPublicRoute = createRouteMatcher(['/']);
export default clerkMiddleware(async (auth, req) => {
  if (!isPublicRoute(req)) await auth.protect();
});

الصفحات:

sign-in/[[...sign-in]]/page.js →
sign-up/[[...sign-up]]/page.js →
dashboard/page.js → auth() + currentUser()
page.js → +

🎤

أسئلة الانترفيو

سهل

الإجابة:

✨

نصائح وحيل

🧠

استخدم Clerk Dashboard

لتفعيل مزودات تسجيل الدخول بدلاً من الكود

→

الدرس السابق

🔐 مقدمة في Clerk

الدرس التالي

🔐 تسجيل الدخول والحسابات

←

جاري التحميل...

أنشئ ملف middleware.ts في جذر المشروع (بجانب مجلد app) لحماية جميع المسارات:

bash
// middleware.ts
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';

const isPublicRoute = createRouteMatcher([
  '/',
  '/learn(.*)',
  '/sign-in(.*)',
  '/sign-up(.*)',
]);

export default clerkMiddleware(async (auth, request) => {
  if (!isPublicRoute(request)) {
    await auth.protect();
  }
});

export const config = {
  matcher: [
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    '/(api|trpc)(.*)',
  ],
};

💡 ما هو middleware؟:

الـ middleware يُنفَّذ قبل كل طلب. في هذه الحالة، يتحقق Clerk من هوية المستخدم قبل السماح بالوصول للصفحات المحمية.

🔍 المسارات العامة:

الصفحة الرئيسية (/) والمنهج (/learn) وصفحات تسجيل الدخول والتسجيل مفتوحة للجميع without authentication.