Guía para migrar funciones Edge y simplificar autenticación en Supabase

Introducción

npm install @supabase/server@latest y npx skills add supabase/server son las dos acciones que debes ejecutar si quieres adoptar el nuevo flujo de trabajo de Supabase: un paquete que elimina el boilerplate de autenticación y un “skill” que da contexto a agentes de código. En las primeras líneas: estos comandos son el punto de partida para migrar funciones Edge, automatizar refactors con agentes y levantar APIs Hono seguras en minutos.

Resumen rápido (lectores con prisa)

Instala @supabase/server para obtener contexto de autenticación y clientes por petición. Añade el skill supabase/server para que agentes de código puedan identificar y actualizar inicializaciones antiguas. Usa withSupabase para la mayoría de endpoints; recurre a primitives o createSupabaseContext para casos compuestos.

npm install @supabase/server@latest — qué instala y qué te da

Instalar @supabase/server provoca algo más que añadir una dependencia: introduce un modelo declarativo para control de acceso y un SupabaseContext listo para usar. Tras la instalación obtienes primitives y wrappers que:

• Verifican JWT asimétricos sin jose/JWKS manual.
• Inicializan dos clientes por petición: ctx.supabase (usuario, respeta RLS) y ctx.supabaseAdmin (service role).
• Inyectan userClaims, jwtClaims y authMode en el contexto.
• Ofrecen withSupabase (wrapper), createSupabaseContext (imperativo) y primitives en @supabase/server/core.

Documentación oficial: Documentación oficial y repo: Repositorio en GitHub

npx skills add supabase/server — por qué lo necesitas si usas agentes

npx skills add supabase/server alimenta a herramientas como Claude Code, Codex o Cursor con la superficie de la API, patrones de adaptadores y rutas de migración. Resultado práctico: un agente puede escanear tu repo, identificar inicializaciones antiguas, reemplazarlas por withSupabase y migrar claves a las nuevas variables sin equivocarse.

Prompts útiles (ejemplos que puedes dar al agente):

• “Analyze all Edge Functions and plan a full migration to use the new API keys with @supabase/server”
• “Scaffold a Hono REST API with CRUD for todos using per-route auth”
• “Create an Edge Function that accepts user or secret auth, reads profile with RLS and writes audit logs with admin client”

Plan de migración: pasos prácticos y ordenados

1. Auditoría rápida

Busca patrones repetidos (creación de clientes, verificación JWT, _shared/*.ts).

2. Añade la dependencia e instala el skill

Ejecuta los comandos:

npm install @supabase/server@latest
npx skills add supabase/server

3. Sustitución incremental

• Reemplaza inicializaciones manuales por withSupabase({ auth }) en funciones individuales.
• Para funciones multifunción, usa createSupabaseContext o primitives (verifyAuth, createContextClient).

4. Variables de entorno

Cambia a formas plurales si es necesario: SUPABASE_PUBLISHABLE_KEYS y SUPABASE_SECRET_KEYS (soporta rotación). Valida inyección en plataformas (Supabase CLI, Vercel, Cloudflare).

5. Test y rollout

• Tests unitarios sobre handlers con contexto mockeado.
• Canary deploy para funciones críticas.

6. Limpieza

• Elimina utilidades compartidas de verificación JWT (ya no necesarias).
• Actualiza docs internas y runbooks.

Ejemplo rápido: Hono + withSupabase (CRUD /todos)

El adaptador Hono inyecta el contexto en c.var.supabaseContext:

import { withSupabase } from '@supabase/server/adapters/hono'
import { Hono } from 'hono'

const app = new Hono()

app.get('/todos', withSupabase({ auth: 'user' }), async (c) => {
  const { supabase } = c.var.supabaseContext
  const { data } = await supabase.from('todos').select()
  return c.json(data)
})

export default { fetch: app.fetch }

Per-route auth es explícito y visible en la firma: mantenimiento y auditoría mucho más sencillos.

Edge Function protegida con operaciones admin (patrón recomendado)

Cuando necesitas dual-mode auth (usuario o secret) y escribir logs de auditoría:

• Declara auth: ['user','secret'].
• Usa ctx.supabase para lecturas que respetan RLS.
• Usa ctx.supabaseAdmin para escribir auditoría o tareas privilegiadas.

Si necesitas control imperativo sobre errores, usa createSupabaseContext:

import { createSupabaseContext } from 'npm:@supabase/server'

const { data: ctx, error } = await createSupabaseContext(req, { auth: ['user','secret'] })
if (error) return Response.json({ error: error.message }, { status: error.status })

Recomendaciones prácticas y criterios técnicos

• Prioriza withSupabase para la mayoría de endpoints: claridad y seguridad por defecto.
• Usa primitives solo cuando debas combinar múltiples auth en una función o manipular headers de forma estricta.
• Aprovecha npx skills para automatizar auditoría y migración; reduce errores humanos en refactors masivos.
• Mantén tests que mockeen SupabaseContext para evitar dependencia de la red en unit tests.
• Revisa el repo y docs oficiales para edge-cases y actualizaciones: Repositorio en GitHub y Documentación oficial

Conclusión

Instalar @supabase/server y añadir el skill cambia la ergonomía del backend: elimina la repetición, reduce superficie de ataque y hace tus funciones Edge predecibles para humanos y agentes por igual. Empieza migrando funciones críticas con canary deploys, automatiza el resto con el skill y conserva primitives para los casos realmente especiales. El resultado: menos fontanería, más foco en la lógica que aporta valor.

Mención: Dominicode Labs

Si estás planificando automatizaciones o migraciones con agentes, puede resultar útil ver recursos y experimentos aplicados a workflows y agentes. Más información y proyectos relacionados en Dominicode Labs.

FAQ