Boilerplate Supabase

GitHub Repository

Boilerplate minimale per subscription con Next.js, Supabase e Dodo Payments.

Live Demo

Esplora la demo distribuita.

Panoramica

Lo starter per subscription Supabase è un’app Next.js 15 e React 19 che vende subscription con Dodo Payments. Supabase fornisce l’accesso Google OAuth e il database Postgres, mentre Drizzle ORM definisce lo schema. Una Supabase Edge Function riceve i webhook di Dodo Payments e salva pagamenti e subscription; una dashboard di base mostra il piano e le fatture di ogni utente. Se ti servono solo checkout, Customer Portal e route handler per i webhook per un’app esistente, usa invece un adattatore per framework:

Next.js Adaptor

Express Adaptor

Prerequisiti

Prima di iniziare, ti servono:

Node.js 18 o versione successiva, oppure Bun 1.0 o versione successiva.
Un progetto Supabase. Ti servono il relativo URL, la anon key, la service role key e la stringa di connessione al database.
Un account Dodo Payments, per una API key e un webhook signing secret.
Un client OAuth Google Cloud, con il relativo Client ID e Client Secret.

Quickstart

Clone and Install

Clona il repository, quindi installa le dipendenze con Bun, npm o 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

Crea un progetto Supabase. I passaggi successivi usano il riferimento del progetto, ovvero il sottodominio in https://[your-project-ref].supabase.co. Copia questi valori:

NEXT_PUBLIC_SUPABASE_URL, l’URL del progetto
NEXT_PUBLIC_SUPABASE_ANON_KEY, la anon key
SUPABASE_SERVICE_ROLE_KEY, la service role key
DATABASE_URL, la stringa di connessione al database

Configure Google OAuth

In Google Cloud, aggiungi questo authorized redirect URI al tuo client OAuth: https://[your-project-ref].supabase.co/auth/v1/callback. Quindi, in Supabase Auth, abilita il provider Google con il tuo Client ID e Client Secret.

Configure Dodo Payments

Con l’interruttore Live Mode disattivato nella barra laterale, crea una API key in Developer → API Keys nella dashboard di Dodo Payments. Mantieni DODO_PAYMENTS_ENVIRONMENT impostato su test_mode durante lo sviluppo.

Add the Webhook in Dodo Payments

In Developer → Webhooks, aggiungi un endpoint con questo URL. Distribuirai la function che lo espone in un passaggio successivo.

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

Seleziona gli eventi di pagamento e subscription gestiti dalla function:

Eventi di pagamento: payment.succeeded, payment.failed, payment.processing e payment.cancelled
Eventi di subscription: subscription.active, subscription.plan_changed, subscription.renewed, subscription.on_hold, subscription.cancelled, subscription.expired e subscription.failed

Copia il signing secret dell’endpoint. È il valore di DODO_WEBHOOK_SECRET.

Create .env.local

Crea un file .env.local nella directory principale:

# 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

L’app Next.js legge tutte le variabili in questo file tranne DODO_WEBHOOK_SECRET. La Edge Function legge DODO_WEBHOOK_SECRET dai secrets Supabase, che imposti quando la distribuisci.

Non eseguire il commit dei secrets. Negli ambienti distribuiti, impostali come variabili d’ambiente.

Provision the Database Schema

Esegui il push dello schema Drizzle nel database Supabase:

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

Tabelle create: users, subscriptions, payments.

Deploy the Webhook Function

Accedi a Supabase, salva il signing secret come secret della function e distribuisci la Edge Function dodo-webhook. Sostituisci [your-project-ref] con il riferimento del tuo progetto:

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

Lo script deploy:webhook esegue supabase functions deploy dodo-webhook --no-verify-jwt, così Dodo Payments può chiamare la function senza un token di autenticazione Supabase. Supabase fornisce SUPABASE_URL e SUPABASE_SERVICE_ROLE_KEY alla function per impostazione predefinita.Per verificare il deployment, invia una richiesta non firmata:

cURL

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

Una risposta 400 con Invalid webhook signature indica che la function è in esecuzione e dispone del secret. Una risposta 500 con Server configuration error indica che DODO_WEBHOOK_SECRET non è impostato. Per inviare un evento di test firmato, apri l’endpoint in Developer → Webhooks e usa la scheda Testing.

