npm install @supabase/server@latest y npx skills add supabase/server: guía práctica para migrar Edge Functions, Hono y agentes IA
Tiempo estimado de lectura: 4 min
- Reduce boilerplate de autenticación gracias a un modelo declarativo y SupabaseContext por petición.
- Automatiza migraciones con agentes usando npx skills add supabase/server para dar contexto y patrones a agentes de código.
- Flujo incremental y seguro: withSupabase para la mayoría de endpoints; primitives o createSupabaseContext para casos complejos.
- Soporta rotación de claves y despliegues controlados con variables plurales y canary deploys.
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/server3. 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?
- ¿Por qué necesito npx skills add supabase/server?
- ¿Cómo manejo variables de entorno y rotación de claves?
- ¿Cuándo usar withSupabase vs createSupabaseContext/primitives?
- ¿Cómo se prueban las funciones migradas?
- ¿Debo eliminar las utilidades de verificación JWT antiguas?
Respuesta: 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.
Respuesta: 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.
Respuesta: 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.
Respuesta: 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.
Respuesta: Escribe tests unitarios que mockeen el SupabaseContext para evitar llamadas de red. Realiza canary deploys para funciones críticas antes del rollout completo.
Respuesta: 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.
