Next.js Minimal Boilerplate - Dodo Payments Documentation

نظرة عامة

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

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

الميزات

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

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

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

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

بدء سريع

Clone the Repository

git clone https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate.git
cd dodo-nextjs-minimal-boilerplate

Install Dependencies

npm install

Get API Credentials

سجّل في Dodo Payments واحصل على بيانات الاعتماد من لوحة التحكم:

مفتاح API: لوحة التحكم → المطور → مفاتيح API
مفتاح ويب هوك: لوحة التحكم → المطور → ويب هوكس

تأكد من أنك في وضع الاختبار أثناء التطوير!

Configure Environment Variables

أنشئ ملف .env في الدليل الجذري:

cp .env.example .env

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

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

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

Add Your Products

قم بتحديث src/lib/products.ts ببيانات معرّفات المنتج الفعلية من Dodo Payments:

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
];

Run the Development Server

npm run dev

افتح http://localhost:3000 لعرض صفحة التسعير!

هيكل المشروع

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، استبدل القيم الثابتة ببيانات المستخدم الفعلية:

customer: {
  name: "John Doe",
  email: "john@example.com",
},

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

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

const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID

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

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

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

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

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

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

أضف المزيد من أحداث الويب هوك حسب الحاجة. للتطوير المحلي، يمكنك استخدام أدوات مثل ngrok لإنشاء نفق آمن إلى خادمك المحلي واستخدامه كعنوان URL للويب هوك الخاص بك.

النشر

بناء للإنتاج

npm run build
npm start

نشر على Vercel

[

](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate) لا تنسَ إضافة متغيرات البيئة الخاصة بك في لوحة تحكم Vercel!

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

بعد النشر، قم بتحديث عنوان URL للويب هوك الخاص بك في لوحة تحكم مدفوعات دودي:

https://example.com/api/webhook

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

Module not found or build errors

احذف node_modules وأعد تثبيت التبعيات:

rm -rf node_modules package-lock.json
npm install

Checkout redirect fails

الأسباب الشائعة:

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

Webhooks not receiving events

للاختبار المحلي، استخدم ngrok لكشف خادمك:

ngrok http 3000

حدّث عنوان URL للويب هوك في لوحة تحكم Dodo إلى عنوان ngrok. تذكّر تحديث ملف .env بمفتاح التحقق الصحيح للويب هوك.

Customer portal link doesn't work

استبدل CUSTOMER_ID الثابت في src/app/components/Header.tsx بمعرّف عميل فعلي من لوحة تحكم Dodo الخاصة بك.أو ادمج نظام المصادقة وقاعدة البيانات لديك لاسترجاع معرّف العميل ديناميكيًا.

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

الدعم

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

انضم إلى مجتمع Discord لطرح الأسئلة والمناقشات
تحقق من مستودع GitHub للمشكلات والتحديثات
اتصل بفريق الدعم الخاص بنا للحصول على المساعدة

​نظرة عامة

​الميزات

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

​بدء سريع

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

​التخصيص

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

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

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

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

​النشر

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

​نشر على Vercel

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

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

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

​الدعم

نظرة عامة

الميزات

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

بدء سريع

هيكل المشروع

التخصيص

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

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

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

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

النشر

بناء للإنتاج

نشر على Vercel

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

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

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

الدعم