Supabase Edge Functions na prática: runtime Deno e implantação global na borda

Você está olhando para aquela linha vermelha no painel de monitoramento: o tempo de resposta da API subiu para 2,3 segundos.

O usuário está no Japão, o servidor está em Ohio. Só a ida e volta da rede já consome cerca de 120 ms; depois ainda entram consulta ao banco de dados e processamento da lógica de negócio. Como não ficaria lento?

“E se a gente testasse uma função de borda?”, alguém comentou no Slack.

Eu fiquei bem desconfiado. Função de borda? Não é só rodar o código em outro lugar? Quanta diferença isso poderia fazer? Aí veio o teste, e eu parei para olhar melhor. Cold start de 120 ms, resposta da requisição em 47 ms. A mesma lógica, movida de Ohio para um nó de borda em Tóquio, ficou quase 5 vezes mais rápida.

Supabase Edge Functions se baseia no runtime Deno e executa código em nós globais de borda. Neste artigo, vamos entender por que ela é tão rápida, quais são as diferenças reais entre Deno e Node.js, como montar uma Edge Function do zero e como escolher entre ela e Cloudflare Workers.

1. Conceito central: o que são Edge Functions e por que são rápidas

Falando de forma direta, Edge Functions levam seu código do “servidor central” para os “nós de borda”.

Antes, quando você implantava uma função Lambda, ela rodava em servidores de uma região fixa, como Leste dos EUA ou Europa. Um usuário em Tóquio fazia a requisição, os dados cruzavam o oceano até o Leste dos EUA, eram processados e voltavam. A distância física define o piso da latência. Afinal, a velocidade da luz não é infinita.

Edge Functions mudam essa lógica. Seu código é empacotado em um formato compacto chamado ESZip e distribuído automaticamente para dezenas de nós de borda ao redor do mundo. Quando um usuário em Tóquio faz uma requisição, o código roda no nó de borda em Tóquio, removendo da resposta a parte mais cara da transmissão transoceânica.

O que é ESZip?

É um formato de empacotamento criado pela equipe do Deno. Diferente de um bundle JavaScript tradicional, o ESZip não empacota apenas o código; ele também inclui todo o grafo de dependências dos módulos. A vantagem é simples: durante a inicialização, não é preciso buscar dependências pela rede. Tudo está em um único arquivo. O cold start deixa de ser “baixar pacotes + analisar + executar” e vira “descompactar + executar”.

Modelo de execução com Isolate

Supabase Edge Functions rodam dentro de V8 Isolates, não em contêineres ou máquinas virtuais tradicionais. O que é um Isolate? Você pode imaginar como um contêiner Worker ultraleve. Um único processo consegue executar dezenas de Isolates, e cada Isolate processa uma requisição. É mais leve que um contêiner e também inicia mais rápido.

Segundo a documentação oficial da Supabase, o limite de tempo de CPU de um Isolate é de 400 segundos (limite flexível + limite rígido). Parece bastante, mas é bom lembrar: função de borda não foi feita para trabalho pesado. Ela serve para lógica leve, validação JWT, encaminhamento de requisições e tarefas parecidas. Computação pesada ainda fica melhor em um servidor central.

Veja uma Edge Function mínima:

// Exemplo mínimo de Edge Function
import "jsr:@supabase/functions-js/edge-runtime.d.ts"

Deno.serve(async (req) => {
  const { name } = await req.json()
  const data = { message: `Hello ${name}!` }
  return new Response(JSON.stringify(data), {
    headers: { "Content-Type": "application/json" }
  })
})

Esse código roda em um nó de borda. A requisição do usuário chega, Deno.serve recebe, a função processa e retorna a resposta. Todo o fluxo acontece no nó mais próximo do usuário.

2. Runtime Deno: a “evolução segura” do Node.js

Para ser honesto, quando ouvi falar de Deno pela primeira vez, a pergunta que me veio foi: Node.js já é tão maduro, por que criar outro runtime?

A resposta é bem simples: Node.js foi desenhado cedo demais, e vários problemas só apareceram depois.

Diferença de segurança

A política padrão do Node.js é “confiar em tudo”. Seu código quer ler o sistema de arquivos? Sem problema. Quer acessar a rede? À vontade. Quer executar comandos do sistema? Pode. Isso significa que uma dependência maliciosa consegue fazer praticamente qualquer coisa.

