How to set up preview deployments on Vercel

intermediate 8 min read Updated 2026-03-13

Quick Answer

Preview deployments on Vercel automatically trigger for non-production branches and pull requests when connected to Git, generating unique URLs for testing. Production deploys only on the main branch while other branches/PRs go to Preview environment. Setup takes 10-20 minutes via dashboard with optional environment variables for Preview scope.

Prerequisites

GitHub, GitLab, or Bitbucket repository with your project code
Vercel account (free tier works)
Project code pushed to repository
Optional: Vercel CLI installed via <code>npm install -g vercel</code>
Basic Git workflow familiarity

Step-by-Step Instructions

Create New Project and Import Git Repository

Log in to vercel.com and click New Project in the dashboard. Select Import Git Repository, authorize Vercel to access your Git provider (e.g., GitHub), and choose your repository. Vercel auto-detects the framework preset like Next.js or Create React App. Confirm Project Name (auto-generated), leave Root Directory as ./, use defaults for Build & Output Settings (e.g., npm run build), then click Deploy for initial production URL on default branch.

Verify Git Integration and Preview Settings

In the Vercel dashboard, select your project and go to Settings > Git. Confirm Production Branch is main (or master)—pushes here trigger Production deploys. Set Preview Branch Limit (default: 200 concurrent previews). Add branches to Ignore Builds if needed (e.g., docs). Verify or override Framework Preset. Save changes to activate previews for non-production branches/PRs.

Previews auto-generate unique URLs for branches/PRs by default.

Configure Preview Environment Variables

Go to Settings > Environment Variables and add variables scoped to Preview environment. Example: NEXT_PUBLIC_API_URL = https://staging-api.example.com. Vercel auto-injects VERCEL_ENV=preview and VERCEL_URL=<unique-preview>.vercel.app. Use in code like:

const apiUrl = process.env.VERCEL_ENV === 'preview' 
  ? process.env.NEXT_PUBLIC_API_URL 
  : 'https://api.example.com';

Click Add and Save.

Scope vars correctly to avoid 'Missing DATABASE_URL in preview' errors.

Install Vercel CLI (Optional for Local Testing)

Install globally with npm install -g vercel for local preview deploys, env pulling, and logs. Useful commands: vercel for preview, vercel --prod for production, vercel env add for scoped variables, vercel logs [deployment-url] for troubleshooting.

CLI helps replicate Preview env locally.

Test Preview Deployment via Git Branch

Create feature branch: git checkout -b feature/test-preview. Make changes, commit, and push: git add . && git commit -m "Test preview" && git push origin feature/test-preview. Open PR to main in Git provider. Vercel auto-triggers Preview build—check Deployments tab for status.

Access and Share Preview URL

When Ready, get unique URL like https://project-feature-test-preview-abcd1234.vercel.app. View logs, inspect build. Use Share button for team access or copy URL. Team members with project access can comment and view live preview.

Vercel posts preview URL in PR comments automatically.

Customize with vercel.json (Optional)

Add vercel.json in project root for custom build commands, output directories, or redirects. Example for static sites:

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist"
}

Vercel uses this if framework preset fails detection.

Overrides dashboard settings for advanced configs.

Manage Deployments in Dashboard

From Deployments sidebar: Redeploy specific commits, Inspect logs, assign custom domains, or Promote to Production. Monitor Preview vs Production environments.

Common Issues & Troubleshooting

No preview deployment triggers

Ensure repo imported via Dashboard > New Project > Import Git. Push to non-<code>main</code> branch or open PR. Verify Git webhook in Settings > Git > Enable deployments.

Environment variables missing in preview

Scope vars to <strong>Preview</strong> in Settings > Environment Variables. Use <code>vercel env add <var> preview</code> via CLI. Check <code>VERCEL_ENV</code> in code.

Build failures on preview

Inspect logs in Deployments tab. Verify framework preset, build command, or add <code>vercel.json</code>. Ignore problematic branches in Git settings.

Preview limit exceeded

Increase <strong>Preview Branch Limit</strong> in Settings > Git (default 200). Older previews auto-expire.

No PR comment with preview URL

Confirm Git integration and webhook. Check Deployments tab manually or ensure Git provider permissions.

Visit Vercel View Vercel Pricing