Create Products and Features

In Products nella dashboard di Dodo Payments, fai clic su Add Product per creare un prodotto subscription per ogni piano. Facoltativamente, per elencare le funzionalità dei piani nell’app, aggiungi una voce di metadata con la chiave features e un array JSON di stringhe come valore. I metadata del prodotto avranno quindi questo aspetto:

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

I valori dei metadata sono stringhe, numeri o booleani, quindi salva l’array come stringa JSON. L’interfaccia di pricing analizza il valore features e visualizza ogni elemento.

Run the Dev Server

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

Apri http://localhost:3000 e accedi con Google.

Ora hai uno scaffold SaaS funzionante per le subscription, realizzato con Supabase e Dodo Payments. Per verificarlo dall’inizio alla fine, sottoscrivi un piano con una carta di test. Dopo l’arrivo del webhook, la dashboard mostra il tuo nuovo piano.

Contenuti inclusi

Autenticazione tramite Supabase, con Google OAuth configurato
Checkout delle subscription tramite Dodo Payments
Una Supabase Edge Function per i webhook (dodo-webhook)
Uno schema Drizzle ORM, con gli script db:generate e db:migrate per le migration
Una dashboard con fatture, stato della subscription e funzionalità del piano
Server action per cambiare piano, annullare una subscription e ripristinare una subscription annullata

Mantieni DODO_PAYMENTS_ENVIRONMENT impostato su test_mode fino al completamento dei test end-to-end. Per andare live, impostalo su live_mode e usa una API key in live mode.

File e percorsi principali

Il webhook handler, le route dell’app e lo schema del database si trovano in questi file:

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

Variabili d’ambiente

L’app Next.js e la Edge Function leggono queste variabili:

Supabase

NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=
DATABASE_URL=

.env.example non elenca SUPABASE_SERVICE_ROLE_KEY, ma il client admin dell’app in lib/supabase/admin.ts ne ha bisogno. Aggiungilo manualmente.

Dodo Payments

DODO_PAYMENTS_API_KEY=
DODO_WEBHOOK_SECRET=
DODO_PAYMENTS_ENVIRONMENT=test_mode|live_mode

Google OAuth

L’app non legge le credenziali Google dalle variabili d’ambiente. Inserisci il Client ID e il Client Secret nelle impostazioni del provider Google di Supabase Auth e aggiungi questo URI di reindirizzamento al client OAuth in Google Cloud:

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

Verifica e risoluzione dei problemi

Webhook signature invalid (400)

Assicurati che il secret della funzione DODO_WEBHOOK_SECRET corrisponda al signing secret dell’endpoint nella dashboard di Dodo Payments.
Conferma di aver eseguito il deploy della versione più recente della funzione dodo-webhook.
La funzione verifica gli header di Standard Webhooks webhook-id, webhook-signature e webhook-timestamp. Assicurati che un proxy non li rimuova.

Database push fails

Controlla la sintassi di DATABASE_URL.
La connessione diretta (db.[project-ref].supabase.co:5432) usa IPv6, a meno che il tuo progetto non disponga dell’add-on IPv4. Su una rete che supporta solo IPv4, usa invece la stringa di connessione del session pooler (documentazione sulle connessioni Supabase).
Attendi 2–3 minuti dopo aver creato il progetto prima di eseguire il primo push.

OAuth redirect mismatch

L’URI di reindirizzamento deve essere https://[ref].supabase.co/auth/v1/callback.
Usa lo stesso URI in Google Cloud e nel provider Supabase Auth.

Per il repository originale e i passaggi dettagliati, consulta dodo-supabase-subscription-starter.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

GitHub Repository

Live Demo

Panoramica

Next.js Adaptor

Express Adaptor

Prerequisiti

Quickstart

Contenuti inclusi

File e percorsi principali

Variabili d’ambiente

Verifica e risoluzione dei problemi

GitHub Repository

Live Demo

​Panoramica

Next.js Adaptor

Express Adaptor

​Prerequisiti

​Quickstart

​Contenuti inclusi

​File e percorsi principali

​Variabili d’ambiente

​Verifica e risoluzione dei problemi

Panoramica

Prerequisiti

Quickstart

Contenuti inclusi

File e percorsi principali

Variabili d’ambiente

Verifica e risoluzione dei problemi