كيفية إضافة المصادقة إلى تطبيق React مع Clerk في عام 2026

يعد إنشاء المصادقة من البداية أمرًا معقدًا وعرضة للأخطاء – مثل تدفقات التسجيل وإعادة تعيين كلمة المرور وتسجيل الدخول عبر وسائل التواصل الاجتماعي وإدارة الجلسة والأمان. كاتب يتعامل مع كل ذلك باستخدام مكونات React المنسدلة. يضيف هذا الدليل مصادقة كاملة إلى تطبيق React بسرعة وأمان.

لماذا استخدام كاتب؟

• مكونات واجهة المستخدم المعدة مسبقًا: مكونات تسجيل الدخول والاشتراك وملف تعريف المستخدم جاهزة للاستخدام
• تسجيل الدخول الاجتماعي المدمج في: Google وGitHub والمزيد بأقل قدر من التكوين
• يعالج الأجزاء الصلبة: الجلسات، إعادة تعيين كلمة المرور، التحقق من البريد الإلكتروني، MFA
• آمن بشكل افتراضي: يتبع أفضل الممارسات الأمنية التي لا يتعين عليك تنفيذها
• إدارة المستخدم: لوحة تحكم لعرض وإدارة المستخدمين

الإعداد

npm install @clerk/clerk-react

# Create an app at clerk.com, get your publishable key, add to .env
VITE_CLERK_PUBLISHABLE_KEY=pk_test_xxx

قم بتغليف تطبيقك باستخدام ClerkProvider

// main.jsx
import { ClerkProvider } from '@clerk/clerk-react';

const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY;

ReactDOM.createRoot(document.getElementById('root')).render(
  <ClerkProvider publishableKey={PUBLISHABLE_KEY}>
    <App />
  </ClerkProvider>
);

إضافة تسجيل الدخول والاشتراك

import {
  SignedIn, SignedOut, SignInButton, SignUpButton, UserButton
} from '@clerk/clerk-react';

function Header() {
  return (
    <header>
      <SignedOut>
        {/* Shown only when signed OUT */}
        <SignInButton />
        <SignUpButton />
      </SignedOut>

      <SignedIn>
        {/* Shown only when signed IN - includes profile/sign-out menu */}
        <UserButton />
      </SignedIn>
    </header>
  );
}

صفحات تسجيل الدخول/الاشتراك الكاملة

import { SignIn, SignUp } from '@clerk/clerk-react';

// Dedicated sign-in page with the full Clerk UI
function SignInPage() {
  return <SignIn routing="path" path="/sign-in" />;
}

function SignUpPage() {
  return <SignUp routing="path" path="/sign-up" />;
}
// These render complete, styled auth flows with social login,
// password reset, email verification - all handled for you

حماية الطرق

import { SignedIn, SignedOut, RedirectToSignIn } from '@clerk/clerk-react';

function ProtectedPage() {
  return (
    <>
      <SignedIn>
        {/* Protected content - only for signed-in users */}
        <Dashboard />
      </SignedIn>
      <SignedOut>
        {/* Redirect signed-out users to sign in */}
        <RedirectToSignIn />
      </SignedOut>
    </>
  );
}

الوصول إلى بيانات المستخدم

import { useUser, useAuth } from '@clerk/clerk-react';

function Profile() {
  const { isLoaded, isSignedIn, user } = useUser();

  if (!isLoaded) return <div>Loading...</div>;
  if (!isSignedIn) return <div>Not signed in</div>;

  return (
    <div>
      <h1>Hello, {user.firstName}!</h1>
      <p>Email: {user.primaryEmailAddress?.emailAddress}</p>
      <img src={user.imageUrl} alt="avatar" />
    </div>
  );
}

استدعاء الواجهة الخلفية الخاصة بك باستخدام رموز المصادقة

import { useAuth } from '@clerk/clerk-react';

function useApi() {
  const { getToken } = useAuth();

  const callApi = async (endpoint) => {
    const token = await getToken();   // Clerk session token
    const res = await fetch(endpoint, {
      headers: { Authorization: `Bearer ${token}` },
    });
    return res.json();
  };

  return { callApi };
}
// Your backend verifies the Clerk token to authenticate the request

التحقق من الواجهة الخلفية (Node.js)

npm install @clerk/backend

import { verifyToken } from '@clerk/backend';