Deno faz o caminho oposto. Por padrão, seu código fica preso em uma “sandbox”: não pode ler arquivos, acessar a rede nem executar comandos do sistema. Quer permissões? Elas precisam ser declaradas explicitamente. Por exemplo:

# Conceder permissão de rede
deno run --allow-net server.ts

# Conceder permissão de leitura e escrita de arquivos
deno run --allow-read --allow-write file_ops.ts

# Conceder todas as permissões (use com cuidado)
deno run -A everything.ts

Esse desenho é especialmente importante em ambientes de borda. Sua função roda em dezenas de nós globais; se for atacada, a área de impacto pode ser enorme.

Diferença no cold start

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

Aqui estão dados medidos na prática. Rodei o mesmo código em Deno Deploy e em AWS Lambda:

A diferença é de 3 vezes. O motivo completo é mais complexo, mas o ponto central é que Deno não carrega algumas heranças históricas do Node.js, como o mecanismo CommonJS, a resolução de require e a busca em node_modules. Com empacotamento ESZip e suporte nativo a TypeScript, uma boa parte do custo de inicialização desaparece.

Mudança no sistema de módulos

Node.js usa CommonJS, carrega módulos com require(), e então você precisa instalar npm, manter package.json e criar o diretório node_modules. Em projetos grandes, esse diretório pode chegar a centenas de megabytes.

Deno usa diretamente o padrão ESM. Não há npm, não há package.json, não há node_modules. A importação pode ser feita por URL:

// Importar diretamente de uma URL
import { serve } from "https://deno.land/[email protected]/http/server.ts"

// Ou usar JSR, o repositório de pacotes do Deno
import { cors } from "jsr:@hono/hono/cors"

Na primeira execução, Deno baixa e armazena os módulos em cache local. Nas execuções seguintes, ele lê diretamente do cache, sem buscar pacotes pela rede novamente.

TypeScript sem configuração

Para rodar TypeScript no Node.js, você precisa instalar ts-node ou configurar webpack, vite ou esbuild, além de escrever tsconfig.json. Deno não precisa disso. Ele oferece suporte nativo a TypeScript e executa arquivos .ts diretamente:

deno run hello.ts

Compilação e checagem de tipos acontecem durante a execução. A experiência de desenvolvimento fica bem mais limpa.

A questão do lock-in de fornecedor

Essa também era uma preocupação minha. Ao usar Supabase Edge Functions, será que eu ficaria preso à plataforma?

A resposta é: não necessariamente. Deno em si é um runtime open source, e o Edge Runtime da Supabase também é open source, com código disponível no GitHub. Em teoria, você pode rodar o Edge Runtime nos seus próprios servidores. Claro, o custo operacional de uma rede global de borda passa a ser seu. Mas, pelo menos tecnicamente, não existe o problema de “não ter para onde fugir”.

3. Exercício prático: monte sua primeira Edge Function em 10 minutos

Não adianta só olhar a teoria. É colocando a mão na massa que você descobre se a experiência é boa.

Segui a documentação oficial do começo ao fim, da instalação à implantação, e levei menos de 10 minutos. O fluxo completo é este:

Primeiro passo: instalar a Supabase CLI

npm install -g supabase

Depois da instalação, você pode verificar a versão:

supabase --version
# Saída parecida com: 1.200.0

Segundo passo: inicializar o projeto

Se você já tem um projeto Supabase, inicialize dentro do diretório do projeto:

supabase init

Isso cria um diretório supabase, com o arquivo de configuração config.toml.

Terceiro passo: criar a Edge Function

supabase functions new hello-world

Depois da execução, um arquivo index.ts será gerado em supabase/functions/hello-world/, com algo parecido com isto:

import "jsr:@supabase/functions-js/edge-runtime.d.ts"

Deno.serve(async (req) => {
  const data = {
    message: "Hello from Edge Function!"
  }

  return new Response(JSON.stringify(data), {
    headers: { "Content-Type": "application/json" }
  })
})

Você pode trocar por sua própria lógica. Por exemplo, receber um parâmetro name e retornar uma saudação:

import "jsr:@supabase/functions-js/edge-runtime.d.ts"

