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

¿Qué hace npm install @supabase/server@latest?

Instalar @supabase/server introduce un modelo declarativo de control de acceso y un SupabaseContext por petición, con clientes ctx.supabase y ctx.supabaseAdmin, verificación de JWT asimétrica y utilidades como withSupabase y createSupabaseContext.

¿Por qué necesito npx skills add supabase/server?

npx skills add supabase/server aporta la superficie de la API y patrones a agentes de código, permitiendo que escaneen repos, identifiquen inicializaciones antiguas y automaticen refactors de forma segura.

¿Cómo manejo variables de entorno y rotación de claves?

Cambia a variables plurales como SUPABASE_PUBLISHABLE_KEYS y SUPABASE_SECRET_KEYS para soportar rotación. Valida la inyección en plataformas como Supabase CLI, Vercel o Cloudflare antes del despliegue.

¿Cuándo usar withSupabase vs createSupabaseContext/primitives?

Usa withSupabase por defecto para claridad y seguridad. Emplea createSupabaseContext o primitives cuando necesites combinar múltiples modos de auth en una sola función o manipular headers de forma estricta.

¿Cómo se prueban las funciones migradas?

Escribe tests unitarios que mockeen el SupabaseContext para evitar llamadas de red. Realiza canary deploys para funciones críticas antes del rollout completo.

¿Debo eliminar las utilidades de verificación JWT antiguas?

Sí: una vez migradas las funciones a @supabase/server, las utilidades compartidas de verificación JWT que replican lógica ya gestionada por el paquete dejan de ser necesarias y pueden eliminarse tras validar el comportamiento.