How to Set Up Preview Environments in Vercel
Preview environments eliminate the 'works on my machine' problem by giving every pull request a live, shareable URL running the exact code from that branch. Designers can review visual changes, PMs can test feature behavior, and QA can run through test cases without waiting for a staging deploy. It compresses the feedback loop from days to minutes.
Vercel's preview deployment system is automatic: every push to a branch connected to your Vercel project generates a unique URL within seconds. But the default setup works for simple static sites, not production applications with backends, databases, and authentication. This guide covers configuring preview environments that actually work for real applications with all their dependencies.
Step-by-step guide
Connect your repository to Vercel
In the Vercel dashboard, click 'New Project' and import your GitHub repository. Select the framework preset that matches your project (Next.js, Vite, etc.). Set the root directory if your frontend is in a subdirectory like 'apps/web.' Configure the build command and output directory. Once connected, Vercel automatically creates a preview deployment for every push to any branch except the production branch.
- Import your GitHub repository into Vercel
- Set the correct framework preset and root directory
- Verify the build command and output directory
Configure environment variables for preview
Navigate to your project's Settings > Environment Variables in Vercel. Add variables specific to preview environments. Your API URL should point to a staging or development backend, not production. Authentication callback URLs need to include the Vercel preview domain pattern. Database connections should use a staging database. Set each variable's scope to 'Preview' so it only applies to preview deployments, keeping production variables separate.
- Set API_URL to your staging backend for preview deployments
- Configure auth callback URLs to accept Vercel preview domains
- Set database and service URLs to staging instances
Set up preview-specific authentication
Preview deployments get unique URLs like 'your-project-abc123.vercel.app,' which breaks OAuth redirects. Configure your OAuth provider to accept wildcard redirect URLs matching '*.vercel.app' for development environments. Alternatively, use Vercel's password protection feature to gate preview URLs with a shared password, which also prevents search engines from indexing preview content.
Configure the backend for preview environments
Your frontend preview needs a backend to talk to. For simple cases, point all previews at your existing staging API. For isolated testing, use Vercel's monorepo support to deploy both frontend and API as preview environments, or use environment-based feature flags to enable preview-specific behavior on your staging backend. The key is that preview environments should never write to production databases or call production APIs.
- Point preview API_URL to staging backend
- Verify CORS settings allow preview domain origins
- Ensure staging data is safe for testing
Add preview comments to pull requests
Enable Vercel's GitHub integration to automatically comment on every PR with the preview URL. The comment includes a direct link to the deployment and the deployment status. Set up Vercel's 'Preview Deployments' check as a required status check in GitHub branch protection so PRs cannot merge if the preview build fails. This ensures every mergeable PR has a working, testable deployment.
Set up Vercel Toolbar for team feedback
Enable Vercel's Toolbar in your project settings. The toolbar appears on preview deployments and lets team members leave visual feedback directly on the page by clicking and commenting. Comments are posted back to the GitHub PR as review comments. This is invaluable for design review: a designer can click on a misaligned element, leave a comment, and the developer sees the exact location and screenshot in their PR.
Configure deployment protection and cleanup
In project settings, configure deployment protection to require Vercel authentication for preview URLs, preventing unauthorized access to in-development features. Set up automatic deployment expiration so preview deployments older than 30 days are automatically deleted, preventing resource waste. For sensitive projects, enable deployment protection that requires team member login before viewing any preview URL.
Common mistakes
Pointing preview environments at production APIs
Preview deployments that call production APIs risk creating test data in production, triggering real emails to customers, or processing test payments through live payment processors. Always configure preview environment variables to point at staging or development backends.
Not configuring CORS for preview domains
Preview URLs are different from your production domain, so CORS policies that only allow your production origin will block API requests from preview deployments. Configure your staging API's CORS settings to accept requests from '*.vercel.app' or use a wildcard during development.
Ignoring build time optimization
If preview builds take 10 minutes, the feedback loop advantage disappears. Use Vercel's build cache, enable incremental static regeneration where applicable, and consider using 'turbo' for monorepo builds. Most preview deployments should build in under 2 minutes.
Not testing the preview build configuration
Preview deployments use different environment variables than production. A build that works in production can fail in preview if a required variable is missing from the preview scope. After initial setup, verify a preview deployment works end-to-end including API calls, authentication, and critical user flows.
Tips
Add a visual banner to your app in preview mode that shows the branch name and commit SHA, so team members always know which version they are testing.
Use Vercel's 'Ignored Build Step' feature to skip builds for branches that only change files outside your frontend directory, saving build minutes in monorepo setups.
Create a Slack notification when preview deployments are ready, so designers and PMs who requested the change are notified without polling the PR.
Set up end-to-end tests with Playwright or Cypress that run against the preview URL as a GitHub check, catching integration issues before manual review.
How Vantage helps
Vantage helps PMs review feature implementations efficiently by connecting PRD requirements to the pull requests that implement them. When a preview environment is ready, PMs can test the deployment against the specific requirements defined in Vantage, providing structured feedback that references the original spec rather than ad-hoc observations.