Deno.serve(async (req) => {
  // Aceita apenas requisições POST
  if (req.method !== "POST") {
    return new Response("Method not allowed", { status: 405 })
  }

  try {
    const body = await req.json()
    const name = body.name || "Stranger"

    return new Response(JSON.stringify({
      message: `Hey ${name}, welcome to the edge!`,
      timestamp: new Date().toISOString()
    }), {
      headers: { "Content-Type": "application/json" }
    })
  } catch (err) {
    return new Response(JSON.stringify({ error: "Invalid JSON" }), {
      status: 400,
      headers: { "Content-Type": "application/json" }
    })
  }
})

Quarto passo: testar localmente

A Supabase CLI permite rodar Edge Functions localmente, o que facilita a depuração:

supabase functions serve --no-verify-jwt

Isso inicia um serviço local, na porta padrão 54321. Você pode testar com curl:

curl -X POST http://localhost:54321/functions/v1/hello-world \
  -H "Content-Type: application/json" \
  -d '{"name":"Easton"}'

# Retorno:
# {"message":"Hey Easton, welcome to the edge!","timestamp":"2026-05-03T14:30:00.000Z"}

O parâmetro --no-verify-jwt indica que a validação JWT será ignorada, o que é conveniente para testes locais. Em produção, é recomendável ativar a validação.

Quinto passo: implantar globalmente

Depois que o teste local estiver funcionando, implante na rede de borda da Supabase:

# Primeiro faça login, se ainda não tiver feito
supabase login

# Vincule seu projeto
supabase link --project-ref <your-project-id>

# Implante a função
supabase functions deploy hello-world

Quando a implantação terminar, a Supabase distribui sua função para nós globais de borda. No Dashboard, você consegue ver os logs de deployment e a URL da função.

Sexto passo: testar a chamada

Depois da implantação, o formato da URL é:

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

https://<project-id>.supabase.co/functions/v1/hello-world

Chame com curl:

curl -X POST https://<project-id>.supabase.co/functions/v1/hello-world \
  -H "Authorization: Bearer <anon-key>" \
  -H "Content-Type: application/json" \
  -d '{"name":"World"}'

Observe o header Authorization. Por padrão, Supabase Edge Functions valida JWT, então você precisa enviar a anon key do projeto ou um token JWT do usuário.

Voltando à pergunta: o que uma Edge Function consegue fazer? Além da demonstração, há muitos cenários práticos.

Processamento de webhooks

Por exemplo, depois de um pagamento bem-sucedido no Stripe, ele envia um webhook. Você pode receber esse evento com uma Edge Function e gravar no banco:

// supabase/functions/stripe-webhook/index.ts
import "jsr:@supabase/functions-js/edge-runtime.d.ts"
import { createClient } from "jsr:@supabase/supabase-js@2"

Deno.serve(async (req) => {
  // Validar a assinatura do Stripe (simplificado aqui; na prática, precisa de validação hmac)
  const event = await req.json()

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  )

  if (event.type === "payment_intent.succeeded") {
    const payment = event.data.object

    await supabase.from("payments").insert({
      id: payment.id,
      amount: payment.amount,
      customer_id: payment.customer,
      created_at: new Date().toISOString()
    })
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" }
  })
})

Proxy de API

Algumas APIs de terceiros precisam de API Key, e você não quer expor isso no frontend. Use uma Edge Function como proxy:

// supabase/functions/openai-proxy/index.ts
Deno.serve(async (req) => {
  const body = await req.json()

  const response = await fetch("https://api.openai.com/v1/chat/completions", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${Deno.env.get("OPENAI_API_KEY")}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(body)
  })

  return new Response(response.body, {
    headers: { "Content-Type": "application/json" }
  })
})

O frontend chama diretamente a sua Edge Function, e a API Key fica escondida no nó de borda.

4. Decisão de arquitetura: Supabase vs Cloudflare Workers

Quando o assunto é computação de borda, muita gente pergunta: Cloudflare Workers ou Supabase Edge Functions, qual é melhor?

Sendo honesto, elas não são concorrentes diretas. Os cenários são diferentes, então a escolha também muda.

Comparação de desempenho

Pelo tempo de cold start, Cloudflare Workers é mais rápido. O dado oficial é cerca de 30 ms, enquanto Supabase Edge Functions fica em torno de 120 ms.

