Deploy en Vercel: guía completa para NextJS

Hacer deploy en Vercel de tu aplicación NextJS es el camino más directo para llevar tu proyecto a producción. Vercel es la plataforma creada por el equipo detrás de NextJS, lo que significa que cada feature nueva tiene soporte desde el día cero: Server Components, ISR, Edge Functions, Image Optimization. No hay configuración especial, no hay parches, no hay incompatibilidades.

En esta guía vas a cubrir todo el proceso, desde crear tu cuenta hasta monitorear tu aplicación en producción. Si ya tienes tu proyecto listo y solo necesitas lanzarlo, esto es lo que necesitas.

por qué Vercel para NextJS

Existen alternativas como AWS, Railway o un VPS con Docker. Todas funcionan. Pero Vercel tiene ventajas concretas cuando trabajas con NextJS:

• Zero config: Detecta que tu proyecto es NextJS y configura todo automáticamente
• Preview deployments: Cada pull request tiene su propia URL para probar
• Edge network: Tu sitio se sirve desde el nodo más cercano al usuario
• Integración nativa: ISR, Server Actions, Edge Functions, Image Optimization funcionan sin configuración extra
• SSL gratuito: Certificados automaticos para todos los dominios
• Plan gratuito generoso: Para proyectos personales y blogs no necesitas pagar

Requisitos previos

Antes de empezar necesitas:

1. Un proyecto NextJS funcionando en local (npm run dev sin errores)
2. Un repositorio en GitHub (también soporta GitLab y Bitbucket)
3. Una cuenta de Vercel (la creas en el siguiente paso)

Si tu proyecto usa MDX y tienes problemas con Turbopack durante el build, revisa la solucion al error de Turbopack con MDX en NextJS antes de continuar. Resuelve errores locales primero; si el build no pasa en tu maquina, tampoco pasara en Vercel.

Paso 1: Crear cuenta en Vercel y conectar repositorio

Estructura de permisos

Cuando conectas Vercel con GitHub, puedes elegir entre:

• Todos los repositorios: Vercel tiene acceso a todos tus repos (presente y futuro)
• Repositorios seleccionados: Solo das acceso a los repos que necesitas

La segunda opción es la recomendada. Otorga acceso solo al repositorio que vas a desplegar.

Paso 2: Configuración del proyecto

Una vez importado el repositorio, Vercel muestra la pantalla de configuración antes del primer deploy.

Framework Preset

Vercel detecta NextJS automáticamente leyendo tu package.json. Si por alguna razon no lo detecta, selecciona "Next.js" del dropdown.

// Vercel busca estas dependencias en tu package.json
{
  "dependencies": {
    "next": "16.0.0",
    "react": "19.0.0",
    "react-dom": "19.0.0"
  }
}

Build Settings

Los valores por defecto son correctos para la gran mayoria de proyectos:

Root Directory

Si tu repositorio es un monorepo y tu app NextJS esta en un subdirectorio:

mi-monorepo/
├── packages/
│   ├── ui/
│   └── shared/
├── apps/
│   ├── web/          <-- Tu app NextJS esta aquí
│   └── api/
└── package.json

Configura el Root Directory como apps/web. Vercel ejecutara el build desde esa carpeta.

Paso 3: Variables de entorno

Este es el paso que más problemas causa en los primeros deployments. Tu aplicación probablemente usa variables de entorno que existen en tu .env.local pero no estan en Vercel.

Agregar variables en el dashboard

DATABASE_URL=postgresql://user:password@host:5432/db
NEXT_PUBLIC_SITE_URL=https://tudominio.com
API_SECRET_KEY=tu-clave-secreta
RESEND_API_KEY=re_xxxxxxxxxxxx

Variables comunes que necesitas configurar

# Base de datos
DATABASE_URL=postgresql://...
 
# URL del sitio (necesaria para sitemaps, OG images, etc.)
NEXT_PUBLIC_SITE_URL=https://tudominio.com
 
# Servicios de email
RESEND_API_KEY=re_...
 
# Analytics
NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX
 
# Cualquier API key que uses
STRIPE_SECRET_KEY=sk_...
STRIPE_PUBLISHABLE_KEY=pk_...

Diferencia entre variables publicas y privadas

// Variable pública - accesible en el navegador
// Prefijo: NEXT_PUBLIC_
process.env.NEXT_PUBLIC_SITE_URL  // OK en client y server
 
