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

> Use o starter oficial de assinaturas Next.js + Supabase + <CardGroup cols={2}> para lançar assinaturas rapidamente. Inclui autenticação, esquema de banco de dados, handler de webhook e UI de preços.

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodo-supabase-subscription-starter">
    Boilerplate mínimo de assinaturas Next.js + Supabase + Dodo Payments
  </Card>

  <Card title="Live Demo" icon="rocket" href="https://dodopayments-supabase-nextjs.vercel.app">
    Explore a demo implantada
  </Card>
</CardGroup>

## Visão geral

Um boilerplate pronto para produção para assinaturas usando Next.js 15, React 19, Supabase, Drizzle ORM e Dodo Payments. Ele inclui Google OAuth, checkout de assinaturas, tratamento de webhooks, esquema de banco de dados e um dashboard básico.

<Info>
  Se você precisa apenas de route handlers para um app existente, consulte os adaptadores dedicados: <a href="/developer-resources/nextjs-adaptor">Adaptador Next.js</a> e <a href="/developer-resources/express-adaptor">Adaptador Express</a>.
</Info>

## Pré-requisitos

* Node.js 18+ (ou Bun 1.0+)
* Projeto do Supabase (URL, chave Anon, chave de Service role, URL do banco de dados)
* Conta do Dodo Payments (chave de API, segredo do Webhook)
* Cliente OAuth do Google Cloud (Client ID e Secret)

## Início rápido

<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">
    Crie um projeto do Supabase e copie:

    * NEXT\_PUBLIC\_SUPABASE\_URL
    * NEXT\_PUBLIC\_SUPABASE\_ANON\_KEY
    * SUPABASE\_SERVICE\_ROLE\_KEY
    * DATABASE\_URL (string de conexão)
  </Step>

  <Step title="Configure Google OAuth">
    Defina o URI de redirecionamento como: `https://[your-project-ref].supabase.co/auth/v1/callback` no Google Cloud e ative o provedor Google no Supabase Auth usando seu Client ID e Secret.
  </Step>

  <Step title="Configure Dodo Payments">
    Gere uma chave de API e um segredo de Webhook no dashboard do Dodo. Defina o ambiente como `test_mode` durante o desenvolvimento.
  </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>
      Nunca faça commit de secrets. Use variáveis de ambiente nos ambientes de implantação.
    </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>
      Tabelas criadas: `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">
    Defina a URL do endpoint como:

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

    Selecione os eventos de pagamento e assinatura.
  </Step>

  <Step title="Create products and features">
    No dashboard do Dodo → Products → Create Product. Opcionalmente, adicione metadados:

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

    A UI de preços lê este array `features` e o renderiza dinamicamente.
  </Step>

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

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

## O que está incluído

* Autenticação via Supabase (Google OAuth configurado)
* Checkout de assinaturas via Dodo Payments
* Supabase Edge Function para webhooks (`dodo-webhook`)
* Esquema e migrações do Drizzle ORM
* Dashboard com faturas, status da assinatura e recursos do plano

<Tip>
  Mantenha `DODO_PAYMENTS_ENVIRONMENT` como `test_mode` até concluir os testes de ponta a ponta.
</Tip>

## Arquivos e caminhos principais

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

## Variáveis de ambiente

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

## Verificação e solução de problemas

<AccordionGroup>
  <Accordion title="Webhook signature invalid (401)">
    * Verifique se `DODO_WEBHOOK_SECRET` corresponde ao valor do dashboard do Dodo
    * Confirme se você implantou a função `dodo-webhook` mais recente
    * Verifique se o nome do header está correto na sua função (Dodo-Signature)
  </Accordion>

  <Accordion title="Database push fails">
    * Verifique a sintaxe de `DATABASE_URL` e a saída de rede do Supabase
    * Aguarde cerca de 2–3 minutos após a criação do projeto antes do primeiro push
  </Accordion>

  <Accordion title="OAuth redirect mismatch">
    * O URI de redirecionamento deve ser `https://[ref].supabase.co/auth/v1/callback`
    * Garanta o mesmo valor no Google Cloud e no provedor do Supabase Auth
  </Accordion>
</AccordionGroup>

<Check>
  Agora você tem um SaaS de assinaturas funcional, criado com Supabase e Dodo Payments.
</Check>

<Info>
  Repositório original e etapas detalhadas: <a href="https://github.com/dodopayments/dodo-supabase-subscription-starter">dodo-supabase-subscription-starter</a>.
</Info>