قالب Supabase الجاهز

GitHub Repository

شيفرة أساسية بسيطة للاشتراكات باستخدام Next.js وSupabase وDodo Payments.

Live Demo

استكشف العرض التجريبي المنشور.

نظرة عامة

البدء الجاهز لاشتراكات Supabase هو تطبيق Next.js 15 وReact 19 يبيع الاشتراكات باستخدام Dodo Payments. يوفر Supabase تسجيل الدخول عبر Google OAuth وقاعدة بيانات Postgres، بينما يعرّف Drizzle ORM المخطط. تستقبل Supabase Edge Function خطافات الويب من Dodo Payments وتخزّن عمليات الدفع والاشتراكات، وتعرض لوحة تحكم أساسية خطة كل مستخدم وفواتيره. إذا كنت تحتاج فقط إلى معالجات مسارات checkout وCustomer Portal وخطافات الويب لتطبيق موجود، فاستخدم بدلًا من ذلك محوّلًا لإطار العمل:

Next.js Adaptor

Express Adaptor

المتطلبات الأساسية

قبل البدء، تحتاج إلى:

Node.js 18 أو إصدار أحدث، أو Bun 1.0 أو إصدار أحدث.
مشروع Supabase. تحتاج إلى عنوان URL الخاص به، وanon key، وservice role key، وسلسلة اتصال قاعدة البيانات.
حساب Dodo Payments، للحصول على API key وسر توقيع خطاف الويب.
عميل Google Cloud OAuth، للحصول على Client ID وClient Secret.

البدء السريع

Clone and Install

استنسخ المستودع، ثم ثبّت التبعيات باستخدام Bun أو npm أو pnpm:

git clone https://github.com/dodopayments/dodo-supabase-subscription-starter.git
cd dodo-supabase-subscription-starter
# choose one
bun install
# or
npm install
# or
pnpm install

Create a Supabase Project

أنشئ مشروع Supabase. تستخدم الخطوات اللاحقة مرجع المشروع الخاص به، وهو النطاق الفرعي في https://[your-project-ref].supabase.co. انسخ القيم التالية:

NEXT_PUBLIC_SUPABASE_URL، عنوان URL للمشروع
NEXT_PUBLIC_SUPABASE_ANON_KEY، مفتاح anon
SUPABASE_SERVICE_ROLE_KEY، مفتاح service role
DATABASE_URL، سلسلة اتصال قاعدة البيانات

Configure Google OAuth

في Google Cloud، أضف عنوان URI لإعادة التوجيه المصرّح به هذا إلى عميل OAuth: https://[your-project-ref].supabase.co/auth/v1/callback. بعد ذلك، في Supabase Auth، فعّل موفّر Google باستخدام Client ID وClient Secret.

Configure Dodo Payments

مع إيقاف مفتاح Live Mode في الشريط الجانبي، أنشئ API key ضمن Developer → API Keys في لوحة تحكم Dodo Payments. أبقِ DODO_PAYMENTS_ENVIRONMENT مضبوطًا على test_mode أثناء التطوير.

Add the Webhook in Dodo Payments

ضمن Developer → Webhooks، أضف نقطة نهاية باستخدام عنوان URL هذا. ستنشر الدالة التي تخدمها في خطوة لاحقة.

https://[your-project-ref].supabase.co/functions/v1/dodo-webhook

حدّد أحداث الدفع والاشتراك التي تتعامل معها الدالة:

أحداث الدفع: payment.succeeded وpayment.failed وpayment.processing وpayment.cancelled
أحداث الاشتراك: subscription.active وsubscription.plan_changed وsubscription.renewed وsubscription.on_hold وsubscription.cancelled وsubscription.expired وsubscription.failed

انسخ سر توقيع نقطة النهاية. وهو قيمة DODO_WEBHOOK_SECRET.

Create .env.local

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

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project-ref.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role

# Database
DATABASE_URL=postgresql://postgres:[password]@db.[project-ref].supabase.co:5432/postgres

# Dodo Payments
DODO_PAYMENTS_API_KEY=your-dodo-api-key
DODO_WEBHOOK_SECRET=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT=test_mode

