Lição 1 de 9: Do local ao deployável

O que muda de local pra produção

Fatia 1 está rodando local (Módulo 3 inteiro). A próxima fronteira é produção, onde o ambiente muda em quatro pontos: buildO processo que compila o código pra versão otimizada que vai pra produção: minificada, sem hot reload. É o `npm run build`, diferente do `npm run dev`. otimizado em vez de npm run dev, variáveis vindas do ambiente em vez de .env.local, banco que não é o seu, e comportamento que pode divergir do dev em 3 lugares previsíveis.

Você vai preparar o repo pra subir (o deployO ato de subir o build pra um servidor público (Vercel, Cloudflare). Depois do deploy, o código roda na URL que o usuário final acessa. em si fica pra L02), mas não vai subir ainda. Cada ambiente é uma fronteira diferente:

A regra: rodar npm run build local até passar verde, com .env.example completo, é o sinal de que produção tem condição de funcionar.

As 3 divergências entre dev e produção

Três divergências previsíveis entre dev e prod no Next.js + Vercel:

1. Server Components com process.env que existem só no .env.local. Em dev, Next lê .env.local automático. Em prod, ele lê do environment do Vercel; se você esqueceu de configurar, o componente renderiza com undefined e quebra silenciosamente.
2. Imports dinâmicos que dev tolera. import('./something') que dev resolve sem reclamar pode quebrar no build se o path estiver errado em maiúscula/minúscula (Linux do servidor Vercel é case-sensitive; macOS local é case-insensitive).
3. Console.log que dev mostra colorido. Em prod, vira linha JSON nos logs do Vercel; se você usa console.log pra debugar, vira ruído sem contexto. Esta lição ainda não trata isso (M3/L06 instalou o analytics.track); mas é bom saber.

A consequência prática: você quer descobrir essas três classes agora (build local), não dali a 5 minutos quando o site público quebrar.

Passo 1 — Catalogue as variáveis de ambiente

Cole no Claude:

Lê todos os arquivos do projeto que usam `process.env` ou `import.meta.env` (Next.js: process.env; Vite: import.meta.env). Lista pra mim:

1. Cada variável de ambiente usada (sem o valor — só o nome)
2. Onde ela é usada (path do arquivo)
3. O que acontece se ela estiver `undefined` (crash imediato? fallback silencioso? erro de tipo?)

Resposta em tabela markdown.

Aprove e leia a resposta com atenção. As variáveis com "fallback silencioso" são as perigosas: em produção, vão funcionar errado sem avisar.

Passo 2 — Crie .env.example

Cole no Claude:

Crie `.env.example` na raiz do projeto. Inclui:

1. Cada variável de ambiente identificada no Passo 1, com:
 - Nome em UPPER_SNAKE_CASE
 - Comentário em pt-BR explicando o que é (1 linha)
 - Valor de exemplo (placeholder, nunca o valor real). Use `<<gere-com-comando-X>>` quando for segredo, ou exemplo formatado quando for URL.
2. **Não copie do `.env.local`** — gere a partir dos nomes catalogados. Se algum nome do `.env.local` não aparece no código, ignora (variável morta) e me avisa no fim.

Mostre o diff antes de criar. Confirma que `.env.example` está no `.gitignore` NEGADO (forçando entrar no git, ao contrário do `.env*`).

Aprove. Verifica que .gitignore permite .env.example (pode precisar de !.env.example se a regra geral é .env*).

Passo 3 — npm run build local até passar

Roda:

Rode `npm run build` no projeto. Mostre o output completo. Se passar verde, ótimo. Se falhar, mostra exatamente qual erro e onde, e propõe correção sem aplicar — quero ver antes.

3 classes comuns de erro:

1. Erro de tipo (tsc). Provavelmente um any implícito que dev tolerava. Conserta sem // @ts-ignore: o jeito honesto é tipar corretamente.
2. Erro de import (case mismatch). import Foo from './foo' quando o arquivo é Foo.tsx quebra no Linux do Vercel. Conserta o path pra bater exatamente com o nome do arquivo.
3. Erro de env var (undefined). Significa que npm run build precisa de uma variável que .env.local tem mas .env.example lista. Confirma se ela é build-time ou runtime. Se for build-time (process.env.NEXT_PUBLIC_*), precisa estar disponível durante o build no Vercel.

Depois de corrigir, roda de novo. Não avance enquanto não passar verde.

Passo 4 — vercel build (dry-run)

Esta etapa simula o build do Vercel localmente. Pega erros que npm run build não pega (config do Vercel, runtime do serverless, etc.).

Verifica se a Vercel CLI está instalada (`vercel --version`). Se não, propõe instalar com `npm i -g vercel` e me avisa antes. Se sim, roda `vercel build` no projeto (sem `--prod`, é dry-run) e mostra o output. Não roda `vercel deploy` ainda — só o build.

Se passa, o repo está pronto pra subir. Se falha, é configuração específica do Vercel (geralmente vercel.json ou next.config): Claude propõe correção, você revisa.

Passo 5 — Faça o commit

Faça commit do `.env.example` + correções de build que foram aplicadas. Mensagem: `chore(deploy): env.example + build green local`. Mostra os comandos antes.

Aprove. Confira no GitHub. Não suba pra Vercel ainda: a L02 é a lição do primeiro deploy real.

Build Diary — um checklist pré-deploy real

Um projeto real tinha um launch-readiness.md: auditoria sistemática de cada aba do produto antes do lançamento público. Cinco workstreams paralelos, cada um com Acceptance criteria explícitos:

Workstream 4 — Session persistence parity. Make cross-device restore work for every tool, not just Analyze.

Acceptance criteria:

• All tool outputs are user-keyed (not profileId-keyed) so they survive cross-device login
• Migration runs idempotently for users who already have profileId-keyed entries
• Tests pass; no regression in single-device flow

Cada item de cada workstream tem assertion programática: não "espero que funcione," mas "se este check falhar, deploy é bloqueado." Esse é o pattern que esta lição instala em escala mínima.

Rodar o build de produção uma vez antes do deploy é o que evita descobrir erro em público. O build local pega a maior parte dos erros antes de qualquer URL pública existir: erro de tipo que dev silencia, import case-sensitive que macOS tolera mas Linux rejeita, env var que ficou faltando.

Takeaways

• Produção muda quatro coisas em relação ao local: build otimizado, env vars de ambiente, banco separado, e divergências previsíveis em case-sensitivity e fallback silencioso de process.env.
• .env.example no git, valores reais nunca. .env.local no .gitignore sempre.
• npm run build local antes de qualquer vercel deploy: pega 80% dos erros que apareceriam em produção.
• vercel build (dry-run) é a camada final antes do deploy real: pega config-specific bugs do Vercel.

Você terminou quando

Quatro coisas:

1. .env.example no repo com todas as variáveis catalogadas (placeholders, nunca valores reais)
2. npm run build passa verde local
3. vercel build (dry-run) passa local
4. Tudo commitado