Base de datos con Supabase & Deploy con Vercel

Introducción

Esta guía complementa el documento de introducción a Cursor y cubre dos pasos esenciales para que tu proyecto pase de "funciona en mi compu" a "está online y guarda datos de verdad": conectar una base de datos y publicar en Vercel.

Parte 1: Base de datos con Supabase

¿Qué es Supabase?

Supabase es una plataforma que te da una base de datos PostgreSQL lista para usar, con panel visual para ver y editar datos. Es como una planilla de Excel pero para tu app: tablas, filas, columnas, todo accesible desde tu código.

¿Por qué Supabase?

• Tiene un tier gratuito generoso para proyectos chicos.

• Panel visual donde podés ver y editar datos sin escribir código.

• Se integra muy fácil con proyectos de Next.js.

• Incluye autenticación de usuarios si la necesitás.

Setup inicial

1. Crear cuenta y proyecto

• Ir a https://supabase.com/ y crear cuenta (podés usar GitHub).

• Click en "New Project".

• Elegir nombre, contraseña de base de datos (guardarla en lugar seguro) y región (elegir la más cercana a tus usuarios).

• Esperar 2-3 minutos mientras se crea.

2. Obtener las credenciales

Una vez creado el proyecto, ir a Settings → API. Vas a necesitar dos valores:

• Project URL: algo como https://xyz123.supabase.co

• anon/public key: una key larga que empieza con eyJ...

3. Configurar en tu proyecto (opcional, lo puede hacer el agent en el punto 5 como parte del plan)

Abrir (o crear) el archivo .env.local en la raíz del proyecto y agregar:

NEXT_PUBLIC_SUPABASE_URL=https://xyz123.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...tu-key-completa

⚠️ Recordá: .env.local nunca se sube a Git. Verificá que esté en el .gitignore.

Nunca pasar estas variables en el chat, el agent deja un placeholder y lo cambias directo.

4. Instalar el cliente de Supabase (opcional, lo puede hacer el agent en el punto 5 como parte del plan)

En la terminal de Cursor:

npm install @supabase/supabase-js

5. PLAN MODE: pedirle al agente que configure la conexión con la base de datos

Prompt básico, iterar y pulir vía Plan Mode.

"Necesito reemplazar toda la data mock de nuestra app y conectarla a una base de datos. Vamos a usar Supabase para este proyecto, diseñar la integración asegurando que toda data generada se guarda y persiste en la base de datos, y que toda la data que se muestra viene de allí. Definir bien todas las tablas correspondientes, darme el SQL code para cada migración, y considerar el diseño de una buena política de RLS. Por ahora no hacer auth, lo haremos en una etapa II. Considerar @cursor.rules"

Crear tablas en Supabase

Opción A: Desde el panel visual

• Ir a Table Editor en el dashboard de Supabase.

• Click en "New Table".

• Definir nombre y columnas (nombre, tipo, si es requerido).

• Supabase crea automáticamente una columna id y created_at.

Opción B: Pedirle al agente que genere el SQL

Prompt recomendado:

"Necesito una tabla 'contactos' con campos: nombre (texto), email (texto), mensaje (texto largo), fecha de creación. Generame el SQL para crearla en Supabase."

Luego copiás ese SQL y lo ejecutás en Supabase → SQL Editor.

Row Level Security (RLS)

Supabase viene con seguridad activada por defecto. Si al intentar leer o escribir datos te devuelve un array vacío o error, probablemente necesitás configurar políticas.

Solución rápida para desarrollo:

• Ir a Authentication → Policies.

• En tu tabla, agregar una policy que permita las operaciones que necesitás.

Prompt para el agente:

"Me devuelve un array vacío al leer de Supabase. ¿Puede ser un tema de RLS? Explicame cómo configurar una policy para permitir lectura pública."

---

Autenticación con Supabase

Autenticación es el sistema que permite a los usuarios registrarse, iniciar sesión y que tu app sepa "quién es quién". Supabase incluye esto out-of-the-box, sin necesidad de construirlo desde cero.

Con autenticación podés:

• Permitir que usuarios creen cuentas y accedan a sus datos.

• Proteger rutas o páginas para que solo las vean usuarios logueados.

• Guardar datos asociados a cada usuario (ej: "mis favoritos", "mi perfil").

• Controlar permisos: qué puede ver o hacer cada usuario.

Setup inicial

1. Habilitar proveedores de autenticación

