Deploy en Vercel: Guia completa para NextJS

Hacer deploy en Vercel de tu aplicacion NextJS es el camino mas directo para llevar tu proyecto a produccion. Vercel es la plataforma creada por el equipo detras de NextJS, lo que significa que cada feature nueva tiene soporte desde el dia cero: Server Components, ISR, Edge Functions, Image Optimization. No hay configuracion especial, no hay parches, no hay incompatibilidades.

En esta guia vas a cubrir todo el proceso, desde crear tu cuenta hasta monitorear tu aplicacion en produccion. Si ya tienes tu proyecto listo y solo necesitas lanzarlo, esto es lo que necesitas.

Por que 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 automaticamente
• Preview deployments: Cada pull request tiene su propia URL para probar
• Edge network: Tu sitio se sirve desde el nodo mas cercano al usuario
• Integracion nativa: ISR, Server Actions, Edge Functions, Image Optimization funcionan sin configuracion 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 (tambien 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 15 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 opcion es la recomendada. Otorga acceso solo al repositorio que vas a desplegar.

Paso 2: Configuracion del proyecto

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

Framework Preset

Vercel detecta NextJS automaticamente 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": "15.1.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 aqui
│   └── 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 mas problemas causa en los primeros deployments. Tu aplicacion 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 PUBLICA - 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 critico 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 unica (tu-proyecto.vercel.app)

Build logs

Mientras Vercel ejecuta el build, puedes ver los logs en tiempo real. Esto es lo que veras 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 cual es el dominio principal:

• tudominio.com (sin www) -- la opcion mas comun
• www.tudominio.com (con www)

El dominio que no elijas como principal redirige automaticamente al principal con un 308.

SSL automatico

Vercel genera certificados SSL (Let's Encrypt) automaticamente 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.

Como funciona

1. Creas una rama: feature/nueva-seccion
2. Haces push y abres un PR en GitHub
3. Vercel detecta el PR automaticamente
4. Ejecuta el build con esa rama
5. Despliega en una URL unica: 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 produccion
• Compartir con diseno 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 util cuando 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 mas frecuente. Revisa los build logs en el dashboard de Vercel.

Causas comunes:

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

Error: 500 Internal Server Error en produccion

Tu build paso pero la aplicacion falla al ejecutarse.

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

Error: Pagina muestra contenido viejo

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

Error: Imagenes 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 limite 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 codigo en el nodo mas 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' },
  })
}

Cuando usar Edge Functions:

• APIs que necesitan baja latencia
• Middleware de autenticacion
• Redirects y rewrites dinamicos
• Personalizacion por region

Cuando NO usar Edge Functions:

• Consultas a base de datos que solo existen en una region
• Operaciones que necesitan Node.js APIs completas
• Procesos que requieren mas de 30 segundos

ISR (Incremental Static Regeneration)

ISR te permite tener paginas estaticas que se actualizan automaticamente:

// 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 version cacheada (rapido)
• En background regenera la pagina
• La siguiente visita recibe la version actualizada
• Sin downtime durante la regeneracion

On-Demand Revalidation

Si necesitas actualizar una pagina 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 imagenes automaticamente. Sirve formatos modernos (WebP, AVIF) y redimensiona segun el dispositivo:

// Componente con optimizacion automatica
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 automaticamente
• Redimensiona segun el sizes prop
• Cachea las imagenes optimizadas en el edge
• Lazy loading por defecto (excepto con priority)

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

Paso 9: Monitoreo basico

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

Ademas de Analytics, Vercel ofrece Speed Insights para un analisis mas 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 produccion:

1. Ve a tu proyecto en Vercel > Logs
2. Filtra por tipo: Functions, Edge, Build
3. Cada invocacion de funcion 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 linea aparece en Vercel Logs')
  const data = await fetchData()
  console.log('Data recibida:', data.length, 'items')
  return <div>...</div>
}

Paso 10: Automatizacion y CI/CD

Deploy automatico

Por defecto, Vercel ejecuta un deploy cada vez que:

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

No necesitas configurar GitHub Actions ni ningun CI adicional. Vercel se encarga de todo.

Ignorar builds innecesarios

Si haces un push que no deberia 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 produccion

Configuracion 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.

Configuracion completa de next.config.ts para Vercel

Esta es una configuracion de next.config.ts optimizada para deploy en Vercel:

// next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  // Optimizaciones de imagenes
  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 automaticamente, asegurate de que la URL base este correcta en produccion. Revisa la guia de sitemap automatico en NextJS 15 para configurarlo.

Checklist antes de hacer deploy

Antes de hacer tu primer deploy a produccion, verifica estos puntos:

Build y codigo

• npm run build pasa sin errores en local
• No hay warnings de TypeScript criticos
• ESLint no reporta errores (solo warnings tolerables)
• Todas las paginas 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 produccion
• La NEXT_PUBLIC_SITE_URL apunta a tu dominio real
• Ninguna clave secreta tiene el prefijo NEXT_PUBLIC_

SEO y metadata

• Cada pagina tiene title y description unicos
• OG images configuradas
• robots.txt permite el crawleo
• sitemap.xml genera URLs con el dominio de produccion

Performance

• Imagenes 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 configuracion especifica:

{
  "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 produccion
vercel --prod

Pero la integracion con GitHub es la forma recomendada porque te da preview deployments automaticos y rollback facil.

Como 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 multiples dominios apuntando al mismo proyecto?

Si. Puedes agregar multiples 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

Cuanto cuesta Vercel para proyectos reales?

Para un blog o portafolio personal, el plan Hobby es mas 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 automaticamente a produccion. Cada pull request genera un preview deployment. SSL, optimizacion de imagenes y CDN global vienen incluidos sin configuracion.

Lo que diferencia a Vercel de otras plataformas es la integracion nativa con NextJS. Features como ISR, Edge Functions y Server Components funcionan tal cual la documentacion los describe, sin parches ni workarounds.

Si todavia no has configurado el SEO basico de tu sitio, este es un buen momento. Revisa la guia de sitemap automatico en NextJS 15 y asegurate de que Google pueda indexar tu sitio correctamente desde el primer dia.

Recursos adicionales

• Documentacion oficial de Vercel
• Guia de deploy de NextJS en Vercel
• Vercel CLI Reference