Boilerplate Supabase

Sử dụng starter subscription chính thức cho Next.js + Supabase + Dodo Payments để triển khai subscription nhanh chóng. Bao gồm xác thực, database schema, webhook handler và giao diện định giá.

GitHub Repository

Boilerplate subscription tối giản cho Next.js + Supabase + Dodo Payments

Live Demo

Khám phá bản demo đã triển khai

​

Tổng quan

Boilerplate sẵn sàng cho môi trường production để triển khai subscription, sử dụng Next.js 15, React 19, Supabase, Drizzle ORM và Dodo Payments. Gói này bao gồm Google OAuth, checkout subscription, xử lý webhook, database schema và dashboard cơ bản.

Nếu bạn chỉ cần route handler cho một ứng dụng hiện có, hãy xem các adaptor chuyên dụng: Adaptor Next.js và Adaptor Express.

​

Điều kiện tiên quyết

• Node.js 18+ (hoặc Bun 1.0+)
• Project Supabase (URL, Anon key, Service role key, Database URL)
• Tài khoản Dodo Payments (API key, Webhook secret)
• OAuth client của Google Cloud (Client ID và Secret)

​

Bắt đầu nhanh

1. Clone and install

   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
   
2. Create Supabase project

   Tạo một project Supabase và sao chép:

   • NEXT_PUBLIC_SUPABASE_URL
   • NEXT_PUBLIC_SUPABASE_ANON_KEY
   • SUPABASE_SERVICE_ROLE_KEY
   • DATABASE_URL (Connection string)
3. Configure Google OAuth

   Đặt redirect URI thành: https://[your-project-ref].supabase.co/auth/v1/callback trong Google Cloud, sau đó bật Google provider trong Supabase Auth bằng Client ID và Secret của bạn.

4. Configure Dodo Payments

   Tạo API key và Webhook secret từ dashboard Dodo. Đặt environment thành test_mode trong quá trình phát triển.

5. Create .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
   

   Không bao giờ commit secret. Sử dụng environment variables trong môi trường triển khai.

6. Provision database schema

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

   Các bảng được tạo: users, subscriptions, payments.

7. Deploy webhook function

   # login (one-time)
   bunx supabase login
   # or
   npx supabase login
   
   # 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]
   

   cURL

   curl -X POST \
     'https://[your-project-ref].supabase.co/functions/v1/dodo-webhook' \
     -H 'Content-Type: application/json' \
     -H 'Dodo-Signature: <signature>' \
     -d '{"type":"payment.succeeded","data":{}}'
   
8. Add webhook in Dodo Payments

   Đặt endpoint URL thành:

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

   Chọn các sự kiện payment và subscription.

9. Create products and features

   Trong dashboard Dodo → Products → Create Product. Bạn có thể thêm metadata:

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

   Giao diện định giá đọc mảng features này và render động.

10. Run the dev server

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

    Mở http://localhost:3000.

​

Các thành phần được bao gồm

• Xác thực thông qua Supabase (đã cấu hình Google OAuth)
• Checkout subscription thông qua Dodo Payments
• Supabase Edge Function cho webhook (dodo-webhook)
• Drizzle ORM schema và migrations
• Dashboard với invoices, trạng thái subscription và các tính năng của plan

Giữ DODO_PAYMENTS_ENVIRONMENT ở trạng thái test_mode cho đến khi bạn hoàn tất các bài kiểm thử end-to-end.

​

Tệp và đường dẫn chính

Edge Function

supabase/functions/dodo-webhook/
  index.ts            # webhook handler verifying signatures
  deno.json           # permissions

Next.js routes

app/(marketing)/*     # landing + pricing UI
app/(dashboard)/*     # protected pages
app/api/*             # server actions & helpers

Database (Drizzle)

lib/db/schema.ts      # users, subscriptions, payments
lib/db/index.ts       # client

​

Environment variables

Supabase

NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=
DATABASE_URL=

Dodo Payments

DODO_PAYMENTS_API_KEY=
DODO_WEBHOOK_SECRET=
DODO_PAYMENTS_ENVIRONMENT=test_mode|live_mode

Google OAuth

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

​

Xác minh và khắc phục sự cố

Webhook signature invalid (401)

• Đảm bảo DODO_WEBHOOK_SECRET khớp với giá trị trong dashboard Dodo
• Xác nhận bạn đã triển khai function dodo-webhook mới nhất
• Xác minh tên header trong function của bạn là chính xác (Dodo-Signature)

Database push fails

• Kiểm tra cú pháp DATABASE_URL và network egress của Supabase
• Chờ khoảng 2–3 phút sau khi tạo project trước lần push đầu tiên

OAuth redirect mismatch

• Redirect URI phải là https://[ref].supabase.co/auth/v1/callback
• Đảm bảo giá trị tương tự trong Google Cloud và Supabase Auth provider

Giờ đây bạn đã có một scaffold SaaS subscription hoạt động với Supabase và Dodo Payments.

Repository gốc và các bước chi tiết: dodo-supabase-subscription-starter.