LLM Best Practices

Vercel: Preview Deployments

4 min read

View markdown source

Overview

Vercel creates a preview deployment for every push to any branch connected to the project. Each preview has a stable URL for that commit and a branch alias that updates on every push to that branch. Preview deployments run the full production build pipeline, the same runtime, and the same edge functions as production. The only differences are the environment variable scope and the URL. This page covers how to use previews correctly, scope credentials safely, and add access controls when needed.

Treat preview deployments as production builds, not as dev servers

Preview builds run next build (or the equivalent framework build) with full optimization, minification, and static generation. They are not next dev builds. A bug that appears on preview but not locally almost always means a missing env var, a build-time incompatibility, or a dependency that is not installed in the production lockfile.

When a preview fails but local dev works, run vercel build locally to reproduce the build environment:

vercel build --target preview

This runs the build in a sandbox that mirrors the Vercel CI environment. See vercel for the full build cache details and vercel-env-vars for pulling env vars locally.

The Vercel GitHub integration posts a comment on every PR with the preview URL, deployment status, and build duration. Enable it in the Vercel project settings under “Git.”

Once enabled, every push to a PR branch posts an updated comment. Reviewers click the link and see the rendered output without deploying locally. This is the primary value of preview deployments: asynchronous visual review by team members who do not run the stack locally.

The comment also surfaces build errors inline on the PR, so a broken build is visible before merge. See github for the GitHub Actions integration that can gate merges on a successful preview build.

Scope env vars to Preview separately from Production

The three Vercel environments (Development, Preview, Production) accept different values for the same variable name. Set credentials for a staging database on Preview and the production database credentials on Production only.

DATABASE_URL (Production)  = postgres://prod-user:...@prod-host/prod-db
DATABASE_URL (Preview)     = postgres://preview-user:...@staging-host/staging-db
DATABASE_URL (Development) = postgres://localhost/local-db

A PR preview that carries the production database URL is a misconfiguration. If a developer merges a bad migration, the preview ran it against production. Keep Preview completely isolated from Production credentials. See vercel-env-vars for the scoping mechanism.

Every branch gets a stable alias of the form <project>-git-<branch>-<team>.vercel.app. This URL updates on every push to the branch. Use it in design reviews, QA tickets, and stakeholder demos.

Branch alias: myapp-git-feat-dashboard-acme.vercel.app
Commit URL:   myapp-abc123-acme.vercel.app (immutable, points to that commit)

The branch alias is mutable. Link to it in a Jira ticket, and the reviewer always sees the latest push. Link to a commit URL when you need a permanent record of a specific build, for example in a post-mortem or a changelog.

Add password protection for previews exposed to external stakeholders

Preview deployments are publicly accessible by default. Anyone with the URL can view them. When a feature branch contains unreleased product changes, add password protection through Vercel’s “Deployment Protection” setting (available on Pro and Enterprise plans).

Password protection prompts for a shared password before serving the preview. Use it for:

  • Unreleased features shown to external partners.
  • Client previews that should not appear in search engine indexes.
  • QA builds with internal data.

For team-internal previews, Vercel’s “Vercel Authentication” option limits access to members of the Vercel team, which is stricter than a shared password.

Clean up stale preview deployments with retention limits

By default, Vercel retains all preview deployments. On active repos, this accumulates thousands of deployments over time. Set a retention limit in the project settings to automatically remove previews older than a threshold.

Retention settings do not affect the Production deployment or branch aliases. Only stale commit-specific previews are removed. Set the retention to match the PR lifecycle: if PRs typically close within two weeks, a 30-day retention keeps all recent work accessible without accumulating indefinitely. See vercel-analytics for the analytics data retention considerations that are separate from deployment retention.

Graph View

Backlinks