Deploying Next.js to Vercel with Preview Deployments

Introduction

Next.js es un framework de React potente que simplifica el desarrollo de aplicaciones web modernas. Cuando se trata de llevar una aplicación del entorno de desarrollo a internet, Vercel se ha convertido en una plataforma popular gracias a su integración nativa con Next.js, despliegues instantáneos y un sistema robusto de despliegues previos (también conocidos como PR previews).

Este artículo te guiará paso a paso a través del proceso completo: desde configurar un nuevo proyecto Next.js hasta conectarlo a Vercel, crear despliegues previos para cada rama y automatizarlo todo con GitHub Actions. Cada comando y bloque de configuración se muestra junto con la salida esperada, para que puedas seguir con confianza y saber exactamente qué esperar.

A quién va dirigido este artículo

• Desarrolladores frontend que ya trabajan con Next.js y quieren llevar sus aplicaciones a producción.
• Equipos que utilizan Git y CI/CD y necesitan pruebas visibles antes de fusionar código.
• Ingenieros de DevOps o responsables de infraestructura que quieren estandarizar el flujo de despliegue en Vercel.

Al finalizar, sabrás cómo:

• Conectar un repositorio local a Vercel usando la CLI.
• Crear un despliegue previo automáticamente con vercel --pre.
• Configurar vercel.json para mantener la producción y los entornos previos separados.
• Escribir un flujo de trabajo de GitHub Actions que dispare despliegues en cada push a una rama.
• Evitar errores comunes como builds fallidos, problemas con variables de entorno o configuraciones incorrectas.
• Obtener un despliegue previo utilizable para cada solicitud de extracción, con un dominio predecible.

1. Requisitos previos

Antes de empezar, asegúrate de tener lo siguiente:

• Node.js ≥ 18 (incluye npm o yarn).
• Una cuenta en GitHub (o cualquier otro servicio de git remoto).
• Una cuenta en Vercel (puedes registrarte en vercel.com).
• El CLI de Vercel instalado globalmente (npm i -g vercel).

node -v
npm -v
vercel --version

Salida esperada (ejemplo):

v14.15.4
9.6.3
v33.3.2

Si algún comando falla, verifica tu instalación de Node o actualiza el CLI con npm i -g vercel@latest.

2. Creación de un proyecto Next.js de ejemplo

Puedes clonar el esqueleto de un proyecto de Next.js (la plantilla “with-typescript” incluye todo lo necesario) o crear uno nuevo con create-next-app. La plantilla que usaremos es mínima, solo para demostración.

npx create-next-app@latest preview-demo --typescript --eslint --app --tailwind --import-alias "@/*"

Salida esperada (e interactions):

¿Prefieres usar TypeScript? (Y/n) n
¿Prefieres usar ESLint? (Y/n) y
¿Prefieres usar Tailwind CSS? (Y/n) y
¿Prefieres usar `appDir` y React 18? (Y/n) y
¿Prefieres usar la opción de importación con alias? (Y/n) y
Creando un nuevo proyecto en /path/to/preview-demo.
Instalando dependencias...

Después de la instalación, navega al directorio:

cd preview-demo

Abre el proyecto en tu editor. La estructura será algo como:

tree -L 2

Salida esperada (poda para brevedad):

preview-demo
├── .eslintrc.json
├── .gitignore
├── next.config.js
├── package.json
├── pnpm-lock.yaml
├── public/
│   └── favicon.ico
├── src/
│   ├── app/
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   └── about/
│   │       └── page.tsx
│   └── components/
│       └── ui/
│           └── card.tsx
└── tsconfig.json

Para propósitos de este tutorial, solo necesitamos un par de páginas y un componente UI simple. Si quieres copiar el código exacto, puedes inspeccionar el repositorio generado más adelante.

3. Primer despliegue en Vercel (producción)

3.1 Iniciar sesión en la CLI de Vercel

vercel login

Se abrirá un navegador; inicia sesión en tu cuenta de Vercel. Si estás usando un token de GitHub Actions, puedes omitir este paso.

3.2 Desplegar desde el directorio raíz

vercel --prod

Se te preguntará:

• ¿Cuál es tu proyecto de Now? (por defecto, toma el nombre del directorio).
• ¿Cuál es tu email de despliegue? (tu email de Vercel).
• ¿Quieres desplegar en production (prod)? (confirmar).

