> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Next.js Minimal Boilerplate

> ابدأ بسرعة مع نموذج Next.js البسيط لدينا لدمج مدفوعات دودي في تطبيق Next.js الخاص بك

## نظرة عامة

يوفر نموذج Next.js البسيط نقطة انطلاق جاهزة للاستخدام لدمج مدفوعات دودي مع تطبيق Next.js الخاص بك. يتضمن هذا القالب جلسات الدفع، ومعالجة الويب هوك، وبوابة العملاء، ومكونات واجهة مستخدم حديثة لمساعدتك في البدء في قبول المدفوعات بسرعة.

<Info>
  هذا القالب يستخدم Next.js 16 App Router مع TypeScript وTailwind CSS 4، وواجهة الـ `@dodopayments/nextjs`.
</Info>

### الميزات

* **إعداد سريع** - ابدأ في أقل من 5 دقائق
* **تكامل الدفع** - تجربة دفع معدة مسبقًا باستخدام `@dodopayments/nextjs`
* **واجهة حديثة** - صفحة أسعار نظيفة بخلفية داكنة باستخدام Tailwind CSS
* **معالج الويب هوك** - نقطة نهاية جاهزة لأحداث الدفع
* **بوابة العملاء** - إدارة الاشتراكات بنقرة واحدة
* **TypeScript** - مكتوب بالكامل بأنواع قليلة ومركزة
* **عملية دفع مسبقة التعبئة** - توضح تمرير بيانات العملاء لتحسين تجربة المستخدم

## المتطلبات المسبقة

قبل أن تبدأ، تأكد من أن لديك:

* **Node.js 20.9+** (مطلوب لـ Next.js 16)
* **حساب مدفوعات دودي** (للوصول إلى مفاتيح API وWebhook من لوحة التحكم)

