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

# Next.js Minimal Boilerplate

> Comece rapidamente com nosso boilerplate mínimo do Next.js para integrar os Dodo Payments em sua aplicação Next.js

## Visão Geral

O boilerplate mínimo do Next.js fornece um ponto de partida pronto para uso para integrar os Dodo Payments com sua aplicação Next.js. Este template inclui sessões de checkout, manipulação de webhook, portal do cliente e componentes de UI modernos para ajudá-lo a começar a aceitar pagamentos rapidamente.

<Info>
  Este boilerplate usa o Next.js 16 App Router com TypeScript, Tailwind CSS 4 e o adaptador `@dodopayments/nextjs`.
</Info>

### Recursos

* **Configuração Rápida** - Comece em menos de 5 minutos
* **Integração de Pagamentos** - Fluxo de checkout pré-configurado usando `@dodopayments/nextjs`
* **UI Moderna** - Página de preços limpa com tema escuro usando Tailwind CSS
* **Handler de Webhook** - Endpoint de webhook pronto para eventos de pagamento
* **Portal do Cliente** - Gerenciamento de assinatura com um clique
* **TypeScript** - Totalmente tipado com tipos mínimos e focados
* **Checkout Pré-preenchido** - Demonstra como passar dados do cliente para melhorar a UX

## Pré-requisitos

Antes de começar, certifique-se de que você tem:

* **Node.js 20.9+** (requerido para Next.js 16)
* **Conta Dodo Payments** (para acessar as chaves da API e do Webhook no painel)