async function authenticate(req, res, next) {
  const token = req.headers.authorization?.replace('Bearer ', '');
  if (!token) return res.status(401).json({ error: 'No token' });

  try {
    const payload = await verifyToken(token, {
      secretKey: process.env.CLERK_SECRET_KEY,
    });
    req.userId = payload.sub;   // Clerk user ID
    next();
  } catch {
    res.status(401).json({ error: 'Invalid token' });
  }
}

الأسئلة المتداولة

س: الكاتب مقابل مصادقة المبنى بنفسي؟
ج: يتعامل Clerk مع الأجزاء المعقدة ذات الأهمية الأمنية (الجلسات، وإعادة تعيين كلمة المرور، والتحقق من البريد الإلكتروني، وMFA، وتسجيل الدخول عبر وسائل التواصل الاجتماعي) باستخدام مكونات تم إنشاؤها مسبقًا – مما يوفر وقتًا كبيرًا ويقلل المخاطر الأمنية. يمنح إنشاء المصادقة بنفسك تحكمًا كاملاً ولكنه يتطلب تنفيذ كل هذه التدفقات وتأمينها بشكل صحيح. بالنسبة لمعظم التطبيقات، يعد Clerk (أو ما شابه) هو الخيار العملي.

س: Clerk vs NextAuth vs Supabase Auth؟
ج: يقدم Clerk أفضل مكونات واجهة المستخدم وإدارة المستخدم المُصممة مسبقًا. يعد NextAuth (Auth.js) رائعًا لـ Next.js والمرونة المستضافة ذاتيًا. تقترن Supabase Auth بواجهة Supabase الخلفية. كلها قوية – يتفوق Clerk في واجهة المستخدم وDX؛ اختر بناءً على مجموعتك وما إذا كنت تريد الراحة المستضافة أو التحكم المستضاف ذاتيًا.

س: كيف يمكنني حماية مسارات واجهة برمجة التطبيقات الخلفية؟
ج: احصل على الرمز المميز لجلسة Clerk على الواجهة الأمامية باستخدامgetToken()، وأرسله كرمز مميز لحامله، وتحقق منه على الواجهة الخلفية لديك باستخدام@clerk/backendرمز التحقق. يمنحك الرمز المميز الذي تم التحقق منه معرف المستخدم لتخويل الطلبات. هذا هو التدفق القياسي القائم على الرمز المميز.

س: هل يدعم Clerk تسجيل الدخول الاجتماعي؟
ج: نعم — Google وGitHub والعديد من مقدمي الخدمة الآخرين ذوي الحد الأدنى من التكوين. قم بتمكينها في لوحة تحكم Clerk، وتعرض مكونات تسجيل الدخول/التسجيل خيارات تسجيل الدخول عبر وسائل التواصل الاجتماعي تلقائيًا. لا حاجة إلى تنفيذ OAuth يدويًا.

س: هل الكاتب مجاني؟
ج: لدى Clerk طبقة مجانية مناسبة للعديد من التطبيقات، مع مستويات مدفوعة للاستخدام الأعلى والميزات المتقدمة. تحقق من الأسعار الحالية لعدد المستخدمين المتوقع. للبدء والتطبيقات الصغيرة والمتوسطة، غالبًا ما تكون الطبقة المجانية كافية.

الخلاصة

يجعل Clerk إضافة المصادقة إلى تطبيق React سريعًا وآمنًا من خلال التعامل مع الأجزاء المعقدة — الجلسات، وإعادة تعيين كلمة المرور، والتحقق من البريد الإلكتروني، وMFA، وتسجيل الدخول عبر وسائل التواصل الاجتماعي — باستخدام المكونات المنسدلة. سير العمل:لف تطبيقك في ClerkProvider، واستخدم مكونات SignedIn/SignedOut لإظهار واجهة المستخدم الصحيحة، وإضافة صفحات SignIn/SignUp، وحماية المسارات باستخدام SignedIn + RedirectToSignIn، والوصول إلى بيانات المستخدم باستخدام useUser، والتحقق من رموز Clerk على الواجهة الخلفية لديك. يمكنك الحصول على نظام مصادقة كامل وآمن مع واجهة مستخدم مصقولة في جزء صغير من الوقت الذي يستغرقه إنشائه بنفسك، ودون المخاطرة الأمنية المتمثلة في تنفيذ تدفقات المصادقة يدويًا. بالنسبة لمعظم تطبيقات React التي تحتاج إلى مصادقة، يتيح لك Clerk (أو موفر مصادقة مُدار مشابه) التركيز على الميزات الفعلية لتطبيقك بدلاً من إعادة اختراع المصادقة الآمنة.