## بدء سريع

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate.git
    cd dodo-nextjs-minimal-boilerplate
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Get API Credentials">
    سجّل في [Dodo Payments](https://dodopayments.com/) واحصل على بيانات الاعتماد من لوحة التحكم:

    * **مفتاح API:** [لوحة التحكم → المطور → مفاتيح API](https://app.dodopayments.com/developer/api-keys)
    * **مفتاح ويب هوك:** [لوحة التحكم → المطور → ويب هوكس](https://app.dodopayments.com/developer/webhooks)

    <Tip>
      تأكد من أنك في **وضع الاختبار** أثناء التطوير!
    </Tip>
  </Step>

  <Step title="Configure Environment Variables">
    أنشئ ملف `.env` في الدليل الجذري:

    ```bash theme={null}
    cp .env.example .env
    ```

    قم بتحديث القيم باستخدام بيانات اعتماد مدفوعات دودي الخاصة بك:

    ```env theme={null}
    DODO_PAYMENTS_API_KEY=your_api_key_here
    DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
    DODO_PAYMENTS_RETURN_URL=http://localhost:3000
    DODO_PAYMENTS_ENVIRONMENT=test_mode
    ```

    <Warning>
      لا تُدخِل ملف `.env` في نظام التحكم بالإصدارات. إنه مُضمَّن بالفعل في `.gitignore`.
    </Warning>
  </Step>

  <Step title="Add Your Products">
    قم بتحديث `src/lib/products.ts` ببيانات معرّفات المنتج الفعلية من Dodo Payments:

    ```typescript theme={null}
    export const products: Product[] = [
      {
        product_id: "pdt_001", // Replace with your product ID
        name: "Basic Plan",
        description: "Get access to basic features and support",
        price: 9999, // in cents
        features: [
          "Access to basic features",
          "Email support",
          "1 Team member",
          "Basic analytics",
        ],
      },
      // ... add more products
    ];
    ```
  </Step>

  <Step title="Run the Development Server">
    ```bash theme={null}
    npm run dev
    ```

    افتح [http://localhost:3000](http://localhost:3000) لعرض صفحة التسعير!
  </Step>
</Steps>

## هيكل المشروع

```text theme={null}
src/
├── app/
│   ├── api/
│   │   ├── checkout/          # Checkout session handler
│   │   ├── customer-portal/   # Customer portal redirect
│   │   └── webhook/           # Webhook event handler
│   ├── components/
│   │   ├── Footer.tsx         # Reusable footer
│   │   ├── Header.tsx         # Navigation header
│   │   └── ProductCard.tsx    # Product pricing card
│   ├── globals.css            # Global styles
│   ├── layout.tsx             # Root layout
│   └── page.tsx               # Pricing page (home)
└── lib/
    └── products.ts            # Product definitions
```

## التخصيص

### تحديث معلومات المنتج

حرر `src/lib/products.ts` لتعديل:

* معرفات المنتجات (من لوحة تحكم Dodo الخاصة بك)
* التسعير
* الميزات
* الوصف

### ملء بيانات العملاء مسبقًا

في `src/app/components/ProductCard.tsx`، استبدل القيم الثابتة ببيانات المستخدم الفعلية:

```typescript theme={null}
customer: {
  name: "John Doe",
  email: "john@example.com",
},
```

### تحديث بوابة العملاء

في `src/app/components/Header.tsx`، استبدل معرّف العميل الثابت:

```typescript theme={null}
const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID
```

يمكنك إكمال عملية شراء تجريبية للحصول على معرف العميل للاختبار.

## أحداث الويب هوك

يُبيّن القالب كيفية التعامل مع حدثين للويب هوك في `src/app/api/webhook/route.ts`:

* `onSubscriptionActive` - يتم تفعيله عندما يُصبح الاشتراك نشطًا
* `onPaymentSucceeded` - يتم تفعيله عندما ينجح الدفع

أضف منطق عملك داخل هذه المعالجات:

```typescript theme={null}
onSubscriptionActive: async (payload) => {
  // Grant access to your product
  // Update user database
  // Send welcome email
},
```

أضف المزيد من أحداث الويب هوك حسب الحاجة.

للتطوير المحلي، يمكنك استخدام أدوات مثل [ngrok](https://ngrok.com/) لإنشاء نفق آمن إلى خادمك المحلي واستخدامه كعنوان URL للويب هوك الخاص بك.

## النشر

### بناء للإنتاج

```bash theme={null}
npm run build
npm start
```

### نشر على Vercel

\[

![نشر مع Vercel](https://vercel.com/button)

]\([https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate))

لا تنسَ إضافة متغيرات البيئة الخاصة بك في لوحة تحكم Vercel!

### تحديث عنوان URL للويب هوك

بعد النشر، قم بتحديث عنوان URL للويب هوك الخاص بك في [لوحة تحكم مدفوعات دودي](https://app.dodopayments.com/developer/webhooks):

```
https://example.com/api/webhook
```

## استكشاف الأخطاء وإصلاحها

<AccordionGroup>
  <Accordion title="Module not found or build errors">
    احذف `node_modules` وأعد تثبيت التبعيات:

    ```bash theme={null}
    rm -rf node_modules package-lock.json
    npm install
    ```
  </Accordion>

  <Accordion title="Checkout redirect fails">
    **الأسباب الشائعة:**

    * معرف المنتج غير صالح - تأكد من وجوده في لوحة تحكم Dodo الخاصة بك
    * مفتاح API أو إعداد بيئة خاطئ في `.env`
    * تحقق من وحدة تحكم المتصفح والطرفية للأخطاء
  </Accordion>

  <Accordion title="Webhooks not receiving events">
    للاختبار المحلي، استخدم [ngrok](https://ngrok.com) لكشف خادمك:

    ```bash theme={null}
    ngrok http 3000
    ```

    حدّث عنوان URL للويب هوك في [لوحة تحكم Dodo](https://app.dodopayments.com/developer/webhooks) إلى عنوان ngrok. تذكّر تحديث ملف .env بمفتاح التحقق الصحيح للويب هوك.
  </Accordion>

  <Accordion title="Customer portal link doesn't work">
    استبدل `CUSTOMER_ID` الثابت في `src/app/components/Header.tsx` بمعرّف عميل فعلي من لوحة تحكم Dodo الخاصة بك.

    أو ادمج نظام المصادقة وقاعدة البيانات لديك لاسترجاع معرّف العميل ديناميكيًا.
  </Accordion>
</AccordionGroup>

## تعرف على المزيد

* [توثيق Dodo Payments](https://docs.dodopayments.com/)
* [توثيق جلسات الدفع](https://docs.dodopayments.com/developer-resources/checkout-session)
* [توثيق Webhooks](https://docs.dodopayments.com/developer-resources/webhooks)

## الدعم

تحتاج إلى مساعدة بشأن النموذج؟

* انضم إلى [مجتمع Discord](https://discord.gg/bYqAp4ayYh) لطرح الأسئلة والمناقشات
* تحقق من [مستودع GitHub](https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate) للمشكلات والتحديثات
* اتصل بفريق [الدعم الخاص بنا](mailto:support@dodopayments.com) للحصول على المساعدة