## Início Rápido

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate.git
    cd dodo-nextjs-minimal-boilerplate
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Get API Credentials">
    Cadastre-se na [Dodo Payments](https://dodopayments.com/) e obtenha suas credenciais no dashboard:

    * **Chave da API:** [Painel → Desenvolvedor → Chaves da API](https://app.dodopayments.com/developer/api-keys)
    * **Chave do Webhook:** [Painel → Desenvolvedor → Webhooks](https://app.dodopayments.com/developer/webhooks)

    <Tip>
      Certifique-se de estar em **Modo de Teste** durante o desenvolvimento!
    </Tip>
  </Step>

  <Step title="Configure Environment Variables">
    Crie um arquivo `.env` no diretório raiz:

    ```bash theme={null}
    cp .env.example .env
    ```

    Atualize os valores com suas credenciais do Dodo Payments:

    ```env theme={null}
    DODO_PAYMENTS_API_KEY=your_api_key_here
    DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
    DODO_PAYMENTS_RETURN_URL=http://localhost:3000
    DODO_PAYMENTS_ENVIRONMENT=test_mode
    ```

    <Warning>
      Nunca faça commit do seu arquivo `.env` no controle de versão. Ele já está incluído no `.gitignore`.
    </Warning>
  </Step>

  <Step title="Add Your Products">
    Atualize `src/lib/products.ts` com seus IDs de produto reais do Dodo Payments:

    ```typescript theme={null}
    export const products: Product[] = [
      {
        product_id: "pdt_001", // Replace with your product ID
        name: "Basic Plan",
        description: "Get access to basic features and support",
        price: 9999, // in cents
        features: [
          "Access to basic features",
          "Email support",
          "1 Team member",
          "Basic analytics",
        ],
      },
      // ... add more products
    ];
    ```
  </Step>

  <Step title="Run the Development Server">
    ```bash theme={null}
    npm run dev
    ```

    Abra [http://localhost:3000](http://localhost:3000) para ver sua página de preços!
  </Step>
</Steps>

## Estrutura do Projeto

```text theme={null}
src/
├── app/
│   ├── api/
│   │   ├── checkout/          # Checkout session handler
│   │   ├── customer-portal/   # Customer portal redirect
│   │   └── webhook/           # Webhook event handler
│   ├── components/
│   │   ├── Footer.tsx         # Reusable footer
│   │   ├── Header.tsx         # Navigation header
│   │   └── ProductCard.tsx    # Product pricing card
│   ├── globals.css            # Global styles
│   ├── layout.tsx             # Root layout
│   └── page.tsx               # Pricing page (home)
└── lib/
    └── products.ts            # Product definitions
```

## Personalização

### Atualizar Informações do Produto

Edite `src/lib/products.ts` para modificar:

* IDs de produto (do seu dashboard Dodo)
* Preços
* Recursos
* Descrições

### Pré-preencher Dados do Cliente

No `src/app/components/ProductCard.tsx`, substitua os valores fixos pelos dados reais do seu usuário:

```typescript theme={null}
customer: {
  name: "John Doe",
  email: "john@example.com",
},
```

### Atualizar Portal do Cliente

No `src/app/components/Header.tsx`, substitua o ID de cliente fixo:

```typescript theme={null}
const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID
```

Você pode completar uma compra de teste para obter o ID do cliente para testes.

## Eventos de Webhook

O boilerplate demonstra o tratamento de dois eventos de webhook em `src/app/api/webhook/route.ts`:

* `onSubscriptionActive` - Acionado quando uma assinatura fica ativa
* `onPaymentSucceeded` - Acionado quando um pagamento é bem-sucedido

Adicione sua lógica de negócios dentro desses manipuladores:

```typescript theme={null}
onSubscriptionActive: async (payload) => {
  // Grant access to your product
  // Update user database
  // Send welcome email
},
```

Adicione mais eventos de webhook conforme necessário.

Para desenvolvimento local, você pode usar ferramentas como [ngrok](https://ngrok.com/) para criar um túnel seguro para seu servidor local e usá-lo como sua URL de webhook.

## Implantação

### Compilar para Produção

```bash theme={null}
npm run build
npm start
```

### Implantar no Vercel

\[

![Implantar com Vercel](https://vercel.com/button)

]\([https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate))

Não se esqueça de adicionar suas variáveis de ambiente no painel do Vercel!

### Atualizar URL do Webhook

Após a implantação, atualize sua URL de webhook no [Painel do Dodo Payments](https://app.dodopayments.com/developer/webhooks):

```
https://example.com/api/webhook
```

## Solução de Problemas

<AccordionGroup>
  <Accordion title="Module not found or build errors">
    Exclua `node_modules` e reinstale as dependências:

    ```bash theme={null}
    rm -rf node_modules package-lock.json
    npm install
    ```
  </Accordion>

  <Accordion title="Checkout redirect fails">
    **Causas comuns:**

    * ID de produto inválido - verifique se ele existe no seu dashboard Dodo
    * Chave de API ou configuração de ambiente incorreta em `.env`
    * Verifique o console do navegador e o terminal para erros
  </Accordion>

  <Accordion title="Webhooks not receiving events">
    Para testes locais, use [ngrok](https://ngrok.com) para expor seu servidor:

    ```bash theme={null}
    ngrok http 3000
    ```

    Atualize a URL do webhook no seu [dashboard Dodo](https://app.dodopayments.com/developer/webhooks) para a URL do ngrok. Lembre-se de atualizar seu arquivo .env com a chave de verificação correta do webhook.
  </Accordion>

  <Accordion title="Customer portal link doesn't work">
    Substitua o `CUSTOMER_ID` fixo em `src/app/components/Header.tsx` por um ID de cliente real do seu dashboard Dodo.

    Ou integre seu sistema de autenticação e banco de dados para buscar o ID do cliente dinamicamente.
  </Accordion>
</AccordionGroup>

## Saiba Mais

* [Documentação do Dodo Payments](https://docs.dodopayments.com/)
* [Documentação de Sessões de Checkout](https://docs.dodopayments.com/developer-resources/checkout-session)
* [Documentação de Webhooks](https://docs.dodopayments.com/developer-resources/webhooks)

## Suporte

Precisa de ajuda com o boilerplate?

* Junte-se à nossa [comunidade no Discord](https://discord.gg/bYqAp4ayYh) para perguntas e discussões
* Verifique o [repositório do GitHub](https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate) para problemas e atualizações
* Entre em contato com nossa [equipe de suporte](mailto:support@dodopayments.com) para assistência