// Variable PRIVADA - solo accesible en el servidor
// Sin prefijo NEXT_PUBLIC_
process.env.DATABASE_URL          // Solo en server
process.env.API_SECRET_KEY        // Solo en server

Las variables sin prefijo NEXT_PUBLIC_ nunca llegan al bundle del cliente. Esto es crítico para la seguridad. No pongas claves secretas con el prefijo NEXT_PUBLIC_.

Paso 4: Primer deploy

Con el repositorio conectado y las variables configuradas, haz clic en "Deploy". Vercel ejecuta el siguiente proceso:

1. Clona tu repositorio
2. Instala dependencias (npm install / yarn / pnpm install)
3. Ejecuta el build (next build)
4. Despliega el resultado en la edge network
5. Asigna una URL única (tu-proyecto.vercel.app)

Build logs

Mientras Vercel ejecuta el build, puedes ver los logs en tiempo real. Esto es lo que verás en un build exitoso:

Cloning github.com/tu-usuario/tu-proyecto...
Installing dependencies...
npm warn deprecated some-package@1.0.0
added 487 packages in 12s
 
Running "npm run build"
> next build
 
   Creating an optimized production build ...
   Compiled successfully
   Collecting page data ...
   Generating static pages (0/14) ...
   Generating static pages (3/14)
   Generating static pages (7/14)
   Generating static pages (10/14)
   Generating static pages (14/14)
   Finalizing page optimization ...
 
Route (app)                    Size     First Load JS
┌ ○ /                          5.12 kB    87.3 kB
├ ○ /about                     1.34 kB    83.5 kB
├ ● /blog                      3.21 kB    85.4 kB
├ ● /blog/[slug]               2.87 kB    85.0 kB
└ ○ /api/health                0 B        0 B
 
○  (Static)   prerendered as static content
●  (SSG)      prerendered as static HTML (uses getStaticProps)
 
Build completed in 32s
Deploying to production...

Paso 5: Custom domains y DNS

La URL por defecto (tu-proyecto.vercel.app) funciona, pero quieres usar tu dominio.

Agregar un dominio personalizado

ns1.vercel-dns.com
ns2.vercel-dns.com

Tipo    Nombre    Valor
A       @         76.76.21.21
CNAME   www       cname.vercel-dns.com.

Configurar www vs non-www

Vercel te permite elegir cuál es el dominio principal:

• tudominio.com (sin www) -- la opción más común
• www.tudominio.com (con www)

El dominio que no elijas como principal redirige automáticamente al principal con un 308.

SSL automático

Vercel genera certificados SSL (Let's Encrypt) automáticamente para todos los dominios. No necesitas configurar nada. El certificado se renueva solo antes de expirar.

https://tudominio.com         ← SSL activo
https://www.tudominio.com     ← SSL activo
https://tu-proyecto.vercel.app ← SSL activo

Paso 6: Preview deployments

Esta es una de las mejores funcionalidades de Vercel. Cada vez que creas un pull request en GitHub, Vercel genera un deployment con su propia URL.

cómo funciona

1. Creas una rama: feature/nueva-sección
2. Haces push y abres un PR en GitHub
3. Vercel detecta el PR automáticamente
4. Ejecuta el build con esa rama
5. Despliega en una URL única: tu-proyecto-abc123.vercel.app
6. Agrega un comentario en el PR con el link

Para que sirve

• Revisar cambios visualmente antes de mergear
• Probar en dispositivos reales sin deploy a producción
• Compartir con diseño o QA para feedback
• Verificar que el build pasa antes de mergear

Variables de entorno en Preview

Las variables de entorno de Preview pueden ser diferentes a las de Production. Esto es útil cuándo necesitas:

# Production
DATABASE_URL=postgresql://prod-host:5432/prod-db
NEXT_PUBLIC_SITE_URL=https://tudominio.com
 
# Preview
DATABASE_URL=postgresql://staging-host:5432/staging-db
NEXT_PUBLIC_SITE_URL=https://tu-proyecto-preview.vercel.app

Paso 7: Debugging de errores comunes

Error: Build failed

El error más frecuente. Revisa los build logs en el dashboard de Vercel.

Causas comunes:

# 1. Variable de entorno faltante
Error: DATABASE_URL is not defined
# Solución: Agrega la variable en Vercel dashboard
 
# 2. Error de TypeScript
Type error: Property 'x' does not exist on type 'y'
# Solución: Corrige el error de tipos en tu código
 
# 3. Dependencia faltante
Module not found: Can't resolve 'some-package'
# Solución: Verifica que este en package.json (no solo devDependencies)
 
# 4. ESLint errors tratados como errores de build
Lint errors found in the listed files
# Solución: Corrige los errores de lint o ajusta la config

Error: 500 Internal Server Error en producción

Tu build paso pero la aplicación falla al ejecutarse.

// Causa común: acceder a variable de entorno que no existe
const url = process.env.API_URL // undefined en Vercel
 
// Solución: verifica que la variable existe
if (!process.env.API_URL) {
  throw new Error('API_URL no esta configurada')
}

Error: página muestra contenido viejo

# Si usas ISR y el contenido no se actualiza:
# 1. Verifica tu configuración de revalidate
export const revalidate = 3600 // Revalida cada hora
 
# 2. Fuerza revalidación desde el dashboard
# Settings > Data Cache > Purge All
 
# 3. O usa on-demand revalidation
# POST /api/revalidate?path=/blog/mi-post

Error: imágenes no cargan

// next.config.ts
const nextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'tu-cdn.com', // Agrega cada dominio externo
      },
      {
        protocol: 'https',
        hostname: 'images.unsplash.com',
      },
    ],
  },
}
 