Onde está a diferença? O runtime do Cloudflare Workers é desenvolvido pela própria Cloudflare e foi otimizado especificamente para cenários de borda. A Supabase usa Deno, que também é rápido, mas ainda adiciona a camada de compilação TypeScript.

Na experiência real, para a maioria dos casos, o usuário não percebe a diferença entre 120 ms e 30 ms. A própria variação de rede de uma página costuma ser maior que isso. Mas, se você está construindo algo como trading de alta frequência ou leilões em tempo real, onde cada milissegundo conta, Cloudflare Workers tende a ser mais adequado.

Comparação de integração

Esse é o ponto forte da Supabase. Com Supabase Edge Functions, você conecta diretamente o banco Postgres do mesmo projeto, chama o serviço de Auth e acessa Storage. As variáveis de ambiente são injetadas automaticamente, sem configuração extra.

Com Cloudflare Workers, você precisa resolver a conexão com o banco por conta própria. Pode usar Cloudflare D1, o banco SQLite de borda deles, ou conectar um banco externo. Mas a configuração exige um pouco mais de cuidado.

Lock-in de fornecedor

Esse ponto é interessante. O runtime do Cloudflare Workers é fechado. O código que você escreve roda na Cloudflare; se trocar de plataforma, provavelmente precisará adaptar o código.

Supabase Edge Functions usa Deno, que é open source. Em teoria, você pode levar o mesmo código para Deno Deploy ou auto-hospedar o Edge Runtime. Claro, a rede de borda da Supabase em si não pode ser simplesmente levada junto, mas pelo menos a camada de runtime não prende você.

Comparação de ecossistema

O ecossistema de Cloudflare Workers é mais maduro. Ele foi lançado em 2017 e já acumulou muitas ferramentas, frameworks e experiência de comunidade. Hono e Remix, por exemplo, dão suporte ao runtime Workers.

Supabase Edge Functions só chegou em 2022, então o ecossistema ainda está crescendo. Mas, como usa Deno padrão, muitas bibliotecas Deno podem ser usadas diretamente.

Recomendação de escolha

Com base na sua situação concreta, eu usaria esta matriz simples:

Hoje, minha própria abordagem é usar uma combinação. Cloudflare Workers fica com proxy reverso e cache no frontend; Supabase Edge Functions cuida da lógica relacionada a Auth e das operações de banco de dados. Cada plataforma entra onde é mais forte.

5. Armadilhas que encontrei e boas práticas

Aqui estão alguns problemas que encontrei na prática, para que você possa evitá-los.

Primeira armadilha: usar pacotes do Node.js

Na época, eu queria usar axios para fazer requisições HTTP e escrevi diretamente import axios from "axios". Na implantação, o erro veio na hora: módulo não encontrado.

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

Edge Functions usa Deno, não Node.js. Pacotes npm não podem ser usados diretamente. Você precisa trocar por pacotes compatíveis com Deno ou usar a API fetch nativa do Deno. Na verdade, fetch já resolve muita coisa:

// Não use axios
// import axios from "axios"  // Esta linha vai gerar erro

// Use fetch
const response = await fetch("https://api.example.com/data", {
  method: "GET",
  headers: { "Authorization": "Bearer xxx" }
})
const data = await response.json()

Se você realmente quiser uma biblioteca parecida com axios, pode procurar alternativas no ecossistema Deno, como ky.

Segunda armadilha: função rodando tempo demais e sendo encerrada

Uma vez escrevi uma função de processamento em lote que precisava percorrer alguns milhares de registros e fazer cálculos. No teste local, tudo funcionou; depois da implantação, ela rodou por 30 segundos e parou.

O motivo é simples: Edge Functions tem limite de tempo de CPU. Segundo a documentação oficial, o limite do Isolate é de 400 segundos, incluindo limite flexível e rígido. Ao ultrapassar o limite, o processo é encerrado à força.

A solução: não coloque trabalho pesado dentro de uma Edge Function. Nós de borda são bons para lógica leve, como validação, encaminhamento e cálculos simples. Tarefas complexas em lote devem ir para um servidor central ou para um serviço Worker dedicado.

Terceira armadilha: conectar ao banco do jeito errado

Ao conectar Postgres em um ambiente de borda, usar conexões longas tradicionais pode causar problemas. Há muitos nós de borda; se cada nó mantiver uma conexão longa, o pool do banco estoura rapidamente.

