Biz Deploy Vercel — Desplegar sitio web en Vercel de forma segu…

Biz Deploy Vercel — Desplegar sitio web en Vercel de forma segura en un solo comando

Esta habilidad convierte 1 directorio de proyecto local (React / Next.js / Vite / HTML estático) en 1 URL en vivo en Vercel con SSL, CDN y despliegue de vista previa. Objetivo: solopreneur / PYME sin necesidad de saber DevOps puede desplegar una landing page solo mediante conversación con Claude.

Espíritu: No preguntar al usuario cosas que Claude puede verificar por sí mismo. Detectar el framework automáticamente, generar vercel.json cuando sea necesario, detenerse solo cuando se encuentre una barrera manual real (inicio de sesión en el navegador, DNS de dominio personalizado).

Cuándo usar

El usuario quiere:

• Publicar 1 landing page / sitio web en una URL en vivo para compartir / probar / ejecutar anuncios
• Volver a desplegar un proyecto después de modificar código
• Configurar Vercel por primera vez para un nuevo repositorio
• Configurar un dominio personalizado que apunte a Vercel

Cuándo NO usar

• Solo necesita compilar localmente, aún no quiere publicar → omitir, usar npm run build / next dev.
• Necesita desplegar en Netlify / Cloudflare Pages / AWS → esta habilidad es específica de Vercel.
• Necesita CI/CD complejo con GitHub Actions personalizado → aún puede usar esta habilidad para inicializar el proyecto, pero la parte del flujo de trabajo personalizado la configura el usuario.
• Necesita backend Node.js con estado completo del servidor (websocket, long polling) → Vercel serverless no es adecuado, usar Railway / Fly.io.

Resultado que recibirá el usuario

1. URL en vivo con formato https://<proyecto>.vercel.app (producción) o URL de vista previa.
2. URL de inspección con formato https://vercel.com/<cuenta>/<proyecto>/<id-despliegue> para ver registros.
3. Proyecto vinculado en .vercel/project.json (ignorado por git) — el próximo despliegue solo necesita vercel --prod.
4. Si el usuario solicita un dominio personalizado → instrucciones DNS específicas (registro A / CNAME).

---

Flujo de trabajo en 6 pasos

Paso 1 — Verificación previa: Comprobar Vercel CLI / MCP

Ejecutar scripts/check_vercel.sh (o comandos en línea equivalentes) para determinar el estado de 3 elementos:

Elemento a verificar	Comando	Resultado esperado
Node.js	node --version	v18+ o v20+
Vercel CLI	vercel --version	Devuelve versión (v32+)
Autenticación Vercel	vercel whoami	Devuelve nombre de usuario

Si falta Node.js:

• macOS: sugerir brew install node o descargar https://nodejs.org
• Windows: guiar para descargar el instalador .msi desde https://nodejs.org/en/download/
• Linux: nvm install --lts o gestor de paquetes.
• Detener la habilidad, esperar a que el usuario instale y avise.

Si falta Vercel CLI:

• Detectar el gestor de paquetes en uso (verificar pnpm, yarn, npm en orden de prioridad o leer el archivo de bloqueo del proyecto).
• Instalar globalmente:
  • pnpm add -g vercel (si el usuario usa pnpm)
  • npm install -g vercel (por defecto)
• Verificar de nuevo con vercel --version.

Si Vercel CLI está presente pero no autenticado (vercel whoami muestra error):

• Ejecutar vercel login — este comando abre el navegador, el usuario debe hacer clic en confirmar. Esta es una barrera manual, no se puede omitir.
• Informar al usuario: "He ejecutado vercel login. Abre el navegador, haz clic en confirmar para autenticarte. Cuando termines, escribe 'ok' para que continúe."
• Detenerse, esperar la respuesta del usuario.

Si el usuario dice que tiene Vercel MCP:

• Verificar el servidor MCP listando las herramientas MCP disponibles (herramientas con prefijo mcp__vercel__*).
• Si hay MCP, seguir priorizando CLI para el despliegue real (CLI es más estable para la subida de archivos), usar MCP para consultar proyecto / dominio / variables de entorno después del despliegue si es necesario.
• Si el usuario exige usar MCP: según la documentación https://vercel.com/docs/mcp para autenticarse, luego usar las herramientas MCP correspondientes.

Paso 2 — Detectar framework + estructura del proyecto

Leer los archivos en la raíz del proyecto para determinar el framework:

Archivo	Framework
next.config.js / next.config.mjs / next.config.ts	Next.js
vite.config.js / vite.config.ts	Vite (React/Vue/Svelte)
package.json con "react-scripts"	Create React App
package.json con "astro"	Astro
package.json con "@remix-run/dev"	Remix
Solo index.html + assets, sin package.json	HTML estático
Tiene package.json pero no coincide con los patrones anteriores	Preguntar al usuario qué framework usa, o dejar que Vercel lo detecte automáticamente

Registrar adicionalmente:

• Comando de compilación desde package.json (scripts.build)
• Directorio de salida (Next: .next, Vite: dist, CRA: build, estático: .)
• Versión de Node requerida (desde engines.node o .nvmrc)

→ Leer la referencia correspondiente:

• React/Vite → references/react-vite.md
• Next.js → references/nextjs.md
• HTML estático → references/static-html.md

Paso 3 — Generar vercel.json (si es necesario)