export default nextConfig

Error: Timeout en funciones serverless

# Error en logs:
FUNCTION_INVOCATION_TIMEOUT
 
# Las funciones serverless tienen un límite de 10 segundos (plan Hobby)
# y 60 segundos (plan Pro)

Soluciones:

// 1. Optimiza tu consulta a la base de datos
const posts = await db.post.findMany({
  select: { id: true, title: true, slug: true }, // Solo los campos necesarios
  take: 20, // Limita los resultados
})
 
// 2. Usa Edge Functions para operaciones rapidas
export const runtime = 'edge' // En tu route handler
 
// 3. Implementa caching
export const revalidate = 3600 // No recalcules cada request

Paso 8: Optimizaciones avanzadas

Edge Functions

Las Edge Functions ejecutan tu código en el nodo más cercano al usuario, reduciendo la latencia.

// app/api/hello/route.ts
export const runtime = 'edge'
 
export async function GET() {
  return new Response(JSON.stringify({ message: 'Hola desde el edge' }), {
    headers: { 'content-type': 'application/json' },
  })
}

cuándo usar Edge Functions:

• APIs que necesitan baja latencia
• Middleware de autenticación
• Redirects y rewrites dinámicos
• Personalización por región

Cuando NO usar Edge Functions:

• Consultas a base de datos que solo existen en una región
• Operaciones que necesitan Node.js APIs completas
• Procesos que requieren más de 30 segundos

ISR (Incremental Static Regeneration)

ISR te permite tener páginas estáticas que se actualizan automáticamente:

// app/blog/[slug]/page.tsx
export const revalidate = 3600 // Regenera cada hora
 
export default async function BlogPost({ params }: { params: { slug: string } }) {
  const post = await getPost(params.slug)
 
  return (
    <article>
      <h1>{post.title}</h1>
      <div>{post.content}</div>
    </article>
  )
}

Ventajas de ISR en Vercel:

• Primera visita sirve la versión cacheada (rápido)
• En background regenera la página
• La siguiente visita recibe la versión actualizada
• Sin downtime durante la regeneración

On-Demand Revalidation

Si necesitas actualizar una página inmediatamente (por ejemplo, cuando publicas un post nuevo):

// app/api/revalidate/route.ts
import { revalidatePath } from 'next/cache'
import { NextRequest } from 'next/server'
 
export async function POST(request: NextRequest) {
  const { path, secret } = await request.json()
 
  // Verificar token de seguridad
  if (secret !== process.env.REVALIDATION_SECRET) {
    return new Response('Unauthorized', { status: 401 })
  }
 
  revalidatePath(path)
  return new Response(JSON.stringify({ revalidated: true }))
}

Uso:

curl -X POST https://tudominio.com/api/revalidate \
  -H "Content-Type: application/json" \
  -d '{"path": "/blog/mi-post", "secret": "tu-token-secreto"}'

