vercel-deploy-checklist

Vercel Deploy Checklist

A 12-point audit you run before every Vercel production deploy. Each item is a hard gate unless the project explicitly opted out. Fail loud, fix the root cause, never --force past a broken check.

When to use

Trigger this skill when any of these apply:

• User says "deploy to production" / "ship it" / "promote preview" / "go live".
• A vercel deploy --prod or vercel --prod command is about to run.
• A PR is about to be merged that targets the production branch.
• A release tag is about to be cut for a Vercel-hosted app.

Do not trigger for: local next dev, preview-only deploys without user prompting, isolated component work, or non-Vercel hosts (Cloudflare Pages, Netlify, self-hosted Node).

The 12-point checklist

Walk through these in order. Stop on the first failure, fix, then resume.

[ 01 ] Environment variables

• Compare .env.example against vercel env ls production — every key in the example must exist in production (and preview if the app uses preview-specific data).
• No secrets in .env.local that aren't also in Vercel.
• NEXT_PUBLIC_* vars only contain things safe to ship to the browser.

vercel env ls production

[ 02 ] Build green locally

Run the same command Vercel runs (from vercel.ts / vercel.json → buildCommand). A green local build is non-negotiable.

pnpm turbo run build --filter=@<app>
# or whatever the build command is

[ 03 ] Typecheck + lint clean

• tsc --noEmit exits 0.
• Linter (eslint / biome) exits 0 with no warnings on changed files.

[ 04 ] No console.log in production paths

grep -rn "console\\.log" apps/web/app apps/web/components apps/web/lib | grep -v test

Allowed: console.error / console.warn in error-handling paths. Everything else → remove or guard with if (process.env.NODE_ENV === 'development').

[ 05 ] SEO essentials present

• app/robots.ts returns the correct rules for the environment.
• app/sitemap.ts enumerates every public route.
• Every public route has generateMetadata with title + description + canonical.
• Per-page OG image route or static OG fallback exists.

[ 06 ] Structured data on key pages

• Landing / detail pages emit <script type="application/ld+json"> with the right schema.org type.
• Validate one URL with Schema Markup Validator.

[ 07 ] Image + font optimization

• All <img> replaced by next/image (or framework equivalent).
• Custom fonts loaded via next/font with display: 'swap'.
• Hero images use priority prop; below-the-fold use lazy default.

[ 08 ] Security headers

In next.config.ts (or vercel.ts headers):

• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY (or CSP frame-ancestors)
• Referrer-Policy: strict-origin-when-cross-origin
• Permissions-Policy set (camera/microphone/geolocation disabled unless used)

[ 09 ] Runtime + region config

• Default runtime is nodejs (Fluid Compute) — only use edge where measurably needed.
• Cron jobs in vercel.ts use realistic schedules + idempotent handlers.
• Function maxDuration set on long-running routes (webhooks, sync jobs).

[ 10 ] Analytics + telemetry wired

• @vercel/analytics mounted in root layout if web traffic matters.
• @vercel/speed-insights mounted if Core Web Vitals matter.
• Custom events instrumented for at least one key conversion.

[ 11 ] Domain + redirects

• Production domain assigned to the correct project.
• www ↔ apex redirect configured (one canonical host).
• Legacy URLs from prior deploys have redirects in vercel.ts redirects[].

[ 12 ] Rollback plan

• Previous deployment is still accessible at its preview URL — note the URL before promoting.
• Database migrations applied in this deploy are reversible OR a backup was taken first.
• Feature flags exist to disable risky new code without redeploying.

Output format

When this skill runs, produce a table like:

[ 01 ] env vars ............ PASS
[ 02 ] build green .......... PASS
[ 03 ] typecheck + lint ..... PASS
[ 04 ] no console.log ....... FAIL — 3 occurrences in apps/web/components/checkout.tsx:42,67,89
[ 05 ] SEO essentials ....... PASS
...

Stop at the first FAIL. Do not produce a green-light recommendation until every item is PASS or explicitly waived by the user with a one-line reason.

Anti-patterns

• Do not run this as a passive "lint pass". Each check is a real gate.
• Do not auto-fix without asking — surface issues, let the user decide.
• Do not silently skip items that don't apply. Mark them WAIVED — <reason>.
• Do not promote with any FAIL or WAIVED-without-reason.

Why this exists

Production deploys that fail in subtle ways (missing env var, broken canonical, console.log noise) erode trust faster than feature bugs. A 60-second pre-deploy checklist catches 90 % of these before they ship. Wealthior projects run this before every vercel --prod.