# Vercel Essentials

> Vercel a profundidad — CLI avanzado, CI/CD, env vars y patrones Next.js App Router (Next 16). Reemplaza al plugin oficial de Vercel (43 skills) condensado a lo esencial. Complementa a `deployment` (que cubre el deploy básico). Usar cuando: "vercel link", "monorepo vercel", "vercel build --prebuilt", "vercel promote", "vercel rollback", "CI/CD vercel", "GitHub Actions vercel", "VERCEL_TOKEN", "vercel env pull", "OIDC token", "VERCEL_OIDC_TOKEN", "project.json vs repo.json", "App Router", "server component async", "cookies() headers() params async", "middleware proxy.ts", "revalidateTag", "next/router next/navigation", "getServerSideProps migrar", "next 16 breaking changes". Do NOT use for: deploy básico a Vercel (usar `deployment`), Railway, Express puro, ni AI SDK/Workflow/shadcn del plugin (esos quedaron fuera del recorte — reactivar el plugin oficial si se necesitan).

- Skill: `apolo-81/vercel-essentials` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add apolo-81/vercel-essentials`
- Raw SKILL.md: https://api.skillmd.com/api/skills/apolo-81/vercel-essentials/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: apolo-81 (https://skillmd.com/u/apolo-81)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/apolo-81/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)

```bash
# 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.