Astro Minimal Boilerplate

Visão Geral

O boilerplate mínimo do Astro é 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 Astro 5 com TypeScript, Tailwind CSS 4 e o adaptador @dodopayments/astro. Para adicionar as mesmas rotas de API a um app existente, consulte Astro Adaptor.

Recursos

O boilerplate inclui:

Configuração rápida: passe do clone a uma página de preços em execução em cerca de cinco minutos.
Checkout: um fluxo de checkout pré-configurado criado com base em @dodopayments/astro.
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 a assinatura de cada 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 para o checkout, para que ele não precise digitá-los novamente.

Pré-requisitos

Antes de começar, você precisa de:

Uma versão LTS do Node.js, exigida pelo Astro 5.
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-astro-minimal-boilerplate.git
cd dodo-astro-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 Live Mode na barra lateral estiver desativado. Uma chave do modo de teste funciona apenas 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:4321/
DODO_PAYMENTS_ENVIRONMENT=test_mode

.env.example define DODO_PAYMENTS_RETURN_URL como a porta 3000. Altere-a para 4321, a porta usada pelo servidor de desenvolvimento do Astro, para que o checkout redirecione o cliente de volta ao seu app.As rotas de API leem estas variáveis:

DODO_PAYMENTS_API_KEY autentica as rotas de checkout e do Customer Portal.
DODO_PAYMENTS_WEBHOOK_KEY verifica as assinaturas dos webhooks.
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. 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:4321 para ver sua página de preços.

Estrutura do projeto

As rotas de API de checkout, Customer Portal e webhook ficam em src/pages/api/:

src/
├── components/
│   ├── Footer.astro           # Reusable footer
│   ├── Header.astro           # Navigation header
│   └── ProductCard.astro      # Product pricing card
├── layouts/
│   └── Layout.astro           # Root layout
├── lib/
│   └── products.ts            # Product definitions
├── pages/
│   ├── index.astro            # Pricing page (home)
│   └── api/
│       ├── checkout.ts        # Checkout session handler
│       ├── customer-portal.ts # Customer portal redirect
│       └── webhook.ts         # Webhook event handler
└── styles/
    └── global.css             # Global styles with Tailwind

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

O script de checkout em src/components/ProductCard.astro 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 conectado:

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

Atualizar o Customer Portal

O link do Customer Portal em src/components/Header.astro abre /api/customer-portal com um ID de cliente definido diretamente no código. Substitua-o pelo ID do cliente do seu sistema de autenticação ou banco de dados:

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.

Eventos de webhook

O handler em src/pages/api/webhook.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).
onSubscriptionCancelled é executado quando uma assinatura é cancelada (subscription.cancelled).

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

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

Para tratar mais eventos, adicione os respectivos handlers, como onPaymentSucceeded. O Astro Adaptor lista todos os handlers compatíveis. O Dodo Payments não consegue alcançar 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 do webhook.

Deploy

O Astro cria as páginas como saída estática, e cada rota de API define export const prerender = false para que seja renderizada sob demanda. As rotas sob demanda precisam de um adaptador do Astro para sua plataforma de deploy:

Plataforma	Guia
Vercel	Deploy to Vercel
Netlify	Deploy to Netlify
Cloudflare	Deploy to Cloudflare

Para outras plataformas, consulte os guias de deploy do Astro. Na sua plataforma de hospedagem, adicione as quatro variáveis de ambiente 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 de produção do webhook no Dodo Payments Dashboard:

https://your-domain.com/api/webhook

Cada endpoint tem seu próprio segredo de assinatura. Defina DODO_PAYMENTS_WEBHOOK_KEY no ambiente de produção como o segredo de assinatura deste endpoint.

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

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 arquivo .env.

Customer portal link doesn't work

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

Build fails with adapter error

As rotas de API são renderizadas sob demanda, e o repositório não inclui um adaptador de deploy. Instale o adaptador do Astro para sua plataforma antes de fazer o build para produção.Consulte os guias de deploy do Astro para obter detalhes.

Saiba mais

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

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

Deploy

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

​Deploy

​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

Deploy

Atualizar a URL do webhook

Solução de problemas

Saiba mais

Suporte