Salida esperada (interactiva, simulada):

✔ Hablando con el equipo de Vercel...
¿Cual es el nombre de tu proyecto? preview-demo
¿Cual es tu email de despliegue? desarrollador@ejemplo.com
¿Quieres desplegar en producción? (Y/n) y
¡Desplegando... ¡Hecho! ¡Puedes encontrar tu despliegue aquí: https://preview-demo.vercel.app

El comando compila la aplicación (next build), ejecuta next export (o la exportación nativa de serverless de Next.js) y te da una URL de producción.

3.3 Verificar el despliegue

curl -I https://preview-demo.vercel.app

Salida esperada:

HTTP/2 200 
Content-Type: text/html; charset=utf-8

¡Excelente! El despliegue en producción está activo.

4. Introducción a los despliegues previos

4.1 ¿Qué es un despliegue previo?

Un despliegue previo es una instancia efímera de tu aplicación alojada en Vercel para una rama o una solicitud de extracción específica. Te permite probar el código antes de fusionarlo en main/master. La URL sigue un patrón predecible:

https://<nombre-proyecto>-<hash-de-la-rama>-vercel.app

Ejemplo: una rama llamada feature/user-list podría obtener https://preview-demo-feature-user-list-abcd1234.vercel.app.

4.2 Habilitar despliegues previos automáticamente

Vercel activa los despliegues previos automáticamente para todas las ramas de un proyecto cuando usas el CLI. Después del primer despliegue, edita vercel.json para ser explícito:

{
  "version": 2,
  "builds": [
    {
      "src": "package.json",
      "use": "@vercel/next",
      "config": { "zeroConfig": true }
    }
  ],
  "routes": [
    {
      "src": "/api/(.*)",
      "dest": "/.vercel/functions/api/$1"
    }
  ],
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/.vercel/functions/render/$1"
    }
  ],
  "preview": {
    "enabled": true,
    "auto": true
  }
}

El campo preview.enabled activa el sistema de vistas previas globalmente; preview.auto indica a Vercel que cree automáticamente una nueva vista previa para cada rama.

4.3 Creación manual de un despliegue previo

Supongamos que ya estás en una rama (git checkout feature/user-list) y quieres un despliegue previo inmediato sin esperar una CI:

vercel --pre

Salida esperada:

✔ Hablando con el equipo de Vercel...
¿Cual es el nombre de tu proyecto? preview-demo
¿Quieres crear un despliegue previo? (Y/n) y
¡Desplegando con vistas previas... ¡Hecho! ¡Puedes encontrar tu despliegue aquí: https://preview-demo-feature-user-list-xyz789.vercel.app