يقرأ تطبيق Next.js كل متغير في هذا الملف باستثناء DODO_WEBHOOK_SECRET. تقرأ Edge Function المتغير DODO_WEBHOOK_SECRET من أسرار Supabase، التي تضبطها عند نشرها.

لا ترفع الأسرار إلى المستودع. في البيئات المنشورة، اضبطها كمتغيرات بيئية.

Provision the Database Schema

ادفع مخطط Drizzle إلى قاعدة بيانات Supabase:

bun run db:push
# or
npm run db:push
# or
pnpm run db:push

الجداول التي أُنشئت: users وsubscriptions وpayments.

Deploy the Webhook Function

سجّل الدخول إلى Supabase، وخزّن سر التوقيع باعتباره سرًا للدالة، وانشر Edge Function ‏dodo-webhook. استبدل [your-project-ref] بمرجع مشروعك:

# login (one-time)
bunx supabase login
# or
npx supabase login

# store the Dodo Payments signing secret for the function
npx supabase secrets set DODO_WEBHOOK_SECRET=your-webhook-secret --project-ref [your-project-ref]

# deploy the edge function
bun run deploy:webhook --project-ref [your-project-ref]
# or
npm run deploy:webhook -- --project-ref [your-project-ref]
# or
pnpm run deploy:webhook --project-ref [your-project-ref]

يشغّل البرنامج النصي deploy:webhook‏ supabase functions deploy dodo-webhook --no-verify-jwt، بحيث يمكن لـ Dodo Payments استدعاء الدالة من دون رمز مصادقة Supabase. يوفّر Supabase المتغيرين SUPABASE_URL وSUPABASE_SERVICE_ROLE_KEY للدالة تلقائيًا.للتحقق من النشر، أرسل طلبًا غير موقّع:

cURL

curl -X POST \
  'https://[your-project-ref].supabase.co/functions/v1/dodo-webhook' \
  -H 'Content-Type: application/json' \
  -d '{"type":"payment.succeeded","data":{}}'

تعني استجابة 400 مع Invalid webhook signature أن الدالة قيد التشغيل وأن سرها مضبوط. وتعني استجابة 500 مع Server configuration error أن DODO_WEBHOOK_SECRET غير مضبوط. لإرسال حدث اختبار موقّع، افتح نقطة النهاية في Developer → Webhooks واستخدم علامة التبويب Testing.

Create Products and Features

ضمن Products في لوحة تحكم Dodo Payments، انقر على Add Product لإنشاء منتج اشتراك لكل خطة. اختياريًا، لإدراج ميزات الخطة في التطبيق، أضف إدخال بيانات وصفية بالمفتاح features ومصفوفة JSON من السلاسل النصية كقيمتها. ستبدو البيانات الوصفية للمنتج كما يلي:

{
  "features": "[\"Feature 1\", \"Feature 2\", \"Feature 3\"]"
}

قيم البيانات الوصفية هي سلاسل نصية أو أرقام أو قيم منطقية، لذا خزّن المصفوفة كسلسلة JSON. تحلّل واجهة التسعير قيمة features وتعرض كل عنصر.

Run the Dev Server

bun run dev
# or
npm run dev
# or
pnpm run dev

افتح http://localhost:3000 وسجّل الدخول باستخدام Google.

أصبح لديك الآن هيكل SaaS عامل للاشتراكات، ومجهّز باستخدام Supabase وDodo Payments. للتأكد من عمله من البداية إلى النهاية، اشترك في خطة باستخدام بطاقة اختبار. بعد وصول خطاف الويب، تعرض لوحة التحكم خطتك الجديدة.

ما يتضمنه المشروع

المصادقة عبر Supabase، مع إعداد Google OAuth
checkout للاشتراكات عبر Dodo Payments
Supabase Edge Function لخطافات الويب (dodo-webhook)
مخطط Drizzle ORM، مع البرنامجين النصيين db:generate وdb:migrate لعمليات الترحيل
لوحة تحكم تتضمن الفواتير وحالة الاشتراك وميزات الخطة
إجراءات الخادم لتغيير الخطط وإلغاء الاشتراك واستعادة اشتراك ملغى

