vercel__vercel-plugin/commands/deploy.md

description

description
Deploy the current project to Vercel. Pass "prod" or "production" as argument to deploy to production. Default is preview deployment.

Deploy to Vercel

Deploy the current project to Vercel using the CLI, with preflight safety checks, explicit production confirmation, and post-deploy verification.

Preflight

Run these checks before any deployment. Stop on failure and print actionable guidance.

1. CLI available? — Confirm vercel is on PATH.
   • If missing: npm i -g vercel (or pnpm add -g vercel / bun add -g vercel).
2. Project linked? — Check for .vercel/project.json in the current directory or nearest parent.
   • If not found: run vercel link interactively, then re-run /deploy.
3. Monorepo detection — Look for turbo.json or pnpm-workspace.yaml at the repo root.
   • If detected: confirm which package is targeted. If ambiguous, ask the user before proceeding.
4. Uncommitted changes — Run git status --porcelain.
   • If output is non-empty: warn the user that uncommitted changes will not be included in the deploy. Ask whether to continue or commit first.
   • If not a git repo, skip this check.
5. Observability preflight (production deploys only) —

Before promoting to production, verify observability readiness:

• Drains check: Query configured drains via MCP list_drains or REST API. If no drains are configured on a Pro/Enterprise plan, warn:

  ⚠️ No drains configured. Production errors won't be forwarded to external monitoring. Configure drains via Dashboard or REST API before promoting.

• Errored drains: If any drain is in error state, warn and suggest remediation before deploying:

  ⚠️ Drain "" is errored. Fix or recreate before production deploy to avoid monitoring gaps.

• Error monitoring: Check that at least one of these is in place: configured drains, an error tracking integration (e.g., Sentry, Datadog via vercel integration ls), or @vercel/analytics in the project.
• These are warnings, not blockers — the user may proceed after acknowledgment.

Plan

State the intended action before executing:

• Preview deploy (default): vercel — creates a preview deployment on a unique URL.
• Production deploy: vercel --prod — deploys to production domains.

If "$ARGUMENTS" contains "prod" or "production":

⚠️ Production deployment requested. This will deploy to your live production URL and affect real users. Ask the user for explicit confirmation before proceeding. Do not deploy to production without a clear "yes."

If "$ARGUMENTS" does not indicate production:

Deploying a preview build. This creates an isolated URL and does not affect production.

Commands

Preview Deployment

# Deploy from project root (creates preview URL)
vercel

# Equivalent explicit form
vercel deploy

Preview deployments are created automatically for every push to a non-production branch when using Git integration. They provide a unique URL for testing.

Production Deployment (requires confirmation)

# Deploy directly to production
vercel --prod
vercel deploy --prod

# Force a new deployment (skip cache)
vercel --prod --force

Capture the full command output. Extract the deployment URL from the output (the line containing the .vercel.app URL or custom domain URL).

Record the current git commit SHA for the summary:

git rev-parse --short HEAD

Verification

After deployment completes, verify the result:

1. Inspect the Deployment

# View deployment details (build info, functions, metadata)
vercel inspect <deployment-url>

# List recent deployments
vercel ls

# View logs for a deployment
vercel logs <deployment-url>
vercel logs <deployment-url> --follow

Extract: deployment state (READY / ERROR / QUEUED / BUILDING), build duration, framework, Node.js version, function count.

2. On Failure — Fetch Build Logs

If the deployment state is ERROR or the deploy command exited non-zero:

vercel logs <deployment-url>

Present the last 50 lines of build logs to help diagnose the failure. Highlight any lines containing error, Error, ERR!, or FATAL.

3. On Success — Quick Smoke Check

If the deployment state is READY, note the URL is live and accessible.

4. Post-Deploy Error Scan (production deploys)

For production deployments, wait 60 seconds after READY state, then scan for early runtime errors:

vercel logs <deployment-url> --level error --since 1h

Or via MCP if available: use get_runtime_logs with level filter error.

Interpret results:

Finding	Action
No errors	✓ Clean deploy — no runtime errors in first hour
Errors detected	List error count and first 5 unique error messages. Suggest: check drain payloads for correlated traces, review function logs in Dashboard
500 status codes in logs	Correlate timestamps with drain data (if configured) or vercel logs <url> --json for structured output. Flag for immediate investigation
Timeout errors	Check function duration limits in vercel.json or project settings. Consider increasing maxDuration

Fallback (no drains):

If no drains are configured, the error scan relies on CLI and Dashboard:

# Stream live errors
vercel logs <deployment-url> --level error --follow

# JSON output for parsing
vercel logs <deployment-url> --level error --since 1h --json

For richer post-deploy monitoring, configure drains to forward logs/traces to an external platform via Dashboard or REST API.

Summary

Present a structured deploy result block:

## Deploy Result
- **URL**: <deployment-url>
- **Target**: production | preview
- **Status**: READY | ERROR | BUILDING | QUEUED
- **Commit**: <short-sha>
- **Framework**: <detected-framework>
- **Build Duration**: <duration>

If the deployment failed, append:

- **Error**: <summary of failure from logs>

For production deploys, also include:

### Post-Deploy Observability
- **Error scan**: <N errors found / clean> (scanned via vercel logs --level error --since 1h)
- **Drains**: <N configured / none>
- **Monitoring**: <active / gaps identified>

Next Steps

Based on the deployment outcome:

• Success (preview) → "Visit the preview URL to verify. When ready, run /deploy prod to promote to production."
• Success (production) → "Your production site is live. Run /status to see the full project overview."
• Build error → "Check the build logs above. Common fixes: verify build script in package.json, check for missing env vars with /env list, ensure dependencies are installed."
• Missing env vars → "Run /env pull to sync environment variables locally, or /env list to review what's configured on Vercel."
• Monorepo issues → "Ensure the correct project root is configured in Vercel project settings. Check vercel.json for rootDirectory."
• Post-deploy errors detected → "Review errors above. Check vercel logs <url> --level error for details. If drains are configured, correlate with external monitoring."
• No monitoring configured → "Set up drains or install an error tracking integration before the next production deploy. Run /status for a full observability diagnostic."