Image Optimization

NextJS con Vercel optimiza imágenes automáticamente. Sirve formatos modernos (WebP, AVIF) y redimensiona según el dispositivo:

// Componente con optimización automática
import Image from 'next/image'
 
export function HeroImage() {
  return (
    <Image
      src="/hero.jpg"
      alt="Hero de mi sitio"
      width={1200}
      height={630}
      priority // Carga inmediata para LCP
      quality={85}
    />
  )
}

Lo que Vercel hace por ti:

• Convierte a WebP/AVIF automáticamente
• Redimensiona según el sizes prop
• Cachea las imágenes optimizadas en el edge
• Lazy loading por defecto (excepto con priority)

// next.config.ts -- configurar dominios de imágenes externas
const nextConfig = {
  images: {
    formats: ['image/avif', 'image/webp'],
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'images.unsplash.com',
      },
    ],
  },
}
 
export default nextConfig

Paso 9: Monitoreo básico

Vercel Analytics

Vercel ofrece analytics integrados que miden Web Vitals reales de tus usuarios:

# Instala el paquete
npm install @vercel/analytics

// app/layout.tsx
import { Analytics } from '@vercel/analytics/react'
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="es">
      <body>
        {children}
        <Analytics />
      </body>
    </html>
  )
}

Web Vitals que Vercel mide

Speed Insights

además de Analytics, Vercel ofrece Speed Insights para un análisis más detallado:

npm install @vercel/speed-insights

// app/layout.tsx
import { Analytics } from '@vercel/analytics/react'
import { SpeedInsights } from '@vercel/speed-insights/next'
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="es">
      <body>
        {children}
        <Analytics />
        <SpeedInsights />
      </body>
    </html>
  )
}

Logs de funciones

Para depurar errores en producción:

1. Ve a tu proyecto en Vercel > Logs
2. Filtra por tipo: Functions, Edge, Build
3. Cada invocación de función muestra el request, response y cualquier console.log o error

// Los console.log en Server Components aparecen en los logs de Vercel
export default async function Page() {
  console.log('Esta línea aparece en Vercel Logs')
  const data = await fetchData()
  console.log('Data recibida:', data.length, 'items')
  return <div>...</div>
}

Paso 10: Automatización y CI/CD

Deploy automático

Por defecto, Vercel ejecuta un deploy cada vez que:

• Haces push a main/master: Deploy a producción
• Haces push a otra rama: Preview deployment
• Se mergea un PR: Deploy a producción (si es a main)

No necesitas configurar GitHub Actions ni ningún CI adicional. Vercel se encarga de todo.

Ignorar builds innecesarios

Si haces un push que no debería disparar un build (por ejemplo, cambios solo en el README):

# En tu commit message, agrega:
git commit -m "actualizar README [skip ci]"

O configura en Vercel > Settings > Git:

# Ignored Build Step
# Solo construye si hay cambios en app/ o content/
git diff --quiet HEAD^ HEAD -- app/ content/ lib/ components/

Proteger la rama de producción

Configuración recomendada en GitHub:

1. Ve a Settings > Branches en tu repositorio
2. Agrega una regla para main
3. Activa "Require status checks to pass before merging"
4. Selecciona "Vercel" como check requerido

Esto asegura que nadie puede mergear a main si el build de Vercel falla.

Configuración completa de next.config.ts para Vercel

Esta es una configuración de next.config.ts optimizada para deploy en Vercel:

// next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  // Optimizaciones de imágenes
  images: {
    formats: ['image/avif', 'image/webp'],
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'images.unsplash.com',
      },
    ],
  },
 
  // Headers de seguridad
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          {
            key: 'X-Frame-Options',
            value: 'DENY',
          },
          {
            key: 'X-Content-Type-Options',
            value: 'nosniff',
          },
          {
            key: 'Referrer-Policy',
            value: 'origin-when-cross-origin',
          },
          {
            key: 'X-DNS-Prefetch-Control',
            value: 'on',
          },
        ],
      },
    ]
  },
 
  // Redirects
  async redirects() {
    return [
      {
        source: '/old-page',
        destination: '/new-page',
        permanent: true, // 308
      },
    ]
  },
}
 
export default nextConfig