En el dashboard de Supabase, ir a Authentication → Providers. Acá elegís cómo van a poder loguearse tus usuarios.

2. Prompt básica para Cursor

Una vez que tenés Supabase conectado (ver sección anterior), podés pedirle al agente:

"Necesito implementar autenticación en este proyecto usando Supabase Auth. Quiero un flujo de registro e inicio de sesión con email y contraseña. Creá los componentes necesarios (formulario de login, registro, y un contexto o hook para manejar el estado del usuario logueado). Usá las variables de entorno que ya tengo configuradas."

Esta prompt genera la estructura base. A partir de ahí podés iterar:

"Agregá un botón de logout en el header que solo aparezca si el usuario está logueado." o "Mostrá el email del usuario logueado en la navbar."

Métodos de autenticación: qué elegir

Email y contraseña

• El clásico: el usuario pone su email, elige una contraseña, y listo.

• Supabase maneja todo: encriptación, recuperación de contraseña, verificación de email.

• Requiere que configures los templates de email en Supabase (Authentication → Email Templates).

Consideraciones:

• Tenés que decidir si requerís verificación de email antes de dejar entrar al usuario.

• Supabase tiene rate limits para evitar spam de registros.

Prompt:

"Configurá auth con email/password. Que después de registrarse el usuario tenga que verificar su email antes de poder entrar."

Google Sign-In (u otros proveedores OAuth)

• El usuario hace click en "Continuar con Google" y listo, sin crear contraseña.

• Menos fricción = más conversiones en registro.

• También disponible: GitHub, Apple, Facebook, Twitter, etc.

Configuración en Supabase:

1. Ir a Authentication → Providers → Google.

2. Necesitás crear credenciales en Google Cloud Console (Supabase te da un link con instrucciones).

3. Pegar el Client ID y Client Secret en Supabase.

Prompt:

"Agregá la opción de login con Google además del email/password. Que ambos botones estén en la misma pantalla de login."

Consideraciones:

• OAuth requiere configurar URLs de callback. Supabase te da la URL que tenés que poner en Google Cloud.

• En desarrollo usás localhost, en producción tu dominio de Vercel. Tenés que agregar ambos.

Rutas protegidas

Una vez que tenés auth funcionando, vas a querer que ciertas páginas solo sean accesibles para usuarios logueados.

Concepto básico:

• Ruta pública: cualquiera puede verla (ej: landing page, pricing).

• Ruta protegida: solo usuarios logueados (ej: dashboard, mi cuenta).

Prompt para implementar (parte del plan inicial):

"Protegé las rutas /dashboard y /settings para usuarios logueados. Si no está logueado, redirigí a /login. Creá el middleware o componente necesario."

---

Configuración de URLs (Auth)

Supabase necesita saber a qué URLs puede redirigir después del login. Esto es crítico para que funcione en desarrollo Y en producción.

Configurar en Supabase:

1. Ir a Authentication → URL Configuration.

2. Configurar:

Desarrollo: a) Site URL : http://localhost:3000 | b) Redirect URLs http://localhost:3000/**

Producción: a) Site URL https://tu-app.vercel.app | b) Redirect URLs https://tu-app.vercel.app/**

¿Qué es cada cosa?

• Site URL: La URL principal de tu app. Supabase la usa como base para emails de confirmación y recuperación de contraseña.