Next.js: Vercel detecta automáticamente, no necesita vercel.json a menos que se requieran encabezados personalizados / redirecciones.

Vite / CRA (enrutamiento SPA): Necesita vercel.json para reescribir todas las rutas a index.html y que funcione el enrutamiento del lado del cliente:

{
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

HTML estático: Generalmente no es necesario. Si el sitio tiene varias páginas (thank-you.html, privacy.html) no se necesita reescritura. Si solo tiene index.html + enrutador JS, se necesita reescritura como SPA.

Encabezados de seguridad (recomendado para producción):

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "X-Content-Type-Options", "value": "nosniff" },
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" }
      ]
    }
  ]
}

Regla: Solo crear vercel.json si el usuario realmente lo necesita. Crear un archivo innecesario = ruido en el repositorio.

Paso 4 — Lista de verificación previa al despliegue

Antes de ejecutar vercel, verificar:

• Tiene .gitignore que contenga .vercel/, node_modules/, .env* (NO se deben confirmar secretos)
• Las rutas de archivos en el código son todas minúsculas + relativas (Linux distingue mayúsculas y minúsculas)
• No hay URL localhost codificadas
• Los scripts/hojas de estilo externos son https://
• Si Next.js tiene variables de entorno → preparar lista de variables de entorno necesarias
• Si tiene package.json → npm install (o equivalente) funciona localmente

Si se detecta un problema claro (ej: localhost codificado en HTML), corregir primero y luego desplegar.

Paso 5 — Desplegar

Primer despliegue de un proyecto (sin .vercel/project.json):

vercel --prod --yes

La bandera --yes acepta toda la configuración predeterminada de la detección automática del framework. Vercel:

• Preguntará el ámbito (elige automáticamente la cuenta del usuario con --yes)
• Detecta el preset del framework
• Establece el comando de compilación + directorio de salida
• Sube el código, compila, despliega

Si se necesita un nombre de proyecto personalizado o el usuario quiere vincularlo a un proyecto existente:

vercel link              # Vincular a proyecto existente (interactivo)
vercel --prod            # Desplegar después de vincular

Desplegar vista previa (no producción):

vercel

→ Devuelve URL de vista previa tipo https://<proyecto>-<hash>.vercel.app, para probar antes de promover a producción.

Volver a desplegar (proyecto ya vinculado):

vercel --prod

Capturar salida — analizar stdout para obtener:

• Production: https://<proyecto>.vercel.app
• Inspect: https://vercel.com/...

Informar al usuario de estas 2 URL de inmediato.

Paso 6 — Verificar + informar

Después de un despliegue exitoso:

1. Verificación HTTP de la URL en vivo con curl -I https://<proyecto>.vercel.app — verificar estado 200 + SSL activo.
2. Informe al usuario con el formato:

## ✅ Despliegue exitoso

**URL en vivo**: https://<proyecto>.vercel.app
**Inspección / Registros**: https://vercel.com/<cuenta>/<proyecto>/<id-despliegue>
**Framework**: <Next.js | Vite | CRA | HTML estático>
**Tiempo de compilación**: <Xs>

### Próximo despliegue
Solo necesita ejecutar: `vercel --prod`

### Opciones
- Configurar dominio personalizado → decirme `setup dominio <tudominio.com>`
- Configurar variables de entorno → decirme `add env <VARIABLE>`
- Ver registros → `vercel logs`

3. Si el usuario solicita un dominio personalizado → leer references/domains.md y guiar con DNS.

---

Casos límite + recuperación

Error de compilación en Vercel pero funciona localmente

Causas comunes:

• Sensibilidad a mayúsculas/minúsculas: import './Components/Header' funciona localmente en Mac pero falla en Linux si la carpeta real es components. Solución: renombrar según el caso correcto.
• Dependencia faltante: paquete en devDependencies pero necesario en tiempo de ejecución → mover a dependencies.
• Versión de Node incorrecta: agregar "engines": { "node": "20.x" } en package.json o .nvmrc.

→ Obtener registros con vercel logs <url-despliegue>, leer, corregir, volver a desplegar.

Proyecto vinculado a la cuenta / proyecto incorrecto

rm -rf .vercel/ y luego ejecutar vercel --prod --yes. O usar vercel link para seleccionar el proyecto correcto.

Variables de entorno en producción

vercel env add <VARIABLE> production
# Pegar valor cuando se solicite
vercel env pull .env.production.local   # Descargar localmente si es necesario

Evitar confirmar archivos .env*. Agregar a .gitignore si no está presente.

Caducidad de autenticación

El token CLI puede caducar. Si vercel whoami muestra no autorizado → ejecutar vercel login de nuevo.

---

Referencias detalladas por framework

Leer la referencia que coincida con el framework del proyecto:

Framework	Referencia
Next.js (App / Pages router)	references/nextjs.md
React (Vite / CRA)	references/react-vite.md
HTML estático	references/static-html.md
Dominio personalizado + DNS	references/domains.md
Errores y solución de problemas	references/troubleshooting.md

Referencias originales

• Documentación de Vercel CLI: https://vercel.com/docs/cli
• Configuración de compilación de Vercel: https://vercel.com/docs/projects/project-configuration
• Límites de Vercel (plan gratuito): https://vercel.com/docs/limits
• Página de estado: https://www.vercel-status.com