# Pathrule Pattern: Vercel Deployment (1.0.0) # ::pathrule:package:vercel-deploy ### [RULE] Preview first, then promote to production (path: /) Production traffic only ever serves a deployment that was first validated as a preview. - Land changes on a non-production branch or PR so Vercel builds a preview, and run health checks against that preview URL before promoting. - Promote the exact preview build with `vercel promote ` or the dashboard Promote action instead of re-merging, so the bytes serving production are the bytes you tested. - Keep instant rollback usable: a known-good earlier production deployment must always exist, since rollback just reassigns the domain rather than rebuilding. - Treat the production branch (usually `main`) as protected; do not force-push or rebase history that has been deployed. --- ### [RULE] Scope secrets to the server and the right environment (path: /) Environment variables are scoped per environment and never leak server secrets to the browser. - Only prefix a variable with `NEXT_PUBLIC_` when it is safe in client JS; everything else (API keys, DB URLs, tokens) stays server-only. - Set distinct values per environment (Production, Preview, Development) rather than reusing production credentials in previews. - Mark credentials as Sensitive so Vercel redacts them in logs and the UI, and never commit `.env*` files; pull with `vercel env pull` for local dev. - For backend access (AWS, GCP, Azure, databases), prefer OIDC Federation via `VERCEL_OIDC_TOKEN` (TTL ~60 min, cached ~45 min) to get short-lived tokens instead of long-lived static secrets. --- ### [MEMORY] vercel.json and project-level configuration conventions (path: /) vercel.json is the file-based configuration layer that version-controls routing, headers, and per-function overrides. Know what it can and cannot do. - Use `vercel.json` for: `rewrites`, `redirects`, `headers`, `cleanUrls`, `trailingSlash`, per-function `maxDuration` and `runtime` overrides, and `crons`. - Do NOT put environment variable values in `vercel.json`; they belong in the Vercel dashboard or `vercel env add`. The file is committed to the repo and world-readable. - Memory cannot be set in `vercel.json` when Fluid Compute is enabled; configure it in the project dashboard under Functions. Fluid Compute is on by default for new projects, raising the Pro `maxDuration` ceiling to 800 s. - Avoid setting `version: 2` explicitly; it is the default and the only supported schema. An old `version: 1` in the file disables modern routing features. - Framework-detected projects (Next.js) apply their own output directory and command defaults; overriding `outputDirectory` or `buildCommand` in `vercel.json` for a Next.js app usually breaks the build unless you know exactly why. --- ### [MEMORY] Function runtime config with Fluid Compute (path: /) Fluid Compute is the default execution model for new Vercel projects as of 2025, and it changes how function limits behave. - Set `maxDuration` per function in `vercel.json` (or via route segment config in Next.js); with Fluid Compute the Pro max rises to 800s, versus 300s without it. - Memory can no longer be set in `vercel.json` when Fluid Compute is on; configure it under Functions in the project dashboard. - Choose the runtime deliberately: Edge for low-latency middleware and lightweight routes, Node.js for heavier or dependency-rich work. - Use Cron Jobs for scheduled invocations rather than external pingers, and keep cold-start-sensitive paths lean. --- ### [MEMORY] Caching and ISR on the Vercel CDN (path: /app) Next.js sets `Cache-Control` from the rendering strategy, and Vercel's CDN serves those responses; on-demand invalidation must reach both layers. - Static pages emit `s-maxage=31536000`; ISR pages emit `s-maxage={revalidate}` with `stale-while-revalidate` so users get fast pages that refresh in the background. - With Cache Components (`use cache`), set lifetime via `cacheLife` and label entries with `cacheTag` for targeted invalidation. - Invalidate on mutation with `revalidateTag` / `revalidatePath` (or `updateTag`); these clear the Next.js cache and Vercel propagates the CDN purge for those keys. - Avoid `revalidate = 0` or fully dynamic rendering on hot pages unless the data truly cannot be cached; it eliminates CDN offload entirely and increases function invocation cost. --- ### [SKILL] vercel-deploy-review (path: /) --- name: vercel-deploy-review description: Run this checklist before promoting any Vercel deployment to production. Covers preview validation, environment variables, function config, caching, and rollback readiness for Next.js apps on Vercel in 2026. --- # Vercel deployment review - [ ] Change landed on a non-production branch or PR and produced a green preview deployment. - [ ] Preview URL passed health checks and key flows; build logs show no errors or unredacted secrets. - [ ] No server secret is exposed via a `NEXT_PUBLIC_` variable; secrets are marked Sensitive. - [ ] Environment variables are set per environment (Production/Preview/Development), with no production credentials reused in previews. - [ ] Backend access uses OIDC (`VERCEL_OIDC_TOKEN`) or short-lived credentials where possible. - [ ] `vercel.json` does not contain env var values, does not override `outputDirectory`/`buildCommand` for a Next.js app without good reason, and has no `version: 1`. - [ ] `maxDuration` and runtime (Edge vs Node.js) are correct for each function; if Fluid Compute is on, memory is set in the dashboard, not `vercel.json`. - [ ] Caching is intentional: ISR `revalidate` / `cacheLife` set, hot pages tagged with `cacheTag`, mutations call `revalidateTag` / `revalidatePath`. - [ ] A known-good prior production deployment exists so instant rollback is available. - [ ] Promotion will reuse the tested preview build (`vercel promote` or dashboard Promote), not a fresh rebuild.