nachoorg/vercel-landing-pages-skill

Landing pages en Vercel

Convertí un pedido no técnico en un sitio rápido y prolijo, y publicalo en Vercel con un circuito repetible. El usuario dice qué quiere; vos te encargás del stack, el código, los chequeos y de preparar cada deploy. El usuario no necesariamente es desarrollador: hablá simple, preguntá poco y nunca dejes un sitio a medio publicar. Respondé en el idioma del usuario (por defecto español rioplatense).

0. Dónde corre cada cosa (regla de oro)

Hay tres lugares para ejecutar comandos y cada uno tiene un rol fijo:

Lugar	Para qué	Nunca para
Terminal del usuario (su Mac/PC, con su sesión de Vercel)	vercel login, link, deploy, rollback, promote, domains, env add — todo lo que toca vercel.com o credenciales	—
Terminal local de Cowork (device_bash, VM sobre la carpeta conectada)	leer y editar archivos, git add/commit, chequeos previos, anotar el historial	vercel login ni deploys
Terminal en la nube de Cowork (Bash)	capturas de pantalla con Playwright, herramientas que no estén en la VM local	tocar los archivos del usuario directamente

Por qué: cada llamada a device_bash es un sandbox nuevo y efímero — un proceso en segundo plano (como vercel login esperando aprobación) muere al terminar el comando y parece "colgado"; además el proxy de la organización puede bloquear vercel.com (403 from proxy after CONNECT, fetch failed). La terminal del usuario ya tiene su login y su red. No pidas ni escribas tokens ni credenciales; el login lo hace el usuario.

Cómo pasarle comandos al usuario:

• Un bloque de código, un comando por línea, empezando por cd a la carpeta.
• Sin comentarios # al final de la línea (zsh los pasa como argumentos: Error: Can't deploy more than one path). Las explicaciones van fuera del bloque.
• Siempre --yes para que no haya prompts interactivos.
• Pedile que pegue la salida completa; de ahí sacás la URL y los errores.
• Después de cada deploy, anotá vos el historial (ver sección 5) con device_bash.

Uso de la computadora: macOS solo permite hacer clic en terminales y editores, no escribir. No pidas control de la Terminal para tipear comandos; no sirve.

1. Detectá la situación primero

• Pedí acceso a la carpeta con device_request_folder_access (p. ej. ~/Downloads). Si el proyecto llegó como .tar.gz/.zip, descomprimilo al lado con device_bash.
• Existe .vercel/project.json → ACTUALIZACIÓN (sección 5). El proyecto ya está vinculado.
• Hay código pero no .vercel/ → PRIMER DEPLOY de código existente (secciones 3–5).
• Vacía / nueva → PROYECTO NUEVO (secciones 2–5).
• Pide dominio propio → sección 6.

Git en una carpeta conectada: git necesita borrar sus archivos .lock; sin permiso de borrado falla con unable to unlink ... Operation not permitted. Pedí una sola vez device_request_delete_permission sobre la carpeta raíz explicando que es para los archivos temporales de git (aclarale que habilita borrar en toda esa carpeta durante la sesión). Si lo rechaza, los commits los hace el usuario en su terminal. Configurá autor en cada comando: git -c user.name=... -c user.email=... commit.

Verificá una vez en la terminal del usuario: node -v (≥18), git --version, npx vercel whoami. Si whoami dice Logged out, el usuario ejecuta npx vercel login ahí mismo y aprueba el código en el navegador. Nunca escribas credenciales, tokens ni claves fiscales por él.

2. Pedido → especificación (corta)

Tomá lo que ya dijo; preguntá solo lo que falta y bloquea, en un solo mensaje, máximo ~4 preguntas:

• Objetivo (vender, captar contactos, informar, inscripción) y una única acción principal (CTA)
• Público e idioma de los textos
• Contenido: nombre, secciones, textos/fotos disponibles (o "inventá textos de ejemplo")
• Marca: colores, logo, estilo (o "elegí vos")
• Necesidades: formulario, botón de WhatsApp, analítica, dominio propio

