Plantilla base de Supabase

GitHub Repository

Boilerplate minimalista de suscripciones con Next.js, Supabase y Dodo Payments.

Live Demo

Explora la demo desplegada.

Descripción general

El starter de suscripciones de Supabase es una aplicación de Next.js 15 y React 19 que vende suscripciones con Dodo Payments. Supabase proporciona el inicio de sesión mediante Google OAuth y la base de datos de Postgres, mientras que Drizzle ORM define el esquema. Una Supabase Edge Function recibe los webhooks de Dodo Payments y almacena los pagos y las suscripciones, y un dashboard básico muestra el plan y las facturas de cada usuario. Si solo necesitas checkout, Customer Portal y manejadores de rutas de webhooks para una aplicación existente, usa en su lugar un adaptador de framework:

Next.js Adaptor

Express Adaptor

Requisitos previos

Antes de comenzar, necesitas:

Node.js 18 o posterior, o Bun 1.0 o posterior.
Un proyecto de Supabase. Necesitas su URL, anon key, service role key y cadena de conexión de la base de datos.
Una cuenta de Dodo Payments, para obtener una API key y un secreto de firma de webhook.
Un cliente OAuth de Google Cloud, con su Client ID y Client Secret.

Inicio rápido

Clone and Install

Clona el repositorio y, después, instala las dependencias 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 proyecto de Supabase. Los pasos posteriores usan la referencia del proyecto, el subdominio en https://[your-project-ref].supabase.co. Copia estos valores:

NEXT_PUBLIC_SUPABASE_URL, la URL del proyecto
NEXT_PUBLIC_SUPABASE_ANON_KEY, la anon key
SUPABASE_SERVICE_ROLE_KEY, la service role key
DATABASE_URL, la cadena de conexión de la base de datos

Configure Google OAuth

En Google Cloud, añade esta URI de redirección autorizada a tu cliente OAuth: https://[your-project-ref].supabase.co/auth/v1/callback. Después, en Supabase Auth, habilita el proveedor de Google con tu Client ID y Client Secret.

Configure Dodo Payments

Con el interruptor de Live Mode de la barra lateral desactivado, crea una API key en Developer → API Keys, dentro del dashboard de Dodo Payments. Mantén DODO_PAYMENTS_ENVIRONMENT establecido en test_mode mientras desarrollas.

Add the Webhook in Dodo Payments

En Developer → Webhooks, añade un endpoint con esta URL. Desplegarás la función que lo sirve en un paso posterior.

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

Selecciona los eventos de pago y suscripción que gestionará la función:

Eventos de pago: payment.succeeded, payment.failed, payment.processing y payment.cancelled
Eventos de suscripción: subscription.active, subscription.plan_changed, subscription.renewed, subscription.on_hold, subscription.cancelled, subscription.expired y subscription.failed

Copia el secreto de firma del endpoint. Es el valor de DODO_WEBHOOK_SECRET.

Create .env.local

Crea un archivo .env.local en el directorio raíz:

# 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

La aplicación de Next.js lee todas las variables de este archivo excepto DODO_WEBHOOK_SECRET. La Edge Function lee DODO_WEBHOOK_SECRET de los secretos de Supabase, que configuras al desplegarla.

No subas secretos al repositorio. En entornos desplegados, configúralos como variables de entorno.

Provision the Database Schema

Envía el esquema de Drizzle a tu base de datos de Supabase:

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

Tablas creadas: users, subscriptions, payments.

Deploy the Webhook Function

Inicia sesión en Supabase, guarda el secreto de firma como secreto de la función y despliega la Edge Function dodo-webhook. Sustituye [your-project-ref] por la referencia de tu proyecto:

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

El script deploy:webhook ejecuta supabase functions deploy dodo-webhook --no-verify-jwt, para que Dodo Payments pueda llamar a la función sin un token de autenticación de Supabase. Supabase proporciona SUPABASE_URL y SUPABASE_SERVICE_ROLE_KEY a la función de forma predeterminada.Para comprobar el despliegue, envía una solicitud sin firma:

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 respuesta 400 con Invalid webhook signature significa que la función está en ejecución y tiene su secreto. Una respuesta 500 con Server configuration error significa que DODO_WEBHOOK_SECRET no está configurado. Para enviar un evento de prueba firmado, abre el endpoint en Developer → Webhooks y usa su pestaña Testing.

