Capítulo 09 de 35

Cheat Sheet: O Guia de Sobrevivência do Dia a Dia

Índice do Manual

Este é o seu canivete suíço. Não tente memorizar a infraestrutura pesada, apenas consulte esta página sempre que esquecer como criar uma tabela, subir o sistema para produção ou resgatar o seu ambiente em um novo computador.

1. Ligar os Motores (Todo Dia)

Ao sentar para trabalhar de manhã, abra duas abas de terminal separadas na pasta do projeto para garantir o isolamento de logs:

Terminal 1 (O Backend):

supabase start

Terminal 2 (O Frontend):

npm run dev

(Lembrete: Os e-mails falsos de Autenticação gerados localmente vão para a caixa secreta em http://localhost:54324).

2. Fluxo de Banco de Dados (Migrations)

Sempre que a estrutura do banco mudar (novas tabelas, colunas, regras RLS), você deve salvar isso em arquivos de migração. (Para entender a fundo a lógica disso, leia o Manual de Versionamento de Migrations).

Se você criou a tabela clicando no painel local (Visual-First):

  1. Capture o que você criou visualmente e transforme em código rodando:
supabase db diff -f nome_da_migracao
  1. Aplique a tipagem no frontend rodando:
npm run gen-types

Se você preferir criar a tabela via código (Migration-First):

  1. Crie um arquivo de migração vazio rodando:
supabase migration new nome_da_migracao

(Atenção: O arquivo gerado na pasta supabase/migrations começará com um longo carimbo de tempo numérico, ex: 20260810143000_nome_da_migracao.sql. Jamais altere esses números, pois é através deles que o banco de Produção sabe a ordem cronológica exata em que as tabelas devem ser criadas).

  1. Escreva (ou cole) o código SQL bruto no arquivo criado.

  2. Para "injetar" esse arquivo SQL recém-criado dentro do seu banco de dados local para que a tabela passe a existir, roda-se:

supabase migration up

(Nota de Agilidade: Diferente do db reset que oblitera e recria o banco inteiro do zero, o migration up apenas lê os arquivos novos que ainda não foram aplicados e os injeta instantaneamente. Ideal para escrever SQL rápido).

  1. Aplique a tipagem no frontend rodando:
npm run gen-types

3. O Ciclo de Desenvolvimento (Git Flow Diário)

Você nunca programa direto na main ou staging. Siga o fluxo isolado:

  1. Inicie da base limpa (Produção):
git checkout main
git pull origin main
  1. Crie a branch da sua tarefa:
git checkout -b feature/nome-da-tarefa
  1. Sincronize o Banco de Homologação (Staging): Se a sua feature alterou o banco de dados, garanta que a nuvem de testes receba essas alterações ANTES de você subir o código do Next.js (do contrário, o build da Vercel vai quebrar procurando tabelas que não existem). Rode:
supabase db push
  1. Salve o código e suba a Branch:
git add .
git commit -m "feat: sua funcionalidade"
git push origin feature/nome-da-tarefa
  1. Mesclar na Homologação (Staging): Seu código e seu banco estão na nuvem. Agora é hora de unir a sua funcionalidade na branch oficial de testes. Escolha uma via:
  • Via GitHub (Padrão Corporativo): Acesse a interface web do GitHub e abra um Pull Request da sua branch de feature contra a branch staging.
  • Via Terminal (Agilidade Solo): Se você trabalha sozinho e quer evitar a burocracia visual do Pull Request, faça o merge direto no terminal:
git checkout staging
git merge feature/nome-da-tarefa
git push origin staging

4. Promover para Produção (Go-Live)

O cliente testou e aprovou a Staging. A Produção deve ser atualizada. Você nunca empurra a staging para a main, você empurra a feature isolada:

  • Via GitHub (Padrão Ouro):

    1. Acesse o GitHub e abra um Pull Request comparando a branch feature/nome-da-tarefa para a main.
    2. Clique em Merge Pull Request. (A Vercel publica na URL principal e o GitHub Actions injeta as Migrations no Supabase de Produção automaticamente).

  • Via Terminal (Agilidade Solo):

git checkout main
git merge feature/nome-da-tarefa
git push origin main

Limpeza Pós-Deploy

A feature está no ar e a branch feature virou lixo. Limpe-a:

  • Remoto: O GitHub deletará a branch automaticamente após o merge (caso a opção Automatically delete head branches tenha sido ativada nas configurações do repositório uma única vez durante o setup do projeto).
  • Local: Sincronize sua máquina com a nuvem e delete a branch local:
git checkout main
git pull origin main
git branch -d feature/nome-da-tarefa

Opcional: O Backmerge de Segurança

Pela regra da arquitetura, a staging e a main nunca perdem a sincronia porque toda feature é obrigada a passar pelas duas. Porém, se você suspeitar que alguém alterou a main diretamente (um erro humano), você pode forçar a sincronia puxando a verdade absoluta da Produção de volta para a Homologação:

git checkout staging
git merge main
git push origin staging

(Se tudo estiver nos conformes, o terminal avisará: "Already up to date").

Exceção: Alterações Triviais (Hotfix Rápido)

Para mudanças minúsculas (ex: cor de botão, texto), pule a interface do GitHub e resolva com agilidade tática no terminal:

# 1. Cria a branch da base
git checkout main && git pull origin main
git checkout -b fix/cor-botao

# 2. Altera o código, salva e empurra pra Staging
git add . && git commit -m "fix: altera cor do botao"
git checkout staging && git merge fix/cor-botao
git push origin staging

# 3. Cliente aprovou na Staging? Empurre pra Produção
git checkout main && git merge fix/cor-botao
git push origin main

# 4. Limpeza: Você já está na base (main), apenas apague o rastro
git branch -d fix/cor-botao

5. Recuperação Imediata (PC Quebrou / Novo Dev)

Se o notebook quebrar, ou a equipe aumentar, a recuperação do ambiente leva apenas 2 minutos:

  1. Clone o repositório do GitHub:
git clone [url_do_seu_github]
  1. Entre na pasta e instale as dependências:
cd nome-do-projeto && npm install
  1. Libere a malha de segurança de múltiplas contas. Se o terminal der erro, leia nosso Manual de Múltiplas Contas:
direnv allow
  1. Baixe as senhas do ambiente de Staging da Vercel:
vercel env pull .env.local --environment=preview
  1. PASSO CRÍTICO: Abra o arquivo .env.local e sobreponha o NEXT_PUBLIC_SUPABASE_URL e a NEXT_PUBLIC_SUPABASE_ANON_KEY usando as credenciais geradas pelo seu banco local.
  2. Ligue o banco e o projeto em terminais separados:
supabase start

npm run dev

6. Supabase Edge Functions (Backend Seguro)

Quando precisar rodar lógicas seguras ou receber Webhooks (Stripe) que não podem ficar expostos no Frontend.

  1. Criar uma Nova Função:
supabase functions new nome-da-funcao
  1. Ligar o Simulador Local:
supabase functions serve

(Abra um Terminal 3 exclusivamente para ver os logs desta função, isolados do Next.js).

  1. Injetar Senhas no Cofre da Nuvem:
supabase secrets set MINHA_SENHA=sk_live_12345
  1. Deploy da Função para a Nuvem:
supabase functions deploy nome-da-funcao

(Dica: Se a função for um Webhook público, adicione --no-verify-jwt no final).

7. Comandos de Qualidade (Testes)

Quando você for focar em testes (Quality Assurance), não perca tempo buscando na documentação.

Testes Unitários (Vitest) - Foco em Backend, RLS e Edge Functions:

  • npm run test (Roda os testes uma vez e exibe o resultado no terminal).
  • npm run test:watch (Roda os testes e fica "ouvindo" o código. Excelente para TDD: você salva o arquivo e ele testa instantaneamente).

Testes End-to-End (Playwright) - Foco na Jornada do Usuário (Login, Compra):

  • npx playwright test (Abre navegadores invisíveis em background e simula todo o clique do usuário em altíssima velocidade).
  • npx playwright test --ui (Abre o painel visual do Playwright, permitindo que você veja o robô clicando na tela passo a passo para debugar por que algo quebrou).

Fim da Fundação: O Palco Está Montado

Se você chegou até aqui e compreendeu o fluxo de trabalho deste Cheat Sheet, meus parabéns. Você acaba de concluir o Módulo de Fundação e Setup.

A sua máquina local não é mais apenas um computador; ela se tornou um clone perfeito de uma arquitetura corporativa em nuvem, equipada com isolamento de banco de dados, controle de versão de Migrations, esteira de deploy automático (CI/CD) e proteção militar de variáveis.

A infraestrutura pesada está 100% configurada e rodando silenciosamente no plano de fundo.

Mas isso é apenas a ponta do iceberg. Com essa fundação de nível empresarial perfeitamente estabelecida, as possibilidades do que você pode construir são infinitas. Para descobrir como plugar Inteligência Artificial, sistemas de pagamento (Stripe), Webhooks, Autenticação B2B e outras superpotências no seu ecossistema, continue lendo os próximos manuais da nossa base de conhecimento.

Capítulo AnteriorSupabase Edge Functions: Criação, Testes e DeployPróximo Capítulo Validação Blindada de Dados: Zod + Server Actions