Supabase Edge Functions: Criação, Testes e Deploy
Índice do Manual
Introdução
As Edge Functions do Supabase são scripts TypeScript (rodando em Deno) executados globalmente em servidores super rápidos perto dos seus usuários. Elas são a ferramenta perfeita para cenários onde você não quer depender do Frontend: integração de webhooks (Stripe, Hotmart), envio de e-mails em massa, ou lógicas de segurança sensíveis.
Este artigo é um guia tático de como criar, testar localmente e despachar para a nuvem usando o Supabase CLI.
1. Criando uma Função (Setup Inicial)
Para gerar a estrutura de uma nova Edge Function na sua máquina de forma correta, não crie a pasta manualmente. Peça para o CLI criar a fundação:
supabase functions new nome-da-funcao
Isso criará uma pasta dentro de supabase/functions/nome-da-funcao/ contendo um arquivo index.ts. É aqui que você escreverá a sua lógica de negócios usando TypeScript e Deno.
2. Testando Localmente (O Servidor Local)
Ao invés de subir para a nuvem para testar se a função funciona (o que faria você perder minutos preciosos a cada salvamento), você deve testar tudo no seu localhost.
Para que você tenha o controle absoluto dos logs (console.log) da sua função e consiga debugar erros facilmente sem misturar com os logs sujos do frontend (Next.js), nós adotamos o padrão de isolamento de terminais.
Abra uma aba exclusiva no seu terminal apenas para o backend de funções e execute:
supabase functions serve
Isso ligará um servidor de testes, geralmente acessível via:
http://localhost:54321/functions/v1/nome-da-funcao
Qualquer salvamento (Ctrl+S) no arquivo index.ts reinicia automaticamente a função na sua máquina. Agilidade em tempo real.
3. Lidando com Variáveis de Ambiente (Environment Variables)
Se a sua função usar chaves secretas (como uma chave da API da OpenAI, Resend ou Stripe), você precisará lidar com elas em dois mundos isolados: o Local (Testes) e a Nuvem (Produção).
3.1. Variáveis no Ambiente Local
Crie um arquivo chamado .env.local dentro da pasta supabase/ e coloque suas senhas de teste lá:
MINHA_CHAVE_SECRETA=sk_test_12345
Ao iniciar o seu terminal de testes, passe a bandeira indicando onde o arquivo está:
supabase functions serve --env-file supabase/.env.local
3.2. Variáveis no Cofre da Nuvem
O Supabase não envia o seu arquivo .env.local para a nuvem por razões óbvias de segurança. Para injetar a senha oficial no cofre remoto (da Staging ou Produção em que o seu terminal estiver linkado no momento), use:
supabase secrets set MINHA_CHAVE_SECRETA=sk_live_12345
[!TIP] Dica de Arquitetura (Staging vs Produção): Como a sua máquina de trabalho passa 99% do tempo linkada ao projeto de Staging, o comando acima salvará a senha na Staging. Para injetar a variável diretamente no banco de Produção sem precisar deslinkar seu terminal, basta usar a flag de referência de projeto:
supabase secrets set MINHA_CHAVE_SECRETA=sk_live_12345 --project-ref ID_DO_PROJETO_DE_PRODUCAO(Alternativamente, você pode cadastrar as senhas de Produção manualmente clicando em "Edge Functions > Secrets" no painel web do Supabase de Produção).
Independente do ambiente (Local ou Nuvem), o código TypeScript na sua função para ler essa chave será sempre o mesmo:
const chavePrivada = Deno.env.get('MINHA_CHAVE_SECRETA');
4. O Deploy (Mandando para a Nuvem)
Quando a função estiver blindada localmente, é hora de subi-la para a nuvem.
4.1. Deploy Manual para Homologação (Staging)
Durante o desenvolvimento diário, nós queremos subir as funções para a nuvem de Homologação para testá-las integradas aos demais sistemas. Como o seu terminal de trabalho passa 99% do tempo linkado ao projeto de Staging (supabase link), o comando manual injetará o código apenas na Staging:
supabase functions deploy nome-da-funcao
4.2. Deploy Automatizado para Produção (CI/CD)
Nós jamais fazemos deploy de código local diretamente para o banco de Produção. O deploy de Edge Functions de Produção deve ser 100% orquestrado por uma esteira de automação (como o GitHub Actions).
Atualizando o seu Robô de CI/CD:
Lembra do arquivo .github/workflows/production.yml que nós criamos lá no nosso Artigo 3 sobre Local, Staging e Produção? Aquele robô já estava configurado para empurrar as suas tabelas (db push).
Agora você deve abrir aquele arquivo e adicionar mais um passo (Step) no final dele para ele empurrar também a sua função:
- name: Executar DB Push
run: supabase db push
- name: Deploy das Edge Functions
run: supabase functions deploy
(Nota de Engenharia: Reparou que tiramos o nome-da-funcao no final do YAML? Se você rodar supabase functions deploy sem argumentos, o CLI inteligentemente fará uma varredura na pasta supabase/functions e fará o deploy (em lote) de todas as suas funções simultaneamente. Além disso, o GitHub Actions puxará os valores de SUPABASE_ACCESS_TOKEN e SUPABASE_PROJECT_ID já configurados nos Secrets).
Quando o seu código for aprovado e mesclado (merged) na branch principal (main), a esteira fará o deploy automático de ponta a ponta (Tabelas + Edge Functions).
[!CAUTION] Desastre em Produção (Rollback Manual): Se a esteira de CI/CD cair e houver uma falha crítica de negócios que exija um deploy de emergência da sua máquina local para a Produção, use a flag de projeto para pular o fluxo natural e forçar a atualização:
supabase functions deploy nome-da-funcao --project-ref ID_DE_PRODUCAO
Opcional: A Flag de Webhooks Abertos
Se a sua função for um Webhook público que recebe requisições de outras empresas (como o Stripe avisando que um pagamento caiu), o Supabase não pode bloquear a requisição pedindo Autenticação JWT. Nesses casos, force o deploy público:
supabase functions deploy nome-da-funcao --no-verify-jwt
Resumo da Regra de Ouro
O fluxo de vida de uma Edge Function segue a premissa máxima de isolamento corporativo:
- Nasce localmente (
functions new). - É testada no simulador de voo local (
functions serve). - Tem suas variáveis guardadas no cofre (
secrets set). - É despachada para o mundo real (
functions deploy).
Se você acha muita coisa para memorizar (comandos de Banco, Nuvem, CI/CD e Edge Functions), fique tranquilo. Siga para o nosso próximo capítulo, o Cheat Sheet: O Guia de Sobrevivência do Dia a Dia, onde compilamos absolutamente todas as rotinas que você usará no seu trabalho diário em formato de consulta rápida.