Supabase Boilerplate

GitHub Repository

Minimal Next.js, Supabase, and Dodo Payments subscription boilerplate.

Live Demo

Explore the deployed demo.

Overview

The Supabase subscription starter is a Next.js 15 and React 19 app that sells subscriptions with Dodo Payments. Supabase provides Google OAuth sign-in and the Postgres database, and Drizzle ORM defines the schema. A Supabase Edge Function receives Dodo Payments webhooks and stores payments and subscriptions, and a basic dashboard shows each user’s plan and invoices. If you need only checkout, Customer Portal, and webhook route handlers for an existing app, use a framework adaptor instead:

Next.js Adaptor

Express Adaptor

Prerequisites

Before you begin, you need:

Node.js 18 or later, or Bun 1.0 or later.
A Supabase project. You need its URL, anon key, service role key, and database connection string.
A Dodo Payments account, for an API key and a webhook signing secret.
A Google Cloud OAuth client, for its Client ID and Client Secret.

Quickstart

Clone and Install

Clone the repository, then install dependencies with Bun, npm, or 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

Create a Supabase project. Later steps use its project reference, the subdomain in https://[your-project-ref].supabase.co. Copy these values:

NEXT_PUBLIC_SUPABASE_URL, the project URL
NEXT_PUBLIC_SUPABASE_ANON_KEY, the anon key
SUPABASE_SERVICE_ROLE_KEY, the service role key
DATABASE_URL, the database connection string

Configure Google OAuth

In Google Cloud, add this authorized redirect URI to your OAuth client: https://[your-project-ref].supabase.co/auth/v1/callback. Then, in Supabase Auth, enable the Google provider with your Client ID and Client Secret.

Configure Dodo Payments

With the Live Mode switch in the sidebar off, create an API key under Developer → API Keys in the Dodo Payments dashboard. Keep DODO_PAYMENTS_ENVIRONMENT set to test_mode while you develop.

Add the Webhook in Dodo Payments

Under Developer → Webhooks, add an endpoint with this URL. You deploy the function that serves it in a later step.

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

Select the payment and subscription events that the function handles:

Payment events: payment.succeeded, payment.failed, payment.processing, and payment.cancelled
Subscription events: subscription.active, subscription.plan_changed, subscription.renewed, subscription.on_hold, subscription.cancelled, subscription.expired, and subscription.failed

Copy the endpoint’s signing secret. It’s the value of DODO_WEBHOOK_SECRET.

Create .env.local

Create a .env.local file in the root directory:

# 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

The Next.js app reads every variable in this file except DODO_WEBHOOK_SECRET. The Edge Function reads DODO_WEBHOOK_SECRET from its Supabase secrets, which you set when you deploy it.

Don’t commit secrets. In deployed environments, set them as environment variables.

Provision the Database Schema

Push the Drizzle schema to your Supabase database:

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

Tables created: users, subscriptions, payments.

Deploy the Webhook Function

Log in to Supabase, store the signing secret as a function secret, and deploy the dodo-webhook Edge Function. Replace [your-project-ref] with your project reference:

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

The deploy:webhook script runs supabase functions deploy dodo-webhook --no-verify-jwt, so Dodo Payments can call the function without a Supabase auth token. Supabase provides SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY to the function by default.To check the deployment, send an unsigned request:

cURL

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

A 400 response with Invalid webhook signature means the function is running and has its secret. A 500 response with Server configuration error means DODO_WEBHOOK_SECRET isn’t set. To send a signed test event, open the endpoint in Developer → Webhooks and use its Testing tab.

Create Products and Features

Under Products in the Dodo Payments dashboard, click Add Product to create a subscription product for each plan. Optionally, to list plan features in the app, add a metadata entry with the key features and a JSON array of strings as its value. The product’s metadata then looks like this:

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

Metadata values are strings, numbers, or booleans, so store the array as a JSON string. The pricing UI parses the features value and renders each item.

Run the Dev Server

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

Open http://localhost:3000 and sign in with Google.

You now have a working subscription SaaS scaffolded with Supabase and Dodo Payments. To confirm it end to end, subscribe to a plan with a test card. After the webhook arrives, the dashboard shows your new plan.

What’s Included

Authentication through Supabase, with Google OAuth configured
Subscription checkout through Dodo Payments
A Supabase Edge Function for webhooks (dodo-webhook)
A Drizzle ORM schema, with db:generate and db:migrate scripts for migrations
A dashboard with invoices, subscription status, and plan features
Server actions to change plans, cancel a subscription, and restore a cancelled subscription

Keep DODO_PAYMENTS_ENVIRONMENT set to test_mode until you complete end-to-end tests. To go live, set it to live_mode and use a live mode API key.

Key Files and Paths

The webhook handler, app routes, and database schema live in these files:

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

Environment Variables

The Next.js app and the Edge Function read these variables:

Supabase

NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=
DATABASE_URL=

.env.example doesn’t list SUPABASE_SERVICE_ROLE_KEY, but the app’s admin client in lib/supabase/admin.ts needs it. Add it yourself.

Dodo Payments

DODO_PAYMENTS_API_KEY=
DODO_WEBHOOK_SECRET=
DODO_PAYMENTS_ENVIRONMENT=test_mode|live_mode

Google OAuth

The app doesn’t read Google credentials from environment variables. Enter the Client ID and Client Secret in the Google provider settings of Supabase Auth, and add this redirect URI to the OAuth client in Google Cloud:

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

Verification and Troubleshooting

Webhook signature invalid (400)

Make sure the function’s DODO_WEBHOOK_SECRET secret matches the endpoint’s signing secret in the Dodo Payments dashboard.
Confirm you deployed the latest dodo-webhook function.
The function verifies the Standard Webhooks headers webhook-id, webhook-signature, and webhook-timestamp. Make sure a proxy doesn’t strip them.

Database push fails

Check the DATABASE_URL syntax.
The direct connection (db.[project-ref].supabase.co:5432) uses IPv6 unless your project has the IPv4 add-on. On an IPv4-only network, use the session pooler connection string instead (Supabase connection docs).
Wait 2–3 minutes after you create the project before the first push.

OAuth redirect mismatch

The redirect URI must be https://[ref].supabase.co/auth/v1/callback.
Use the same URI in Google Cloud and in the Supabase Auth provider.

For the original repository and detailed steps, see dodo-supabase-subscription-starter.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

GitHub Repository

Live Demo

Overview

Next.js Adaptor

Express Adaptor

Prerequisites

Quickstart

What’s Included

Key Files and Paths

Environment Variables

Verification and Troubleshooting

GitHub Repository

Live Demo

​Overview

Next.js Adaptor

Express Adaptor

​Prerequisites

​Quickstart

​What’s Included

​Key Files and Paths

​Environment Variables

​Verification and Troubleshooting

Overview

Prerequisites

Quickstart

What’s Included

Key Files and Paths

Environment Variables

Verification and Troubleshooting