Devolvé una especificación de 5–10 líneas y avanzá salvo objeción. El contenido inventado va marcado con TODO. Si te dan un teléfono para WhatsApp, validá el formato internacional (Argentina celular: 549 + área + número, sin + ni 15) y avisá si no cierra: un wa.me mal armado abre un chat inválido.

Si el pedido de estilo tiene tensiones ("cheta pero tumbera", colores de un club en un barrio rival, marcas registradas), resolvelas vos con criterio, mostrá el resultado y explicá la decisión en dos líneas; no uses escudos, nombres ni logos de terceros.

3. Elegí el stack (lo más simple por defecto)

Necesidad	Stack	Por qué
Landing única / pocas páginas estáticas	HTML + CSS + JS mínimo, sin build	Cero dependencias, nada que se rompa, deploys instantáneos. Por defecto.
Muchas páginas, layout compartido, blog	Astro (salida estática)	Componentes + markdown, casi sin JS
Lógica de aplicación real, login, paneles	Next.js	Solo si hace falta de verdad
Solo un formulario de contacto	Estático + función api/contact.js, o servicio de formularios	No justifica un framework

Detalles, comandos, formularios y analítica: references/stacks.md.

Para sitios estáticos, copiá assets/static-starter/ como base (index, estilos, vercel.json, 404, robots, .gitignore) y adaptalo; no publiques el diseño base sin cambios.

4. Construilo bien (en Cowork)

Seguí references/landing-guidelines.md. Innegociables:

• Mobile first, responsive, el contenido principal funciona sin JS
• <title>, meta description, Open Graph, favicon, atributo lang
• Imágenes comprimidas, con tamaño, loading="lazy" debajo del pliegue, alt
• Una acción principal clara, repetida (arriba y al final)
• Nada de secretos en el repo; las claves van con npx vercel env add (lo corre el usuario)
• .vercelignore obligatorio con .env*, .deployments.log, .git, .gitignore, .vercelignore. En un sitio estático sin build Vercel sube todo lo que hay en la carpeta, y vercel link crea un .env.local con un token que quedaría público en /.env.local.
• .gitignore con .vercel, node_modules, .env*, .deployments.log

Ediciones con device_bash: sed -i o un script corto en python de leer-modificar-escribir con assert de que cada reemplazo matchea exactamente una vez. Nunca re-tipear el archivo entero desde la salida de una herramienta.

Chequeos antes de cualquier deploy:

• predeploy-check.mjs sobre la carpeta: corregí todos los ERROR, evaluá los WARNING. Los scripts del skill viven en la nube; para correrlos en la VM local copialos una vez a $HOME/tools/ (fuera de mnt/, invisible para el usuario) pasándolos por device_bash en base64 o con un heredoc.
• Astro/Next: npm run build tiene que pasar.
• Verificación visual en la nube: device_stage_files de los archivos del sitio → python3 -m http.server → Playwright con chromium.launch({executablePath: '/opt/pw-browsers/chromium-*/chrome-linux/chrome'}) (no correr playwright install) → capturas de página completa en 1366px y 390px → mirarlas con Read. Las fuentes de Google no cargan ahí, así que la tipografía se ve aproximada. Mandale al usuario una captura si el cambio es visual.

Cada cambio termina en un git commit -m "<qué cambió>". Los commits son el historial de versiones.

5. Deploy: siempre el mismo circuito

Instalá el script en el proyecto una sola vez: copiá scripts/deploy.mjs del skill a la raíz del proyecto como deploy.mjs (por device_bash, heredoc o base64) y commitealo. Es lo que corre el usuario; funciona en macOS, Windows y Linux y no tiene dependencias.

Qué hace node deploy.mjs: verifica el login → si falta .vercel/project.json, crea/vincula el proyecto (vercel link --yes --project <nombre>) → avisa si hay cambios sin commitear → si hay package.json con build usa vercel pull + vercel build + vercel deploy --prebuilt, si no vercel deploy --yes directo → imprime la URL → agrega una línea a .deployments.log (fecha, destino, commit, URL). --dry-run solo muestra el plan.

Flujo, siempre:

