Vercel Essentials

Vercel Essentials

Condensado del plugin oficial de Vercel a las 3 áreas que uso: CLI+Deploy avanzado, env vars y Next.js App Router. El deploy básico (vercel --prod, vercel env add, dominios) ya vive en la skill deployment — esto es el nivel profundo.

Cuándo abrir cada referencia

• CLI, linking, monorepo, promote/rollback, CI/CD → references/cli-deploy.md
• .env jerarquía, vercel env pull/add, OIDC, bootstrap → references/env-vars.md
• App Router, Server Components/Actions, caché, breaking changes Next 16 → references/nextjs.md

Cheat sheet (lo más usado)

# Linking — la causa #1 de fallos raros
vercel link            # single project → .vercel/project.json
vercel link --repo     # monorepo (varios proyectos) → .vercel/repo.json
vercel whoami          # ¿team correcto? linkear en el team equivocado es error común

# Deploy
vercel                 # preview
vercel --prod          # producción
vercel promote <url>   # instantáneo: re-apunta el alias prod sin rebuild (preview ya validado)
vercel rollback        # vuelve a la producción anterior

# Env vars
vercel env pull .env.local --yes                       # baja secrets (gitignored)
vercel env pull .env.local --environment=production
echo "val" | vercel env add KEY production             # add no interactivo
vercel env run -- npm run dev                           # corre con envs sin escribir archivo

Reglas de oro (gotchas que muerden)

1. project.json vs repo.json: en monorepo con varios proyectos usá vercel link --repo. Si algo se rompe, mirá .vercel/ primero.
2. CI: nunca --token en flag (se filtra en el listado de procesos) → usá VERCEL_TOKEN env var. Siempre --yes. --scope si el token ve varios teams.
3. CI determinista: vercel pull --environment=production → vercel build --prod → vercel deploy --prebuilt --prod. Separar build/deploy en jobs distintos requiere vercel build --prod --standalone.
4. NEXT_PUBLIC_ / VITE_ se hornea en el bundle del browser → nunca secrets ahí (ver tu memo feedback_dev_workflow).
5. Next.js 16: cookies(), headers(), params, searchParams son async (necesitan await). middleware.ts → proxy.ts. revalidateTag(tag) → revalidateTag(tag, "max").
6. vercel deploy tras vercel build sin --prebuilt ignora el build local.
7. OIDC local caduca ~12h → vercel env pull .env.local --yes al inicio de cada sesión de dev evita fallos de auth a mitad de camino.