أبقِ DODO_PAYMENTS_ENVIRONMENT مضبوطًا على test_mode حتى تُكمل الاختبارات من البداية إلى النهاية. للانتقال إلى الوضع المباشر، اضبطه على live_mode واستخدم مفتاح API للوضع المباشر.

الملفات والمسارات الرئيسية

توجد معالج خطاف الويب ومسارات التطبيق ومخطط قاعدة البيانات في هذه الملفات:

Edge Function
Next.js Routes
Database (Drizzle)

supabase/functions/dodo-webhook/
  index.ts            # verifies signatures, stores payments and subscriptions
  deno.json           # Deno configuration

app/page.tsx                    # redirects to /login or /dashboard
app/login/page.tsx              # Google sign-in page
app/dashboard/page.tsx          # plans, subscription, and invoices
app/checkout/route.ts           # checkout handler
app/api/auth/callback/route.ts  # OAuth callback
actions/*                       # server actions

lib/drizzle/schema.ts   # users, subscriptions, payments
lib/drizzle/client.ts   # client

متغيرات البيئة

يقرأ تطبيق Next.js وEdge Function هذه المتغيرات:

Supabase

NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=
DATABASE_URL=

لا يسرد .env.example‏ SUPABASE_SERVICE_ROLE_KEY، لكن عميل المسؤول في التطبيق الموجود في lib/supabase/admin.ts يحتاج إليه. أضِفه بنفسك.

Dodo Payments

DODO_PAYMENTS_API_KEY=
DODO_WEBHOOK_SECRET=
DODO_PAYMENTS_ENVIRONMENT=test_mode|live_mode

Google OAuth

لا يقرأ التطبيق بيانات اعتماد Google من متغيرات البيئة. أدخل Client ID وClient Secret في إعدادات موفّر Google في Supabase Auth، وأضف عنوان URI لإعادة التوجيه هذا إلى عميل OAuth في Google Cloud:

https://[your-project-ref].supabase.co/auth/v1/callback

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

Webhook signature invalid (400)

تأكد من أن السر DODO_WEBHOOK_SECRET الخاص بالدالة يطابق سر التوقيع الخاص بنقطة النهاية في لوحة تحكم Dodo Payments.
تأكد من نشر أحدث إصدار من الدالة dodo-webhook.
تتحقق الدالة من ترويسات Standard Webhooks ‏webhook-id وwebhook-signature وwebhook-timestamp. تأكد من أن الوكيل الوسيط لا يحذفها.

Database push fails

تحقّق من صيغة DATABASE_URL.
يستخدم الاتصال المباشر (db.[project-ref].supabase.co:5432) IPv6 ما لم يتضمن مشروعك إضافة IPv4. في شبكة تعمل بنظام IPv4 فقط، استخدم سلسلة اتصال مجمّع الجلسات بدلاً من ذلك (وثائق اتصال Supabase).
انتظر من دقيقتين إلى 3 دقائق بعد إنشاء المشروع قبل أول عملية دفع.

OAuth redirect mismatch

يجب أن يكون URI لإعادة التوجيه هو https://[ref].supabase.co/auth/v1/callback.
استخدم URI نفسه في Google Cloud وفي موفّر المصادقة في Supabase.

للاطلاع على المستودع الأصلي والخطوات التفصيلية، راجع dodo-supabase-subscription-starter.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

GitHub Repository

Live Demo

نظرة عامة

Next.js Adaptor

Express Adaptor

المتطلبات الأساسية

البدء السريع

ما يتضمنه المشروع

الملفات والمسارات الرئيسية

متغيرات البيئة

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

GitHub Repository

Live Demo

​نظرة عامة

Next.js Adaptor

Express Adaptor

​المتطلبات الأساسية

​البدء السريع

​ما يتضمنه المشروع

​الملفات والمسارات الرئيسية

​متغيرات البيئة

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

نظرة عامة

المتطلبات الأساسية

البدء السريع

ما يتضمنه المشروع

الملفات والمسارات الرئيسية

متغيرات البيئة

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