1. Vos: cambio, chequeos, captura, git commit (Cowork).
2. Usuario, en su terminal:

   cd ~/ruta/al/proyecto
   node deploy.mjs --name nombre-del-proyecto
   

   (--name solo la primera vez.) Te pega la salida; vos le devolvés la URL de preview.
3. El usuario revisa la preview en su navegador. Las previews suelen tener Deployment Protection (piden login de Vercel); no uses npx vercel curl para verificarlas: genera un token de bypass permanente en el proyecto. Si necesitás verla vos, usá el navegador integrado con request_access al dominio *.vercel.app y a vercel.com, y si no se puede, confiá en la revisión del usuario más tus capturas locales.
4. Solo con un "sí" explícito, el usuario corre node deploy.mjs --prod. Producción es pública.
5. Verificá producción (esa URL no está protegida): / responde, el CSS carga, los links de CTA apuntan bien, /.env.local, /.git/HEAD y /.vercel/project.json dan 404, una ruta inexistente muestra tu 404.
6. Informá: URL de producción, qué cambió, commit, cómo volver atrás.

Si el usuario prefiere no usar el script, el equivalente a mano es npx vercel link --yes --project <nombre>, npx vercel deploy --yes y npx vercel deploy --prod --yes; en ese caso anotá vos la línea en .deployments.log (fecha ISO<TAB>preview|production<TAB>sha corto<TAB>URL) con device_bash a partir de la salida que te pegó.

Nombre del proyecto: minúsculas y guiones, derivado del negocio (panaderia-la-espiga); define el subdominio *.vercel.app.

Volver atrás

• npx vercel rollback → producción anterior (inmediato, sin rebuild; no existe si fue el primer deploy)
• npx vercel promote <url-deploy> → publicar un deploy específico
• npx vercel ls <proyecto> → listar deploys; .deployments.log los relaciona con commits

Extras a pedido

• Variables de entorno: npx vercel env add NOMBRE production (el valor lo escribe el usuario).
• Deploy automático al hacer git push: references/ci-github.md. Recomendalo cuando haya más de una persona editando o muchos cambios seguidos; elimina el paso manual de deploy.

Las flags de la CLI cambian. Si un comando falla por una flag, npx vercel <cmd> --help y adaptá. Errores comunes: references/troubleshooting.md, más estos vistos en la práctica:

Síntoma	Causa / solución
Error: Can't deploy more than one path	Comentarios # al final de la línea pegada en zsh. Reescribí el bloque sin comentarios.
vercel login "colgado" en Cowork	Sandbox efímero. El login va en la terminal del usuario.
403 from proxy after CONNECT / fetch failed hacia vercel.com	Red de la organización bloquea Vercel. Terminal del usuario, o el admin agrega vercel.com y *.vercel.app a los dominios permitidos.
Apareció .env.local después de vercel link	Normal (token OIDC). Debe estar en .gitignore y .vercelignore; podés borrarlo.
unable to unlink .git/...lock: Operation not permitted	Falta permiso de borrado en la carpeta conectada; pedilo una vez o que el usuario commitee.
Preview pide login de Vercel	Deployment Protection en previews; la revisa el usuario logueado.

6. Dominio propio

• .com.ar / .ar → seguí references/dominio-nic-ar.md (compra en NIC Argentina con CUIT + Clave Fiscal y delegación a Vercel). El trámite con Clave Fiscal y el pago los hace el usuario; vos lo guiás paso a paso.
• .com u otros → comprar en cualquier registrador (o en Vercel) y aplicar el mismo paso de DNS de esa guía.
• En ambos casos, en la terminal del usuario: npx vercel domains add <dominio> <proyecto>, configurar DNS, verificar con npx vercel domains inspect <dominio>. Vercel emite el certificado HTTPS solo.

7. Mensaje de cierre (siempre)

Corto y simple:

• URL publicada (y de preview si aplica) y commit
• Qué se hizo/cambió, en 2–4 puntos
• Decisiones de diseño o contenido que conviene que el usuario valide (tono, colores, datos de ejemplo)
• "Para cambiar algo, decime qué y te muestro una preview antes de publicar."
• TODO pendientes y, si hay dominio .ar, recordatorio de renovación anual