Create Products and Features

En Products, dentro del dashboard de Dodo Payments, haz clic en Add Product para crear un producto de suscripción para cada plan. Opcionalmente, para mostrar las características del plan en la aplicación, añade una entrada de metadata con la clave features y un array JSON de strings como valor. La metadata del producto se verá así:

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

Los valores de metadata son strings, números o booleanos, así que debes almacenar el array como un string JSON. La interfaz de precios analiza el valor features y muestra cada elemento.

Run the Dev Server

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

Abre http://localhost:3000 e inicia sesión con Google.

Ahora tienes un SaaS de suscripciones funcional creado con Supabase y Dodo Payments. Para confirmarlo de principio a fin, suscríbete a un plan con una tarjeta de prueba. Cuando llegue el webhook, el dashboard mostrará tu nuevo plan.

Qué incluye

Autenticación mediante Supabase, con Google OAuth configurado
Checkout de suscripciones mediante Dodo Payments
Una Supabase Edge Function para webhooks (dodo-webhook)
Un esquema de Drizzle ORM, con los scripts db:generate y db:migrate para las migraciones
Un dashboard con facturas, estado de la suscripción y características del plan
Server actions para cambiar de plan, cancelar una suscripción y restaurar una suscripción cancelada

Mantén DODO_PAYMENTS_ENVIRONMENT establecido en test_mode hasta completar las pruebas de principio a fin. Para pasar a producción, establécelo en live_mode y utiliza una API key de live mode.

Archivos y rutas principales

El manejador de webhooks, las rutas de la aplicación y el esquema de la base de datos se encuentran en estos archivos:

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

Variables de entorno

La aplicación de Next.js y la Edge Function leen estas variables:

Supabase

NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=
DATABASE_URL=

.env.example no incluye SUPABASE_SERVICE_ROLE_KEY, pero el cliente de administración de la aplicación en lib/supabase/admin.ts lo necesita. Añádelo manualmente.

Dodo Payments

DODO_PAYMENTS_API_KEY=
DODO_WEBHOOK_SECRET=
DODO_PAYMENTS_ENVIRONMENT=test_mode|live_mode

Google OAuth

La aplicación no lee las credenciales de Google desde las variables de entorno. Introduce el Client ID y el Client Secret en la configuración del proveedor de Google de Supabase Auth y añade esta URI de redirección al cliente OAuth en Google Cloud:

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

Verificación y solución de problemas

Webhook signature invalid (400)

Asegúrate de que el secreto DODO_WEBHOOK_SECRET de la función coincida con el secreto de firma del endpoint en el dashboard de Dodo Payments.
Confirma que implementaste la función dodo-webhook más reciente.
La función verifica los encabezados de Standard Webhooks webhook-id, webhook-signature y webhook-timestamp. Asegúrate de que un proxy no los elimine.

Database push fails

Comprueba la sintaxis de DATABASE_URL.
La conexión directa (db.[project-ref].supabase.co:5432) usa IPv6, a menos que tu proyecto tenga el complemento de IPv4. En una red que solo admite IPv4, usa la cadena de conexión del session pooler en su lugar (documentación de conexión de Supabase).
Espera entre 2 y 3 minutos después de crear el proyecto antes del primer push.

OAuth redirect mismatch

El URI de redirección debe ser https://[ref].supabase.co/auth/v1/callback.
Usa el mismo URI en Google Cloud y en el proveedor de Supabase Auth.

Para consultar el repositorio original y los pasos detallados, visita dodo-supabase-subscription-starter.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

GitHub Repository

Live Demo

Descripción general

Next.js Adaptor

Express Adaptor

Requisitos previos

Inicio rápido

Qué incluye

Archivos y rutas principales

Variables de entorno

Verificación y solución de problemas

GitHub Repository

Live Demo

​Descripción general

Next.js Adaptor

Express Adaptor

​Requisitos previos

​Inicio rápido

​Qué incluye

​Archivos y rutas principales

​Variables de entorno

​Verificación y solución de problemas

Descripción general

Requisitos previos

Inicio rápido

Qué incluye

Archivos y rutas principales

Variables de entorno

Verificación y solución de problemas