> ## 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.

# 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á.

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodo-supabase-subscription-starter">
    Boilerplate subscription tối giản cho Next.js + Supabase + Dodo Payments
  </Card>

  <Card title="Live Demo" icon="rocket" href="https://dodopayments-supabase-nextjs.vercel.app">
    Khám phá bản demo đã triển khai
  </Card>
</CardGroup>

## 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.

<Info>
  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: <a href="/developer-resources/nextjs-adaptor">Adaptor Next.js</a> và <a href="/developer-resources/express-adaptor">Adaptor Express</a>.
</Info>

## Đ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

<Steps>
  <Step title="Clone and install">
    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="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)
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Create .env.local">
    ```env theme={null}
    # 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
    ```

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

  <Step title="Provision database schema">
    ```bash theme={null}
    bun run db:push
    # or
    npm run db:push
    # or
    pnpm run db:push
    ```

    <Check>
      Các bảng được tạo: `users`, `subscriptions`, `payments`.
    </Check>
  </Step>

  <Step title="Deploy webhook function">
    ```bash theme={null}
    # 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]
    ```

    ```bash cURL theme={null}
    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":{}}'
    ```
  </Step>

  <Step title="Add webhook in Dodo Payments">
    Đặt endpoint URL thành:

    ```text theme={null}
    https://[your-project-ref].supabase.co/functions/v1/dodo-webhook
    ```

    Chọn các sự kiện payment và subscription.
  </Step>

  <Step title="Create products and features">
    Trong dashboard Dodo → Products → Create Product. Bạn có thể thêm metadata:

    ```json theme={null}
    {
      "features": ["Feature 1", "Feature 2", "Feature 3"]
    }
    ```

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

  <Step title="Run the dev server">
    ```bash theme={null}
    bun run dev
    # or
    npm run dev
    # or
    pnpm run dev
    ```

    Mở [http://localhost:3000](http://localhost:3000).
  </Step>
</Steps>

## 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

<Tip>
  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.
</Tip>

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

<Tabs>
  <Tab title="Edge Function">
    ```text theme={null}
    supabase/functions/dodo-webhook/
      index.ts            # webhook handler verifying signatures
      deno.json           # permissions
    ```
  </Tab>

  <Tab title="Next.js routes">
    ```text theme={null}
    app/(marketing)/*     # landing + pricing UI
    app/(dashboard)/*     # protected pages
    app/api/*             # server actions & helpers
    ```
  </Tab>

  <Tab title="Database (Drizzle)">
    ```text theme={null}
    lib/db/schema.ts      # users, subscriptions, payments
    lib/db/index.ts       # client
    ```
  </Tab>
</Tabs>

## Environment variables

<AccordionGroup>
  <Accordion title="Supabase">
    ```env theme={null}
    NEXT_PUBLIC_SUPABASE_URL=
    NEXT_PUBLIC_SUPABASE_ANON_KEY=
    SUPABASE_SERVICE_ROLE_KEY=
    DATABASE_URL=
    ```
  </Accordion>

  <Accordion title="Dodo Payments">
    ```env theme={null}
    DODO_PAYMENTS_API_KEY=
    DODO_WEBHOOK_SECRET=
    DODO_PAYMENTS_ENVIRONMENT=test_mode|live_mode
    ```
  </Accordion>

  <Accordion title="Google OAuth">
    ```env theme={null}
    GOOGLE_CLIENT_ID=
    GOOGLE_CLIENT_SECRET=
    ```
  </Accordion>
</AccordionGroup>

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

<AccordionGroup>
  <Accordion title="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)
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

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

<Info>
  Repository gốc và các bước chi tiết: <a href="https://github.com/dodopayments/dodo-supabase-subscription-starter">dodo-supabase-subscription-starter</a>.
</Info>