Edge Functions en Supabase

Las Edge Functions son funciones serverless (funciones que corren bajo demanda, sin que tú administres un servidor) que Supabase ejecuta en el edge (la red de servidores distribuidos más cercana al usuario). Corren sobre Deno, un runtime de JavaScript y TypeScript creado por el mismo autor de Node.js.

Qué son las Edge Functions

Una Edge Function es un archivo TypeScript que expone un handler HTTP. Cuando alguien hace un request a la URL de tu función, Supabase levanta el runtime de Deno, ejecuta tu código y devuelve la respuesta. No hay servidores que mantener, no hay infraestructura que configurar.

Cada función vive en su propio directorio dentro de supabase/functions/ en tu proyecto:

supabase/
  functions/
    mi-funcion/
      index.ts    <-- tu codigo
    otra-funcion/
      index.ts

El entry point siempre es index.ts y usa Deno.serve() para manejar requests.

Cuándo usar Edge Functions

Las Edge Functions son la herramienta correcta cuando necesitas ejecutar lógica que no debería correr en el cliente ni puede resolverse solo con RLS y la API auto-generada.

Casos de uso típicos

• Webhooks: recibir notificaciones de servicios externos (Stripe, GitHub, Resend)
• Integraciones con APIs de terceros: llamar a APIs externas que requieren API keys secretas
• Transformación de datos: procesar datos antes de guardarlos en la base de datos
• Notificaciones: enviar emails o push notifications cuando ocurre algo en tu app
• Lógica de negocio compleja: cálculos, validaciones o flujos que no encajan en una política de RLS
• Scheduled functions: tareas programadas que se ejecutan periódicamente (con pg_cron)

Cuándo NO usar Edge Functions

• Queries simples a la base de datos: usa el SDK directamente. La API auto-generada es más rápida y no requiere código extra
• Validación de permisos: usa RLS. Es más seguro y más performante
• Servir archivos estáticos: usa Storage

Deno vs Node.js

Las Edge Functions corren en Deno, no en Node.js. Si vienes de Node, hay diferencias importantes que necesitas conocer.

Imports

Deno usa URLs para importar módulos en vez de node_modules:

// Node.js
import express from 'express'
 
// Deno -- importas desde URLs o desde el mapa de imports
import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'

En la práctica, Supabase ya configura un import map (un archivo que mapea nombres de paquetes a URLs) para que puedas importar las librerías de Supabase de forma limpia:

// Esto funciona en Edge Functions gracias al import map
import { createClient } from '@supabase/supabase-js'

TypeScript nativo

Deno soporta TypeScript sin configuración. No necesitas tsc, ni tsconfig.json, ni un paso de compilación. Escribes .ts y funciona.

APIs del navegador

Deno implementa APIs web estándar. fetch, Request, Response, Headers, URL, crypto -- todo funciona igual que en el browser.

// Esto funciona tal cual en Deno
const response = await fetch('https://api.ejemplo.com/datos')
const data = await response.json()

Lo que NO funciona

Algunos paquetes de npm que dependen de APIs específicas de Node.js (como fs, path, child_process) no van a funcionar directamente. La mayoría de los paquetes modernos que usan APIs web sí funcionan.

Estructura de una Edge Function

Una Edge Function mínima se ve así:

// supabase/functions/hola-mundo/index.ts
Deno.serve(async (req: Request) => {
  return new Response(
    JSON.stringify({ mensaje: 'Hola desde el edge' }),
    {
      headers: { 'Content-Type': 'application/json' },
      status: 200,
    }
  )
})

Deno.serve() recibe una función que toma un Request (el request HTTP estándar) y devuelve un Response. Es la API más simple posible para manejar HTTP.

Setup de desarrollo local

Para trabajar con Edge Functions en tu máquina necesitas el Supabase CLI y Docker.

Prerrequisitos

1. Supabase CLI instalado (lo cubrimos en la sección de CLI)
2. Docker corriendo (Supabase local usa contenedores)

Iniciar el entorno local

Si todavía no inicializas Supabase en tu proyecto:

supabase init

Esto crea la carpeta supabase/ con la configuración necesaria.

Para levantar todos los servicios locales (incluyendo el runtime de Edge Functions):

supabase start

Crear tu primera función

supabase functions new mi-funcion

Esto crea supabase/functions/mi-función/index.ts con un template básico.

Ejecutar localmente

supabase functions serve mi-funcion

Tu función queda disponible en http://localhost:54321/functions/v1/mi-función. Cada vez que modifiques el archivo, el servidor se recarga automáticamente.

Probar con curl

curl -i --location --request POST \
  'http://localhost:54321/functions/v1/mi-funcion' \
  --header 'Authorization: Bearer TU_ANON_KEY_LOCAL' \
  --header 'Content-Type: application/json' \
  --data '{"nombre": "test"}'

Resumen

En la siguiente sección vas a crear una Edge Function completa, deployarla a producción y manejar secretos y CORS.