desenvolvimento local

pré-requisitos:

Node.js versão 19 ou superior
Wrangler CLI instalado
Acesso ao Cloudflare Workers
Repository com wrangler.toml configurado

este guia te ajuda a configurar o ambiente de desenvolvimento para trabalhar com nossa API do dashboard backend.

configure o ambiente backend

# clone o repositório
git clone [REPO_URL]
cd dashboard-backend

# instale dependências
npm install

configure as variáveis de ambiente

você precisará configurar as seguintes variáveis no wrangler.toml:

[vars]
JWT_SECRET = "seu_jwt_secret"
BEEHIIV_API_KEY = "sua_api_key"
GEMINI_API_KEY = "sua_gemini_key"
RESEND_API_KEY = "sua_resend_key"
# ... outras variáveis

nunca commite secrets reais no repositório. use wrangler secret put para secrets sensíveis.

execute o servidor de desenvolvimento

# inicia o servidor local conectado ao ambiente remoto
npm run dev

sua API estará disponível em http://localhost:8787.

teste os endpoints

você pode testar os endpoints usando curl ou Postman:

# teste um endpoint público
curl http://localhost:8787/referrals/count

# teste um endpoint autenticado
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     http://localhost:8787/referrals

estrutura do projeto

nossa API é organizada da seguinte forma:

dashboard-backend/
├── src/
│   ├── routes/          # definições de rotas
│   ├── handlers/        # lógica de negócio
│   ├── services/        # integrações externas
│   ├── middleware/      # autenticação e cache
│   ├── schema/          # schemas do banco
│   └── types/           # tipos TypeScript
├── drizzle/             # migrações do banco
└── wrangler.toml        # configuração do Workers

bancos de dados

ossa arquitetura utiliza múltiplos bancos D1 especializados:

📊 DB

dados principais, métricas e newsletters

🎯 STREAKS

gamificação, leituras e engagement

👥 CRM

gestão de relacionamento com clientes

📝 FORMS

formulários dinâmicos e submissions

migrações do banco

para aplicar migrações localmente:

# gerar nova migração
npm run generate

# aplicar migrações localmente
npm run migrate

deploy para produção

quando estiver pronto para fazer deploy:

# deploy com minificação e source maps
npm run deploy

o deploy inclui automaticamente integração com Sentry para monitoramento de erros.

ferramentas recomendadas

para melhor experiência de desenvolvimento:

VSCode com extensões TypeScript
Drizzle Kit para gestão do banco
Postman ou Insomnia para teste de APIs
Wrangler para gestão do Cloudflare Workers

solução de problemas

erro: "wrangler not found"

instale o wrangler CLI globalmente:

npm install -g wrangler

ou use via npx:

npx wrangler dev --remote

erro de autenticação com Cloudflare

faça login no Cloudflare:

wrangler login

verifique se o account_id está correto no wrangler.toml.

erro: banco de dados não encontrado

verifique se os database IDs estão corretos no wrangler.toml e se os bancos existem no painel do Cloudflare.

endpoints retornando 500

verifique os logs do Sentry ou use wrangler tail para debug em tempo real:

wrangler tail

dica: use console.log() liberalmente durante desenvolvimento - os logs aparecerão no terminal com npm run dev.

Getting started

Customization

Writing content

AI tools

desenvolvimento local

estrutura do projeto

bancos de dados

📊 DB

🎯 STREAKS

👥 CRM

📝 FORMS

migrações do banco

deploy para produção

ferramentas recomendadas

solução de problemas

​estrutura do projeto

​bancos de dados

📊 DB

🎯 STREAKS

👥 CRM

📝 FORMS

​migrações do banco

​deploy para produção

​ferramentas recomendadas

​solução de problemas

estrutura do projeto

bancos de dados

migrações do banco

deploy para produção

ferramentas recomendadas

solução de problemas