Next.js Minimal Boilerplate

Visão Geral

O boilerplate mínimo do Next.js é um app inicial com o Dodo Payments já conectado. Adicione suas chaves de API e IDs de produtos para obter uma página de preços que abre o checkout, um endpoint de webhook para eventos de pagamento e um link para o Customer Portal.

Este boilerplate usa o App Router do Next.js 16 com TypeScript, Tailwind CSS 4 e o adaptador @dodopayments/nextjs. Para adicionar os mesmos route handlers a um app existente, consulte o Next.js Adaptor.

Recursos

O boilerplate inclui:

Configuração rápida: passe do clone a uma página de preços em funcionamento em cerca de cinco minutos.
Checkout: um fluxo de checkout pré-configurado criado com base no @dodopayments/nextjs.
Página de preços: uma página de preços com tema escuro, estilizada com Tailwind CSS.
Handler de webhook: um endpoint que verifica cada assinatura de webhook e executa seu código para o evento.
Customer Portal: um link no cabeçalho que abre o Customer Portal, onde os clientes gerenciam suas assinaturas.
TypeScript: definições de produtos e handlers tipados.
Checkout pré-preenchido: envia o nome e o e-mail do cliente ao checkout, para que ele não precise digitá-los novamente.

Pré-requisitos

Antes de começar, você precisa de:

Node.js 20.9 ou posterior, exigido pelo Next.js 16.
Uma conta do Dodo Payments, para criar uma chave de API e um segredo de assinatura de webhook no dashboard.

Início rápido

Clone the Repository

git clone https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate.git
cd dodo-nextjs-minimal-boilerplate

Install Dependencies

npm install

Get API Credentials

Cadastre-se no Dodo Payments e obtenha suas credenciais no dashboard:

Chave de API: crie uma chave em Dashboard → Developer → API Keys.
Chave de webhook: adicione um endpoint em Dashboard → Developer → Webhooks e copie o segredo de assinatura. A URL do endpoint deve ser pública e usar HTTPS. Para receber eventos na sua máquina, consulte Webhook Events.

Crie ambos enquanto o seletor de Live Mode na barra lateral estiver desativado. Uma chave do modo de teste funciona somente com DODO_PAYMENTS_ENVIRONMENT=test_mode, e os pagamentos no modo de teste não movimentam dinheiro real.

Configure Environment Variables

Copie o arquivo de exemplo para criar um arquivo .env no diretório raiz:

cp .env.example .env

Defina os valores com suas credenciais do Dodo Payments:

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

Os route handlers leem estas variáveis:

DODO_PAYMENTS_API_KEY autentica os handlers de checkout e Customer Portal.
DODO_PAYMENTS_WEBHOOK_KEY verifica as assinaturas de webhook.
DODO_PAYMENTS_RETURN_URL é o local para onde o checkout envia o cliente após o pagamento.
DODO_PAYMENTS_ENVIRONMENT é test_mode ou live_mode.

Não faça commit do arquivo .env no controle de versão. O .gitignore do repositório já o exclui.

Add Your Products

Substitua os produtos de exemplo em src/lib/products.ts pelos seus próprios produtos. Defina cada product_id como o ID de um produto em Products no seu dashboard:

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

A página de preços exibe name, description, price e features deste arquivo. O checkout cobra o preço definido no produto no Dodo Payments, portanto mantenha price sincronizado com ele.

Run the Development Server

npm run dev

Abra http://localhost:3000 para ver sua página de preços.

Estrutura do projeto

Os route handlers de checkout, Customer Portal e webhook ficam em src/app/api/:

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

IDs dos produtos, em Products no seu dashboard do Dodo Payments
Preços
Recursos
Descrições

Pré-preencher dados do cliente

src/app/components/ProductCard.tsx envia um nome e um e-mail definidos diretamente no código em cada solicitação de checkout. Substitua-os pelos dados do usuário autenticado:

customer: {
  name: "John Doe",
  email: "john@example.com",
},

Atualizar o Customer Portal

O link do Customer Portal em src/app/components/Header.tsx abre /api/customer-portal com um ID de cliente definido diretamente no código. Substitua-o pelo ID de cliente do Dodo Payments do usuário autenticado:

const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID

Para obter um ID de cliente para testes, conclua uma compra de teste e copie o ID do cliente em Customers no dashboard. Em produção, busque o ID no seu backend.

Eventos de webhook

O handler em src/app/api/webhook/route.ts verifica cada solicitação com DODO_PAYMENTS_WEBHOOK_KEY e, em seguida, trata dois eventos:

onSubscriptionActive é executado quando uma assinatura se torna ativa (subscription.active).
onPaymentSucceeded é executado quando um pagamento é concluído com sucesso (payment.succeeded).

Adicione sua lógica de negócio dentro destes handlers:

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

Para tratar mais eventos, adicione os respectivos handlers, como onSubscriptionCancelled. O Next.js Adaptor lista todos os handlers compatíveis. O Dodo Payments não consegue acessar localhost. Para desenvolvimento local, use um túnel como o ngrok para expor seu servidor local e use a URL do túnel como endpoint de webhook.

Implantação

Compilar para produção

npm run build
npm start

Fazer deploy na Vercel

[

](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate) Adicione as quatro variáveis de ambiente no dashboard da Vercel e defina DODO_PAYMENTS_RETURN_URL como sua URL de produção.

Atualizar a URL do webhook

Após fazer o deploy, adicione a URL do webhook de produção no Dodo Payments Dashboard, usando seu domínio no lugar de example.com:

https://example.com/api/webhook

Cada endpoint tem seu próprio segredo de assinatura. Copie o segredo do novo endpoint para DODO_PAYMENTS_WEBHOOK_KEY no seu ambiente de produção.

Solução de problemas

Module not found or build errors

Exclua node_modules e package-lock.json e reinstale as dependências:

rm -rf node_modules package-lock.json
npm install

Checkout redirect fails

Verifique estas causas comuns:

O ID do produto não existe no seu dashboard do Dodo Payments.
A chave de API ou DODO_PAYMENTS_ENVIRONMENT em .env está incorreta. Uma chave do modo de teste funciona somente com test_mode.

Procure o erro no console do navegador e no terminal que executa npm run dev.

Webhooks not receiving events

Para testes locais, use o ngrok para expor seu servidor:

ngrok http 3000

No seu Dodo dashboard, adicione um endpoint com a URL HTTPS do ngrok seguida de /api/webhook. Copie o segredo de assinatura desse endpoint para DODO_PAYMENTS_WEBHOOK_KEY no seu arquivo .env.

Customer portal link doesn't work

Substitua o CUSTOMER_ID definido diretamente no código em src/app/components/Header.tsx pelo ID de um cliente no seu dashboard do Dodo Payments.Em produção, obtenha o ID do cliente do seu sistema de autenticação e banco de dados.

Saiba mais

Documentação do Dodo Payments
Documentação de Checkout Sessions
Documentação de Webhooks
Next.js Adaptor: opções para os handlers Checkout, CustomerPortal e Webhooks

Suporte

Para obter ajuda com o boilerplate:

Faça perguntas na comunidade do Discord.
Relate problemas e acompanhe as atualizações no repositório do GitHub.
Envie um e-mail para a equipe de suporte.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Visão Geral

Recursos

Pré-requisitos

Início rápido

Estrutura do projeto

Personalização

Atualizar informações do produto

Pré-preencher dados do cliente

Atualizar o Customer Portal

Eventos de webhook

Implantação

Compilar para produção

Fazer deploy na Vercel

Atualizar a URL do webhook

Solução de problemas

Saiba mais

Suporte

​Visão Geral

​Recursos

​Pré-requisitos

​Início rápido

​Estrutura do projeto

​Personalização

​Atualizar informações do produto

​Pré-preencher dados do cliente

​Atualizar o Customer Portal

​Eventos de webhook

​Implantação

​Compilar para produção

​Fazer deploy na Vercel

​Atualizar a URL do webhook

​Solução de problemas

​Saiba mais

​Suporte

Visão Geral

Recursos

Pré-requisitos

Início rápido

Estrutura do projeto

Personalização

Atualizar informações do produto

Pré-preencher dados do cliente

Atualizar o Customer Portal

Eventos de webhook

Implantação

Compilar para produção

Fazer deploy na Vercel

Atualizar a URL do webhook

Solução de problemas

Saiba mais

Suporte