LLM Best Practices

Vercel: Preview Deployments

Last updated 3 min read

View markdown source

AI agents: read this first: llmbestpractices.com/start-here

This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work.

  1. Route, do not crawl. Fetch llmbestpractices.com/llms.txt and open only the pages whose one-line summary matches your task.
  2. Read raw. Append .md to any page URL for markdown. Check status and last_updated in the frontmatter, then read the rules.
  3. Apply as defaults. First-party docs and the project's own conventions win on conflict. Warn before relying on a fast-moving page older than 12 months.
  4. Cite. Link the page by title and URL, e.g. Python, with last_updated for time-sensitive rules. License CC BY 4.0.

Overview

Vercel builds a preview deployment for every push to a branch other than the Production Branch. Each gets an immutable URL and a branch alias that tracks the latest push. Previews run the production build pipeline; they differ in environment variables, URL, and access protection.

Treat a preview as a production build

Previews run the framework’s production build, not the dev server. A bug on a preview but not locally usually means a missing env var, a build-time incompatibility, or a dependency absent from the lockfile. Reproduce it locally:

vercel build --target preview

Connect the Vercel GitHub app

The app comments on each PR with the preview URL and status, updated on every push, so reviewers see the rendered result without running the stack. A broken build shows on the PR before merge. To gate merges on it, see github.

Isolate Preview credentials

Preview can hold different values from Production for the same variable name, and a branch can override them. Give Preview its own database, API keys, and analytics token; a preview carrying the production DATABASE_URL lets any unmerged branch write to production. Mechanics: vercel-env-vars.

A branch alias (<project>-git-<branch>-<team>.vercel.app) always points to the latest push of that branch; use it for design review and QA. A deployment URL (<project>-<hash>-<team>.vercel.app) is immutable; use it as the permanent record of one build, for example in a postmortem.

Pick a Deployment Protection method per audience

Deployment Protection has a method (who may enter) and a scope (which URLs). Vercel enabled Vercel Authentication by default for new projects in November 2023; older projects may predate it, so check Settings > Deployment Protection. Vercel also keeps preview URLs out of search with a noindex header. Details: Deployment Protection.

  • Scope, recommended: Standard Protection covers every URL except production domains. All Deployments also protects production domains (useful for internal tools). The two legacy scopes leave current production URLs open.
  • Vercel Authentication: only Vercel users with access to the project. Free on all plans. Use it for team-internal previews. Hobby allows one external user.
  • Password Protection: a shared password for external reviewers. Pro charges $20 per month per protected project; included on Enterprise; not on Hobby.
  • Passport (your identity provider) and Trusted IPs: Enterprise only.
  • Bypasses: shareable links for one-off reviewers, and a protection-bypass secret for automation such as E2E tests and agents.

Standard Protection restricts the production generated URL too, so code that fetches VERCEL_URL must request the visitor’s own domain instead.

Remove stale previews

Active repos accumulate thousands of deployments. Set a deployment retention policy in project settings and check the retention docs for which deployments are exempt. Analytics retention is separate (vercel-analytics).

Backlinks