A prática recomendada é usar o pool de conexões (Pooler) fornecido pela Supabase, ou criar uma conexão curta para cada requisição e liberá-la logo em seguida. A Supabase fornece a variável de ambiente SUPABASE_DB_URL, que aponta para o Pooler:

import { Pool } from "https://deno.land/x/[email protected]/mod.ts"

const pool = new Pool(Deno.env.get("SUPABASE_DB_URL")!, 10)

Deno.serve(async (req) => {
  const client = await pool.connect()
  try {
    const result = await client.queryArray("SELECT * FROM users LIMIT 10")
    return new Response(JSON.stringify(result.rows))
  } finally {
    client.release()  // Não esqueça de liberar
  }
})

Quarta armadilha: validação JWT não configurada

Nos testes locais, usei --no-verify-jwt para facilitar a depuração. Depois da implantação, esqueci de habilitar a validação, e qualquer pessoa podia chamar minha função. É uma falha de segurança considerável.

O jeito correto é configurar no config.toml:

[functions.hello-world]
verify_jwt = true

Ou especificar durante a implantação:

supabase functions deploy hello-world --verify-jwt

Algumas dicas úteis

1. Use Hono no lugar de Deno.serve puro

Hono é um framework Web ultraleve, criado para ambientes de borda. Ele oferece rotas e middlewares, mas tem apenas 13 KB. Comparado ao peso do Express, Hono combina muito bem com Edge Functions:

import { Hono } from "jsr:@hono/hono"
import { cors } from "jsr:@hono/hono/cors"

const app = new Hono()

app.use("*", cors())

app.get("/health", (c) => c.json({ status: "ok" }))

app.post("/echo", async (c) => {
  const body = await c.req.json()
  return c.json({ echo: body })
})

Deno.serve(app.fetch)

2. Gerenciamento de variáveis de ambiente

Supabase Edge Functions tem dois runtimes: Main Runtime, controlado pela plataforma Supabase, e User Runtime, que é o seu código. As permissões das variáveis de ambiente são diferentes:

• SUPABASE_URL, SUPABASE_ANON_KEY e SUPABASE_SERVICE_ROLE_KEY são injetadas automaticamente, e seu código pode usá-las diretamente
• Variáveis personalizadas são configuradas pelo Dashboard ou pela CLI: supabase secrets set MY_VAR=value

3. Use Import Map para reduzir resolução repetida

Se sua função depende de muitos módulos externos, você pode usar Import Map para pré-definir importações e reduzir a resolução de URLs em cada requisição:

// deno.json ou import_map.json
{
  "imports": {
    "hono": "jsr:@hono/hono",
    "supabase-js": "jsr:@supabase/supabase-js@2"
  }
}

Depois, no código, use os nomes curtos diretamente:

import { Hono } from "hono"
import { createClient } from "supabase-js"

Conclusão

Depois de tudo isso, a ideia central cabe em uma frase: Supabase Edge Functions empurra seu código para o nó mais próximo do usuário, executa em um runtime Deno seguro, entrega cold start de 120 ms e faz a distribuição global automaticamente.

Se o seu projeto já usa Supabase, seja Auth, Database ou Storage, Edge Functions é uma extensão natural. Você não precisa brigar com conexão de banco, nem configurar validação Auth em separado; os serviços se encaixam diretamente. Preocupado com lock-in? Deno é open source, e o Edge Runtime pode ser auto-hospedado. Pelo menos existe uma rota de saída.

Qual é o próximo passo? Abra o Supabase Dashboard e siga o Quickstart. Em até 10 minutos, sua primeira Edge Function estará rodando em nós globais de borda.

Aliás, vale ler também os outros artigos desta série:

• Introdução ao Supabase: PostgreSQL + Auth + Storage como backend completo - para entender o panorama geral do Supabase
• Supabase Auth na prática: verificação por e-mail, OAuth e gerenciamento de sessões - prática com o serviço de autenticação
• Configuração avançada do Supabase Auth: OAuth, SSO e controle de permissões - configuração avançada

Se você tem mais interesse em Cloudflare Workers, também pode ler este artigo: Guia prático de Cloudflare Workers. As duas plataformas têm vantagens; escolha a que faz mais sentido para o seu caso.