• Redirect URLs: Lista de URLs permitidas para redirigir después de login/signup. El /** permite cualquier subruta.

Para OAuth (Google, GitHub, etc.):

Además de configurar en Supabase, tenés que agregar la callback URL en el proveedor:

• Ir a Google Cloud Console (o el proveedor que uses).

• En Authorized redirect URIs agregar: https://tu-proyecto.supabase.co/auth/v1/callback

⚠️ Error común: OAuth funciona en local pero no en producción → falta agregar la URL de Vercel en el proveedor.

Prompt si algo falla:

"El redirect después del login no funciona en producción. ¿Están bien configuradas las URLs en Supabase y en el proveedor OAuth?"

---

Conectar auth con la base de datos

El caso más común: que cada usuario solo vea sus propios datos.

RLS con usuarios:

Supabase permite policies que usan el ID del usuario logueado.

Prompt:

"Tengo una tabla 'proyectos' con campo user_id. Configurá RLS para que cada usuario solo vea y edite sus propios proyectos."

Guardar user_id al crear datos:

Prompt:

"Al crear un proyecto, guardá automáticamente el user_id del usuario logueado."

Parte 2: Deploy con Vercel

¿Qué es Vercel?

Vercel es una plataforma que toma tu código de GitHub y lo publica en internet automáticamente. Cada vez que hacés push a main, Vercel detecta el cambio y actualiza tu sitio.

¿Por qué Vercel?

• Hecho por los creadores de Next.js, así que la integración es perfecta.

• Tier gratuito muy generoso para proyectos personales.

• Deploy automático: push a GitHub = sitio actualizado.

• Te da una URL pública inmediatamente.

Setup inicial

1. Crear cuenta

• Ir a https://vercel.com/ y crear cuenta con GitHub (recomendado para que se conecten automáticamente).

2. Importar proyecto

• Click en "Add New" → "Project".

• Seleccionar el repositorio de GitHub que querés deployar.

• Vercel detecta automáticamente que es un proyecto Next.js.

3. Configurar variables de entorno

Antes de deployar, tenés que agregar las mismas variables que tenés en .env.local:

• En la pantalla de configuración, buscar "Environment Variables".

• Agregar cada variable con su nombre y valor:

  • NEXT_PUBLIC_SUPABASE_URL

  • NEXT_PUBLIC_SUPABASE_ANON_KEY

  • (y cualquier otra que uses)

⚠️ Importante: Las variables en Vercel no se actualizan automáticamente. Si cambiás una key, tenés que actualizarla manualmente en Vercel y hacer redeploy.

4. Deploy

• Click en "Deploy".

• Esperar 1-2 minutos.

• Vercel te da una URL tipo tu-proyecto.vercel.app.

Flujo de trabajo post-setup

Una vez configurado, el flujo es automático:

1. Hacés cambios en Cursor.

2. Commit + Push a GitHub.

3. Vercel detecta el push y hace deploy automático.

4. En 1-2 minutos, los cambios están online.

Podés ver el estado de cada deploy en el dashboard de Vercel.

Preview Deployments

Vercel tiene una feature muy útil: cada branch y cada Pull Request tiene su propia URL de preview.

• Si creás una rama feature/nuevo-header y hacés push, Vercel genera una URL tipo tu-proyecto-git-feature-nuevo-header.vercel.app.

• Esto te permite probar cambios antes de mergear a main.

• Es el equivalente al ambiente de Staging que mencionamos antes.

Errores comunes y soluciones

"Build failed"

• Revisar los logs de build en Vercel (te muestra exactamente qué falló).

• Error típico: funciona en local pero falla en Vercel → generalmente es una variable de entorno que falta.

• Prompt para el agente: "El build de Vercel falla con este error: [pegar error]. ¿Qué puede ser?"

"La base de datos no conecta en producción"

• Verificar que las variables de Supabase están configuradas en Vercel.

• Verificar que no hay typos en los nombres de las variables.

• En Supabase, revisar que el proyecto no esté pausado (en tier gratuito se pausa por inactividad).

"Funciona en local pero no en producción"

• 90% de las veces es una variable de entorno faltante.

• Comparar .env.local con lo configurado en Vercel.

Checklist de seguridad para producción

Antes de compartir tu URL con usuarios reales:

Variables de entorno:

• Ninguna API key está hardcodeada en el código.

• .env.local está en .gitignore.

• Las variables sensibles en Vercel no tienen el prefijo NEXT_PUBLIC_ (a menos que realmente necesiten ser públicas).

Base de datos:

• RLS está configurado en Supabase.

• No estás exponiendo datos que no deberías en el frontend.

• La contraseña de la base de datos es fuerte y está guardada en lugar seguro.

Prompt de auditoría para el agente:

"Revisá el proyecto y decime si hay algún riesgo de seguridad antes de deployar a producción. Especialmente verificá que no haya keys expuestas y que los endpoints estén protegidos."

Prompts útiles para todo el flujo

Setup de Supabase:

• "Configurá la conexión a Supabase en este proyecto usando las variables de entorno."

• "Creá el SQL para una tabla de [describir lo que necesitás]."

Integración con la app:

• "Creá un formulario que guarde datos en la tabla X de Supabase."

• "Mostrá los datos de la tabla X en una lista."

Troubleshooting:

• "El build de Vercel falla con este error: [error]. ¿Cómo lo soluciono?"

• "Supabase me devuelve un array vacío. ¿Qué puede estar pasando?"

• "Revisá si hay algún problema de seguridad antes de ir a producción."