How to use `vercel deploy` safely and efficiently

Decloak is an AI-powered web security intelligence platform that scans a site's HTTP/TLS posture, JavaScript, and third-party scripts to produce a report anyone can read. This guide is part of Decloak's library of practical, source-backed security guidance.

Key takeaways

• Use vercel deploy from the project root for a quick preview deployment.
• Add --prod to promote a deployment to the production domain.
• Prefer --prebuilt after vercel build for faster, cache - aware uploads.
• Supply runtime and build - time env vars with --env and --build-env.
• Automate without prompts using --skipAutoDetectionConfirmation or the REST API flags.

What does vercel deploy actually do?

vercel deploy uploads the current project, runs a build in Vercel’s isolated VM, and creates a new deployment URL that is printed to stdout. The URL points to a preview by default unless --prod is used.

The CLI creates a hidden .vercel folder that stores the project and organization IDs. After the build, static assets go to a globally distributed CDN and Serverless/Edge Functions are stored in Vercel’s function store. The edge network then routes requests via anycast routing and a private backbone, applying DDoS mitigation and TLS termination before serving content.

How do I create a preview deployment in one command?

Run vercel (or vercel deploy) from the project root. The command will:

1. Detect the framework automatically.
2. Upload source files.
3. Trigger a build in the VM.
4. Stream build logs (if --logs is added).
5. Print a preview URL to stdout.

Example:

cd my-next-app
vercel --logs

The --logs (-l) flag streams the build logs so you can see progress in real time.

How do I promote a deployment to production?

Add the --prod flag. The first deployment of a new project is automatically production; subsequent deployments need --prod to replace the production URL.

vercel --prod

If you want to promote later without a new upload, use vercel promote <deployment-id> after the fact.

When should I use --prebuilt versus a normal deploy?

Run vercel build first to generate the .vercel/output directory, then deploy with --prebuilt:

vercel build
vercel deploy --prebuilt

--prebuilt uploads the already - built output, avoiding a second VM build and making large projects faster. It is the recommended path for CI pipelines that separate build and deploy steps.

How can I pass environment variables safely?

• Runtime variables: --env KEY=VALUE (shorthand -e). These are available to Serverless/Edge Functions at request time.
• Build - time variables: --build-env KEY=VALUE (shorthand -b). These affect the build process (e.g., NEXT_PUBLIC_API_URL).

vercel --env API_KEY=abc123 --build-env NODE_ENV=production

Do not commit secrets into source; use the CLI flags or Vercel’s dashboard to keep them hidden.

How do I control where Functions run?

Use the --regions flag with a comma - separated list of Vercel edge regions.

vercel --regions iad,cdg,sfo

Only the listed regions will host your Serverless Functions, reducing latency for target users.

What if I need a faster upload for a very large project?

Compress the upload with --archive tgz or --archive zip.

vercel --archive tgz

Compression reduces the amount of data transferred, but it disables incremental file - caching, so subsequent deployments may be slower.

How can I run vercel deploy in CI without interactive prompts?

Add the REST - API flag --skipAutoDetectionConfirmation to suppress framework detection prompts, or use the REST API directly with skipAutoDetectionConfirmation=1.

vercel deploy --skipAutoDetectionConfirmation

For a guaranteed fresh build, add --force (or forceNew=1 via the API). Pair --force with --with-cache to keep the build cache.

How do I skip automatic domain promotion?

Include --skip-domain. The deployment will be created without assigning a custom domain; you can later run vercel promote <deployment-id> to attach one.

vercel --skip-domain

This is useful for staging environments where you want a preview URL only.

What are the most common mistakes to avoid?

How can I integrate vercel deploy into a script?

A minimal Bash script for CI/CD:

#!/usr/bin/env bash
set -euo pipefail
# Build first (optional for pre - built flow)
vercel build
# Deploy with prebuilt output, force a fresh build, and skip prompts
vercel deploy \
 --prebuilt \
 --prod \
 --force \
 --skipAutoDetectionConfirmation \
 --env API_URL=$API_URL \
 --build-env NODE_ENV=production

The script exits with a non - zero code if the deployment fails, making it CI - friendly.

Where can I find more detailed documentation?

• Official CLI reference: https://vercel.com/docs/cli/deploy
• REST API deployment guide: https://vercel.com/docs/rest-api/deployments/create-a-new-deployment
• Infrastructure overview: https://vercel.com/docs/fundamentals/infrastructure

This article is based on Vercel’s official documentation as of September 2024.