Pular para o conteúdo

Builder OS

&
Builder · OS
L02 · Primeiro deploy + doctor
PRÓXIMA L03
~13 MIN DE LEITURA

Lição 2 de 9: Primeiro deploy e doctor

lição 2/9 do Módulo 4
AO FIM, VOCÊ VAI TER
  • Produto rodando em <seu-projeto>.vercel.app (URL real, SSL, todas as rotas servindo 200)
  • Skill deploy-and-verify em .claude/skills/ cobrindo o ritual pré-deploy
  • Comando npm run doctor rodando verde (6 checks passando)
  • Commit chore(deploy): first production deploy + doctor checks

O deploy leva dois minutos; configurar leva mais

Build local passou (L01). Agora sobe. O Vercel deixa isso fácil: um comando, dois minutos, e o produto está num *.vercel.app público com SSL. O que separa produto de demo abandonado é o conjunto de checks que confirma se o que subiu está mesmo funcionando.

As 4 etapas que fazem o deploy ser previsível em vez de "apertar botão e torcer":

  1. Configurar variáveis secretas no Vercel: senhas que estavam só no .env.local precisam estar lá também
  2. Deploy de teste primeiro (preview): URL temporária; se quebrar, sem problema
  3. Promover pra produção depois que o preview funcionou
  4. Instalar o doctor: script que confere 6 coisas antes de cada deploy futuro

Esta lição instala o , comando local (npm run doctor) que roda 6 checks pré-deploy. Você vai usar ele toda vez antes de subir, como o cinto de segurança antes de dirigir.

Pré-requisitos desta lição:

  • Conta Vercel (free tier): cria agora se não tem.
  • Vercel CLI (npm i -g vercel) com login (vercel login). O primeiro vercel no projeto pede login no browser.
  • Repo no GitHub com o projeto pushed em pelo menos main.
  • openssl no PATH (já vem no macOS/Linux; no Windows usa Git Bash ou WSL). Vamos gerar segredos com ele.

Passo 1 — Deploy preview primeiro

Antes de produção, . URL temporária, comportamento idêntico ao da produção, e errar ali não custa nada.

prompt · text
Roda `vercel` (sem `--prod`) na raiz do projeto. Se for o primeiro deploy:

1. Vercel vai perguntar projeto novo ou existente — responde "new project"
2. Vai perguntar diretório raiz — confirma "./"
3. Vai perguntar pra configurar settings — aceita defaults primeiro, ajuste depois se preciso

Mostre a URL do preview deploy quando terminar.

Aprove. Aguarde os 2-3 minutos de build na Vercel. Abre a URL do preview no browser, e:

  1. Página inicial carrega (sem erro 500)
  2. Rota da fatia 1 carrega (ex: /recibos/novo)
  3. Submete o formulário. Quase certo que vai falhar: o banco em produção ainda não existe, ou as env vars não estão configuradas. É o esperado nesta etapa. A preview existe justamente pra você bater nesse erro antes de promover pra produção.

Passo 2 — Configure as env vars do Vercel

A preview falhou porque o Vercel não tem o .env.local que você usa na sua máquina. As variáveis precisam ser configuradas no dashboard do Vercel (ou via CLI).

prompt · text
Lê o `.env.example` (criado na L01). Lista pra mim, em formato de comandos `vercel env add`, cada variável que precisa ser configurada pra produção. Não rode os comandos — só lista pra eu copiar e rodar uma de cada vez (preciso colar os valores reais).

Roda os comandos manualmente (são interativos; Vercel pede o valor de cada uma). Lembra:

  • Database URL: produção tem que ser outro banco, não o local. Crie um Postgres separado pra produção (Vercel Postgres, Supabase, Neon, Railway, qualquer um serve). Nunca aponte produção pro banco do seu laptop.
  • Segredos: gere segredos novos pra produção, não reaproveite os do local. openssl rand -hex 32 é a forma padrão.
  • Variáveis NEXT_PUBLIC_*: ficam expostas no JS do client, só pra coisa não-sensível (ex: URL pública da analytics, não chave de API).

Depois de configurar, redeploy:

prompt · text
Roda `vercel` (preview de novo) pra incorporar as env vars que acabei de configurar. Mostra a nova URL.

Testa de novo no browser. Agora o submit do formulário deve funcionar. Se funcionou, está pronto pra --prod.

Passo 3 — Promova pra produção

prompt · text
Roda `vercel --prod`. Mostra a URL de produção (`<projeto>.vercel.app`) e confirma que o SSL está ativo.

Aguarde, abra a URL de produção. Mesma rota da fatia 1, mesmo submit. Se passar, é a primeira coisa pública que você construiu este mês.

Passo 4 — Instale o npm run doctor

Você acabou de fazer deploy manualmente. Na próxima vez (e na vez depois, e na seguinte), é fácil deixar algum check pra trás: ou o vercel build, ou alguma env var nova, ou que o npm run build precisava passar primeiro. O doctor automatiza esse checklist.

prompt · text
Cria `bin/doctor.mjs` (ou caminho equivalente) com 6 checks pré-deploy. Cada check responde OK ou FAIL + 1 linha de motivo:

1. `vercel.json` existe na raiz (se o projeto usa)
2. `.env.example` existe na raiz
3. Projeto está linkado a um deploy Vercel (`.vercel/project.json` existe). O doctor checa o arquivo local em vez de rodar `vercel ls` (que falha sem auth e geraria FAIL ruidoso no CI). (Nas lições L07 e L09 você roda `vercel ls` direto no terminal, onde já está logado — ali ele serve pra listar deploys; aqui no doctor, o `.vercel/project.json` é o sinal local suficiente.)
4. Pelo menos uma chamada `analytics.track` no código (`grep -r 'analytics.track' src/`)
5. Helper de analytics existe (`lib/analytics.ts` ou equivalente)
6. Custom domain configurado (placeholder — true por agora; vai virar check real na L03)

`package.json`: adiciona `scripts.doctor: "node bin/doctor.mjs"` pra rodar como `npm run doctor`.

Mostre o diff antes de criar.

Aprove. Roda:

prompt · text
Roda `npm run doctor`. Mostra o output completo dos 6 checks.

Você espera 5 OKs e 1 placeholder (custom domain, que vai virar check real na L03). Se algum falha, conserta antes de seguir.

Passo 5 — Crie a skill deploy-and-verify

Vale a regra da 3ª repetição: você fez deploy manual uma vez, vai fazer no próximo módulo de feature, e vai fazer toda vez que quiser publicar. Na 3ª, escreve a skill.

prompt · text
Crie `.claude/skills/deploy-and-verify/SKILL.md` com:

# Deploy and Verify

## When to use
Use this skill before every production deploy.

## Steps

1. Run `npm run doctor` and confirm all checks pass (FAIL blocks deploy)
2. Run `npm run build` and confirm green (build errors block deploy)
3. Run `vercel` (preview) and verify the preview URL works for the happy path
4. If preview is good: `vercel --prod`
5. Open the production URL and re-test the happy path (NOT just the homepage — the wedge feature too)
6. If anything fails post-deploy: `vercel ls` to find the previous deploy, then `vercel rollback <previous-deploy-url>` (see L07 for the full procedure)

## Anti-patterns
- Don't deploy without doctor passing
- Don't skip preview — production has the same config but the consequence is public
- Don't deploy on Friday afternoon

Mostre o diff antes de criar.

Aprove. Confira que .claude/skills/deploy-and-verify/SKILL.md está no caminho certo.

Passo 6 — Faça o commit

prompt · text
Faça commit do `bin/doctor.mjs`, ajustes em `package.json`, e `.claude/skills/deploy-and-verify/SKILL.md`. Mensagem: `chore(deploy): first production deploy + doctor checks`. Mostra os comandos antes.

Aprove. Confira no GitHub.

Build Diary — o CEAP escreveu um Launch Checklist antes de subir

Antes de promover o CEAP pro custom domain, o autor escreveu o LAUNCH_CHECKLIST.md: uma lista exaustiva organizada em fases. Trecho da Fase 1:

Phase 1: Visão Geral - COMPLETED

Code Preparation

  • Feature flags created (src/config/features.ts)
  • Sidebar updated to use feature flags
  • Route guards added to App.tsx
  • Production URLs updated in index.html
  • wrangler.toml created
  • Deploy script added to package.json

Deployment

  • Install wrangler as dev dependency
  • Login to Cloudflare via wrangler
  • Create Cloudflare Pages project
  • Deploy to Cloudflare Pages
  • Configure custom domain ceap.escoladados.com
  • SSL certificate active

Verification

  • Site loads at https://ceap.escoladados.com
  • Only "Visão Geral" tab visible
  • Test all charts load correctly
  • Test filters work
  • Test mobile view
  • Run Lighthouse audit

A maior parte é caso específico do CEAP, não vale copiar item por item. O que vale é o padrão. Alguém escreveu uma lista de critérios objetivos, foi marcando, e teve evidência (não só esperança) de que o que subiu funcionava.

O npm run doctor que você acabou de criar é a versão automatizada disso. Cada check é um [ ] da Phase 1 do CEAP virado em assertion programática. Mesma lógica, com menos atrito.

Takeaways

  • Preview primeiro, produção depois: *.vercel.app antes do --prod. O deploy leva dois minutos; o resto é configurar pra subir certo.
  • Cada env var configurada no Vercel CLI; banco de produção separado do local. Nunca aponte produção pro banco do seu laptop.
  • npm run doctor é a 3ª repetição virada em script. São 6 checks: vercel.json existe, .env.example existe, projeto linkado, analytics.track chamado, helper de analytics existe, domain placeholder (vira check real na L03).
  • Skill deploy-and-verify documenta o ritual. Anti-pattern explícito: nunca deploy na sexta à tarde sem o ritual.

Você terminou quando

Quatro coisas:

  1. Produto rodando em <projeto>.vercel.app com SSL e fatia 1 funcional ponta a ponta
  2. bin/doctor.mjs com 6 checks; npm run doctor retorna 5 OKs + 1 placeholder
  3. Skill deploy-and-verify em .claude/skills/
  4. Tudo commitado