Si tu proyecto genera un sitemap automáticamente, Asegúrate de que la URL base este correcta en producción. Revisa la guía de sitemap automatico en NextJS para configurarlo.

Checklist antes de hacer deploy

Antes de hacer tu primer deploy a producción, verifica estos puntos:

Build y código

• npm run build pasa sin errores en local
• No hay warnings de TypeScript críticos
• ESLint no reporta errores (solo warnings tolerables)
• Todas las páginas cargan correctamente en local

Variables de entorno

• Todas las variables de .env.local estan en Vercel
• Las variables con NEXT_PUBLIC_ son las correctas para producción
• La NEXT_PUBLIC_SITE_URL apunta a tu dominio real
• Ninguna clave secreta tiene el prefijo NEXT_PUBLIC_

SEO y metadata

• Cada página tiene title y description unicos
• OG images configuradas
• robots.txt permite el crawleo
• sitemap.xml genera URLs con el dominio de producción

Performance

• imágenes usan el componente Image de NextJS
• Fonts estan configurados con next/font
• No hay bundles de JavaScript innecesariamente grandes

Estructura de un proyecto listo para Vercel

mi-proyecto/
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   ├── sitemap.ts
│   ├── robots.ts
│   ├── blog/
│   │   ├── [slug]/page.tsx
│   │   └── page.tsx
│   └── api/
│       └── revalidate/route.ts
├── components/
├── content/
│   └── blog/
├── lib/
├── public/
│   ├── favicon.ico
│   └── og-default.png
├── .env.local          (NO subir a GitHub)
├── .env.example        (SI subir - sin valores reales)
├── .gitignore
├── next.config.ts
├── package.json
├── tsconfig.json
└── vercel.json         (opcional)

El archivo vercel.json (opcional)

Para la mayoria de proyectos NextJS no necesitas un vercel.json. Pero si necesitas configuración específica:

{
  "framework": "nextjs",
  "regions": ["iad1"],
  "crons": [
    {
      "path": "/api/cron/cleanup",
      "schedule": "0 0 * * *"
    }
  ],
  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [
        {
          "key": "Access-Control-Allow-Origin",
          "value": "https://tudominio.com"
        }
      ]
    }
  ]
}

Preguntas frecuentes

¿Puedo hacer deploy sin GitHub?

Si. Vercel tiene un CLI que te permite desplegar directamente desde tu terminal:

# Instalar Vercel CLI
npm install -g vercel
 
# Deploy
vercel
 
# Deploy a producción
vercel --prod

Pero la integración con GitHub es la forma recomendada porque te da preview deployments automaticos y rollback fácil.

¿Cómo hago rollback a un deploy anterior?

En el dashboard de Vercel > Deployments, cada deploy tiene un boton de "Promote to Production". Haz clic en un deploy anterior para revertir. El rollback es instantaneo porque Vercel mantiene todas las versiones.

¿Puedo tener múltiples dominios apuntando al mismo proyecto?

Si. Puedes agregar múltiples dominios en Settings > Domains. Todos apuntan al mismo proyecto. Vercel recomienda definir uno como principal y que los demas redirijan a ese.

tudominio.com           → Principal
www.tudominio.com       → Redirect a tudominio.com
tudominio.mx            → Redirect a tudominio.com
old-dominio.com         → Redirect a tudominio.com

¿Cuánto cuesta Vercel para proyectos reales?

Para un blog o portafolio personal, el plan Hobby es más que suficiente.

Conclusion

El deploy de NextJS en Vercel se reduce a tres pasos fundamentales:

1. Conecta tu repositorio de GitHub
2. Configura las variables de entorno
3. Haz clic en Deploy

A partir de ahi, cada push a tu rama principal despliega automáticamente a producción. Cada pull request genera un preview deployment. SSL, optimización de imágenes y CDN global vienen incluidos sin configuración.

Lo que diferencia a Vercel de otras plataformas es la integración nativa con NextJS. Features como ISR, Edge Functions y Server Components funcionan tal cuál la documentación los describe, sin parches ni workarounds.

Si todavia no has configurado el SEO básico de tu sitio, este es un buen momento. Revisa la guia de sitemap automatico en NextJS y Asegúrate de que Google pueda indexar tu sitio correctamente desde el primer día.

Recursos adicionales

• Documentación oficial de Vercel
• guía de deploy de NextJS en Vercel
• Vercel CLI Reference