Deploy to Vercel

Desplegar una aplicación Next.js en Vercel con configuración de producción.

Cuándo Usar

• Al desplegar una aplicación Next.js por primera vez
• Al configurar despliegues de vista previa para pull requests
• Al configurar dominios personalizados
• Al gestionar variables de entorno en producción

Entradas

• Requerido: Aplicación Next.js que compila exitosamente en local
• Requerido: Repositorio de GitHub (recomendado) o proyecto local
• Opcional: Dominio personalizado
• Opcional: Variables de entorno para producción

Procedimiento

Paso 1: Verificar la Compilación Local

npm run build

Esperado: La compilación tiene éxito sin errores.

En caso de fallo: Corrige los errores de compilación antes de desplegar. Problemas comunes: errores de TypeScript, dependencias faltantes, importaciones inválidas.

Paso 2: Instalar la CLI de Vercel

npm install -g vercel

Esperado: El comando

vercel

está disponible globalmente y

vercel --version

imprime la versión instalada.

En caso de fallo: Si ocurren errores de permisos, usa

sudo npm install -g vercel

o configura npm para usar un prefijo local al usuario. Verifica que Node.js esté instalado con

node --version

.

Paso 3: Vincular y Desplegar

# Iniciar sesión en Vercel
vercel login

# Desplegar (la primera vez: crea el proyecto)
vercel

# Sigue las indicaciones:
# - Set up and deploy? Y
# - Which scope? (selecciona tu cuenta)
# - Link to existing project? N (para proyectos nuevos)
# - Project name: my-app
# - Directory: ./
# - Override settings? N

Esperado: URL de vista previa proporcionada (p.ej.,

https://my-app-xxx.vercel.app

).

En caso de fallo: Si

vercel login

falla, verifica la conectividad a internet e intenta la autenticación por navegador. Si el despliegue falla, revisa la salida de la compilación — Vercel usa un entorno limpio, por lo que todas las dependencias deben estar en

package.json

.

Paso 4: Configurar Variables de Entorno

# Añadir variables de entorno
vercel env add DATABASE_URL production
vercel env add API_KEY production preview

# Listar variables de entorno
vercel env ls

O configura a través del panel de Vercel: Project Settings > Environment Variables.

Esperado:

vercel env ls

muestra todas las variables de entorno requeridas configuradas para los entornos correctos (production, preview, development).

En caso de fallo: Si las variables no aparecen en tiempo de ejecución, verifica que el entorno objetivo coincida (production vs preview). Vuelve a desplegar después de añadir variables — los despliegues existentes no recogen nuevas variables automáticamente.

Paso 5: Desplegar a Producción

vercel --prod

Esperado: URL de producción disponible (p.ej.,

https://my-app.vercel.app

).

En caso de fallo: Revisa los registros de despliegue con

vercel logs

o en el panel de Vercel. Los problemas comunes incluyen variables de entorno faltantes en el entorno de producción y comandos de compilación que difieren del entorno local.

Paso 6: Conectar GitHub para Auto-Despliegue (Recomendado)

1. Ve a https://vercel.com/new
2. Importa tu repositorio de GitHub
3. Vercel despliega automáticamente en:
   • Push a main → Despliegue de producción
   • Pull request → Despliegue de vista previa

Esperado: El panel de Vercel muestra el repositorio de GitHub conectado, y los pushes posteriores a main activan despliegues de producción automáticamente.

En caso de fallo: Si el repositorio no aparece en la lista de importación, verifica que la aplicación GitHub de Vercel tenga acceso al repositorio. Ve a GitHub Settings > Applications > Vercel y concede acceso.

Paso 7: Configurar Dominio Personalizado

vercel domains add my-domain.com

O a través del panel: Project Settings > Domains.

Actualiza los registros DNS según las instrucciones de Vercel (típicamente registro CNAME o A).

Esperado:

vercel domains ls

muestra el dominio personalizado como configurado, y después de la propagación del DNS (hasta 48 horas), el dominio resuelve al despliegue de Vercel.

En caso de fallo: Si el dominio muestra "Invalid Configuration", verifica que los registros DNS coincidan exactamente con las instrucciones de Vercel. Usa

dig my-domain.com

o un verificador de DNS en línea para confirmar la propagación.

Paso 8: Optimizar la Configuración

Crea

vercel.json

para configuración avanzada:

{
  "framework": "nextjs",
  "regions": ["iad1"],
  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "no-store" }
      ]
    }
  ]
}

Esperado:

vercel.json

guardado en la raíz del proyecto y el siguiente despliegue recoge la configuración (visible en los registros de compilación del panel de Vercel).

En caso de fallo: Si la configuración es ignorada, verifica que

vercel.json

sea JSON válido con

jq . vercel.json

. Consulta la documentación de Vercel para tu versión del framework, ya que algunas configuraciones pueden haberse movido a

next.config.ts

.

Validación

• npm run build

  tiene éxito en local
• El despliegue de vista previa funciona y es accesible
• El despliegue de producción sirve la aplicación correctamente
• Las variables de entorno están disponibles en producción
• El dominio personalizado resuelve (si está configurado)
• La integración con GitHub activa despliegues al hacer push

Errores Comunes

• Compilación que falla en Vercel pero no en local: Vercel usa un entorno limpio. Asegúrate de que todas las dependencias estén en

  package.json

  , no solo instaladas globalmente.
• Variables de entorno faltantes: Las variables deben añadirse a Vercel, no solo a

  .env.local

  . Los distintos entornos (production, preview, development) tienen conjuntos de variables separados.
• Incompatibilidad de versión de Node.js: Configura la versión de Node.js en Project Settings o en el campo

  engines

  de

  package.json

  .
• Despliegues grandes: Vercel tiene límites de tamaño. Usa

  .vercelignore

  para excluir archivos innecesarios.
• Tiempos de espera de rutas de API: Las funciones serverless de Vercel tienen un tiempo de espera de 10s en el plan Hobby. Optimiza o actualiza el plan.

Habilidades Relacionadas

• scaffold-nextjs-app

  — crear la aplicación a desplegar

• setup-tailwind-typescript

  — configurar estilos antes del despliegue

• configure-git-repository

  — configuración de Git para integración de auto-despliegue