La URL (https://preview-demo-feature-user-list-xyz789.vercel.app) apunta ahora a esa rama. Puedes compartirla con tu equipo para pruebas.

4.4 Prueba del despliegue previo

curl -I https://preview-demo-feature-user-list-xyz789.vercel.app

Salida esperada:

HTTP/2 200
Content-Type: text/html; charset=utf-8

Si usas el enrutamiento basado en archivos de Next.js, la página principal debe mostrar el título de app/page.tsx. Puedes verificar el HTML real:

curl -s https://preview-demo-feature-user-list-xyz789.vercel.app | grep "<title>"

Salida esperada:

<title>preview-demo</title>

5. Automatización con GitHub Actions

5.1 Crear el flujo de trabajo (.github/workflows/vercel.yml)

Crea el directorio .github/workflows si no existe.

mkdir -p .github/workflows

Edita el archivo vercel.yml:

name: Despliegue en Vercel

on:
  push:
    branches:
      - main
      - develop
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Obtener código
        uses: actions/checkout@v4

      - name: Configurar Node
        uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: 'npm'

      - name: Instalar dependencias
        run: npm ci

      - name: Desplegar en producción (rama main)
        if: github.ref == 'refs/heads/main'
        env:
          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
        run: |
          npx vercel --prod --token ${{ secrets.VERCEL_TOKEN }}

      - name: Desplegar vista previa (otras ramas)
        if: github.ref != 'refs/heads/main'
        env:
          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
        run: |
          npx vercel --pre --token ${{ secrets.VERCEL_TOKEN }}

Salida esperada durante la ejecución de la acción:

Clonando repositorio...
Instalando dependencias...
Resolviendo versiones...
Desplegando en Vercel (vista previa)... ¡Hecho! https://preview-demo-<branch-hash>-vercel.app

El workflow usa variables secretas de GitHub:

• VERCEL_TOKEN – token de acceso personal de Vercel.
• VERCEL_ORG_ID – ID de la organización de Vercel.
• VERCEL_PROJECT_ID – ID del proyecto dentro de la organización.

Estos IDs se pueden obtener desde la interfaz de usuario de Vercel → Ajustes del proyecto → “Integrar”. No los expongas nunca públicamente.

5.2 Resultados esperados para cada evento

6. Mejores prácticas

1. Mantén limpias las variables de entorno
   Usa vercel env ls para listarlas, vercel env add para agregarlas de forma segura, y elimina cualquier clave secreta del historial de git (git filter-repo o git filter-branch).

2. Usa un archivo .gitignore adecuado
   Además de los valores por defecto, ignora:

   .vercel
   *.log
   .env.local
   .env.test

3. Separa configuraciones de producción y previas
   El archivo vercel.json anterior ya aísla las rutas. Si necesitas diferentes headers o redirects para vistas previas, puedes usar routes con handle: 'pre'.

4. Cachea la compilación
   Usa las acciones de Caché de GitHub (actions/cache) para mantener el directorio node_modules y la compilación .next para reducir el tiempo de ejecución.

5. Usa un nombre de dominio personalizado
   Una vez que estés contento con el despliegue previo, asigna un subdominio (vercel.app o un dominio personalizado) usando la interfaz de usuario de Vercel.

6. Evita “No se encontró salida de compilación”
   Asegúrate de que next build se ejecute correctamente localmente (npm run build). Si tu aplicación usa imágenes estáticas (next export) o output: 'export' en next.config.js, verifica que VERCEL. Por lo general, sigue los pasos descritos en la documentación de Vercel.

7. Problemas comunes y cómo solucionarlos

7.1 Depuración con vercel dev

Si necesitas probar el comportamiento localmente antes de un despliegue, ejecuta:

vercel dev

Salida esperada:

► Listening on http://localhost:3000
► Build completed (duración Xms)

Puedes acceder a http://localhost:3000 para ver la aplicación como Vercel la vería.

8. Conclusión

Revisemos los puntos clave:

1. Configuración inicial – Instala Node, el CLI de Vercel e inicia sesión.
2. Primer despliegue en producción – vercel --prod proporciona una URL pública instantly.
3. Concepto de despliegue previo – Las vistas previas son URLs temporales y compartibles para ramas específicas.
4. Creación manual – vercel --pre en cualquier rama.
5. Automatización – Un simple workflow de GitHub Actions maneja tanto main (producción) como otras ramas (vista previa).
6. Mejores prácticas – Usa variables de entorno seguras, un .gitignore adecuado y un vercel.json limpio.
7. Solución de problemas – Depura con vercel dev, verifica los mensajes de error de compilación y limpia vistas previas antiguas si es necesario.

Con estos pasos, tu equipo puede tener confianza de que cada cambio se prueba en un entorno real antes de fusionarlo. La combinación de despliegues previos automáticos con CI/CD hace que el proceso sea prácticamente sin esfuerzo y mantenible.

Próximos pasos

• Asignar dominios personalizados: En la interfaz de Vercel, agrega app.example.com y configura los registros DNS.
• Monitorear el rendimiento: Conecta tu proyecto a Vercel Analytics (@vercel/analytics) para obtener métricas en tiempo real.
• Escalar globalmente: Vercel usa CDN; los despliegues previos ya se benefician de ello, pero puedes especificar overrides en vercel.json para regiones específicas si lo necesitas.
• Flujos de ramas protegidas: Implementa una política de ramas protegidas en GitHub + require approval en Vercel para controlar quién puede fusionar código.

Al perfeccionar este flujo de trabajo, obtendrás un pipeline de CI/CD rápido y confiable que mantendrá a tu aplicación Next.js siempre en su mejor versión.

“El mejor código no se escribe solo; se implementa, prueba y mejora continuamente.” – equipo de Vercel