إعداد Clerk

# إعداد Clerk

استخدم [Clerk CLI](https://clerk.com/docs/cli) لإضافة المصادقة. في بيئات الوكيل، تعد الأطر المدعومة افتراضيا إعدادا بدون حساب: `npx -y clerk@latest init` يوفر تطبيقا قابلا للمطالبة ويكتب مفاتيح تطوير مؤقتة دون الحاجة إلى حساب Clerk.

## قبل أن تبدأ

اعرض على المستخدم قائمة التحقق هذه وانتظر موافقته:

``` إليك ما سأفعله لإعدادك باستخدام Clerk.

1. إعداد Clerk في هذا المشروع، أو إنشاء تطبيق جديد إذا كان هذا الدليل فارغا. 2. تثبيت مهارات وكيل Clerk لوكلاء البرمجة على هذا الجهاز، إذا لم تكن مثبتة بعد. 3. تشغيل تطبيقك مع تثبيت Clerk.

هل أستمر؟ ```

## المصادقة الموجودة

قبل `init`، افحص تبعيات المصادقة، المسارات، البرمجيات الوسيطة (middleware)، الجلسات، وسجلات المستخدمين — لا تفحص ملفات البيئة أبدا. إذا كان هناك مزود مصادقة مختلف، توقف واطلب الموافقة على خطة ترحيل تغطي:

- استيراد مستخدمي واجهة برمجة التطبيقات الخلفية، والمعرفات الخارجية المستقرة، وتجزئة كلمات المرور المتوافقة، واستمرارية OAuth. - المسارات المحمية، والرموز المميزة، وتحويل الجلسة، واستراتيجية النشر.

لا تقم بتعديل أو إزالة المصادقة الموجودة دون موافقة.

راجع [دليل الترحيل](https://clerk.com/docs/guides/development/migrating/overview).

## مشاريع Clerk الموجودة

إذا كان المشروع يستخدم Clerk بالفعل، فتخط `init` في الخطوتين 1أ و 1ب: قد يؤدي تشغيل وكيل غير مسجل الدخول إلى إنشاء تطبيق آخر واستبدال مفاتيح Clerk للمشروع. إذا كان Clerk يعمل بالفعل وطلب المستخدم الإعداد، فأبلغ بأنه لا يلزم أي إعداد. إذا أبلغ المستخدم عن مفاتيح مفقودة، فاستعدها من فرع التطبيق الحالي أدناه. إذا وجد الفحص مزودا أو برمجيات وسيطة أو مسارات مصادقة مفقودة، فأضف هذه الأجزاء فقط من البدء السريع المطابق في الخطوة 2. لا تنشئ تطبيقا بديلا أبدا.

افحص إصدارات حزمة Clerk قبل تغيير أي شيء واستخدم جدول الإصدارات في [مهارة Clerk](https://clerk.com/.well-known/skills/clerk/SKILL.md) لتحديد جيل SDK الخاص بها. حافظ على هذا الجيل ما لم يطلب المستخدم ترقيته، وطبق هذه الاختلافات في كل خطوة أدناه لمشاريع Core 2:

- يستخدم React و Expo `@clerk/clerk-react` و `@clerk/clerk-expo` بدلا من `@clerk/react` و `@clerk/expo`. - مكونات التحكم هي `<SignedIn>` و `<SignedOut>` بدلا من `<Show>`. - يمكن ل `ClerkProvider` في Next.js أن يغلف `<html>` بدلا من أن يكون داخل `<body>`. - الحد الأدنى لإصدار Node.js هو 18.17.0 بدلا من 20.9.0. - تأتي السمات من `@clerk/themes` و `@clerk/themes/shadcn.css` بدلا من `@clerk/ui`.

## استخدام تطبيق Clerk موجود (اختياري)

اتبع هذا الفرع عندما يطلب المستخدم استخدام تطبيق Clerk موجود أو عندما يحتاج مشروع Clerk موجود إلى استعادة مفاتيحه. اطلب منهم المصادقة من محطة المضيف الخاصة بهم قبل استهداف موارد على مستوى الحساب:

```bash npx -y clerk@latest auth login ```

إذا قاموا بتوفير معرف تطبيق، فاحتفظ به ل `init` أو `link` حسب الاقتضاء. وإلا، ادرج التطبيقات:

```bash npx -y clerk@latest apps list --json ```

اعرض الأسماء والمعرفات واسأل عن التطبيق الذي سيتم استخدامه. لا تختر تطبيقا لهم أبدا. لتكامل Clerk جديد، مرر المعرف المحدد ك `--app <application_id>` إلى `init`. لمشروع يستخدم Clerk بالفعل، لا تقم بتشغيل `init`. إذا لم يكن مرتبطا بالفعل بالتطبيق المحدد، فاربطه:

```bash npx -y clerk@latest link --app <application_id> ```

بالنسبة لمفاتيح التطوير المفقودة، اسحبها:

```bash npx -y clerk@latest env pull ```

فقط عندما يحتاج المستخدم إلى مفاتيح الإنتاج، استخدم `npx -y clerk@latest env pull --instance prod` بدلا من ذلك. لا تستبدل المفاتيح العاملة أو تبدل التطبيقات دون تأكيد المستخدم.

## الخطوة 1أ: مشروع موجود بدون Clerk

لمشروع لا يستخدم Clerk بالفعل، قم بالتشغيل من جذر المشروع:

```bash npx -y clerk@latest init ```

يكتشف `init` الإطار ومدير الحزم، ويثبت SDK، ويقوم بتكوين المزود، والبرمجيات الوسيطة، ومسارات المصادقة، والبيئة. كما يقوم بتثبيت مهارات وكيل Clerk عالميا. إذا رفضها المستخدم، أو كانت متاحة لك بالفعل، كما هو الحال عندما قمت بتحميل هذا كمهارة `clerk-setup`، فأضف `--no-skills` لتخطي هذه الخطوة. لا تمرر `--framework` أو `--pm` إلا إذا طلب منك ذلك. أضف `--app <application_id>` فقط عندما يختار المستخدم تطبيقا في الفرع الاختياري أعلاه.

## الخطوة 1ب: دليل فارغ

اسأل عن الإطار ومدير الحزم الذي سيتم استخدامه، مع الافتراض الافتراضي ل Next.js و npm:

```bash npx -y clerk@latest init --framework <framework> --pm <package-manager> ```

ينشئ `init` التطبيق في دليل فرعي جديد، مثل `my-clerk-next-app`، وليس في الدليل الحالي. قم بتشغيل الخطوات المتبقية من هذا الدليل الفرعي. كما في الخطوة 1أ، أضف `--no-skills` إذا كانت مهارات Clerk متاحة لك بالفعل أو رفضها المستخدم.

يمكن ل `init` إنشاء تطبيقات Next.js، React Router، Astro، Nuxt، TanStack Start، React، Vue، JavaScript/Vite، و Expo. بالنسبة ل Express، Fastify، iOS، أو Android، أنشئ المشروع باستخدام أدوات تلك المنصة أولا، ثم اتبع الخطوة 1أ.

## الخطوة 1ج: مفاتيح تطوير بدون حساب