Preview Deployments

Imagine testing every single change before it goes live, and letting your teammates review it by clicking ONE link. That's preview deployments in a nutshell.

What Are Preview Deployments?#

A preview deployment is a temporary version of your site that shows the changes you're proposing. Every time you open a pull request on GitHub, Vercel creates one for you automatically.

Think of it as a dress rehearsal before the real show. You get to watch everything work (or totally fall apart) before the audience shows up.

How It Works#

Here's the flow.

Branch --> Edit --> Push --> PR --> Vercel Builds
                                        |
                                        v
              +--- More changes? <-- Preview URL
              |                         |
              v                         v
            Edit                   Approved?
                                        |
                                        v
                              Merge --> Production

Step 1. You Create a Pull Request#

Over on GitHub, you open a pull request to merge your branch into the main branch.

Step 2. Vercel Gets Notified#

Since Vercel is connected to your GitHub repo, it spots the new pull request right away.

Step 3. Vercel Builds a Preview#

Vercel grabs the code from your pull request and builds a complete version of your site, with all your proposed changes baked in.

Step 4. You Get a Unique URL#

Vercel hands you a special URL for this preview. It'll look something like this.

your-project-abc123.vercel.app

Every pull request gets its own unique URL.

Step 5. Vercel Comments on Your PR#

Vercel drops a comment on your pull request with a link to the preview. You and your teammates can click it and see the changes live.

Why Previews Matter#

Catch Bugs Before Production#

Your production site is what real users see, so a bug there is a REAL problem. A bug in a preview? That's just something you fix before merging.

Get Better Feedback#

Instead of "go look at line 42 of this file," you get to say "click this link and look at the header." People can actually see what you're talking about.

Test on Real Infrastructure#

Your preview runs on the same Vercel infrastructure as your production site, so it's WAY closer to the real thing than your laptop is. It's not a guarantee though. Previews use their own environment variables (often test keys and a test database), so something can work in preview and still break in production if those settings don't match. Give production a quick check after you merge.

No Extra Work#

You don't have to do anything special to get previews. Open a pull request and Vercel takes care of the rest.

The Preview Comment#

When Vercel finishes building your preview, it leaves a comment on your pull request with a few things in it.

Preview URL#

The main link to see your changes. Click it to visit the preview site.

Deployment Status#

Tells you whether the build worked or failed. Green means everything's good.

Visit Details#

Links to the deployment logs, a comparison with production, and more.

Here's roughly what that comment looks like in your pull request.

Vercel
 
The latest updates on your project. Learn more
 
Preview: https://your-project-abc123.vercel.app

Preview vs Production URLs#

Let's clear up how Vercel URLs work.

Production is permanent, and it updates when you merge to main.

Previews are temporary. Each pull request gets its own, and it keeps updating as you add commits to that PR.

Sharing Previews with Your Team#

Preview URLs are AWESOME for working with other people. Here's how to put them to use.

In Pull Request Reviews#

When you're reviewing someone's code, open the preview link first. See how the changes actually look and behave, then read the code with that picture in your head.

Getting Design Feedback#

Send the preview link to your designers. They get to see the real thing instead of screenshots or a paragraph trying to describe it.

Stakeholder Approval#

Need a manager or a client to sign off on something? Send them the preview link. They don't need to understand a lick of code to see what's changing. (They do need access though, more on that in Troubleshooting below.)

Testing Different Devices#

Open the preview on your phone, a tablet, or a few different browsers. Make sure everything works before you merge.

What Happens When You Merge?#

Once your pull request is approved and merged, here's the chain reaction.

1. GitHub merges your branch into main
2. Vercel notices the change to main
3. Vercel creates a new production deployment
4. Your changes go live on your main URL

The preview deployment hangs around for a while, but it stops getting updates. It turns into a snapshot of what that pull request looked like.

Managing Previews in the Dashboard#

Your Vercel project dashboard shows all your deployments.

• Production - Your live site
• Previews - All active preview deployments

Click any deployment to see its details, logs and URL.

Troubleshooting Previews#

Preview Not Appearing?#

Check these things.

• Your Vercel project is connected to the right GitHub repo
• The pull request is going to a branch Vercel is watching (usually main)
• The build didn't fail (check your GitHub PR for error messages)

Preview Shows Old Content?#

Try pushing another commit to the PR. That kicks off a fresh preview build.

Can't Access the Preview URL?#

Preview URLs are NOT public by default. New Vercel projects turn on Deployment Protection, which means anyone opening a preview has to log in with a Vercel account that has access to your project. That's why your client hits a login screen. To let someone in without a Vercel account, create a Shareable Link from the deployment (the Hobby plan only gets one of those per account), or change the protection settings under Settings, then Deployment Protection.

TL;DR#

• Every pull request gets its own preview deployment
• Preview URLs let you test changes before they hit production
• Vercel comments on your PRs with the preview link
• Previews update on their own when you push new commits
• Sharing preview URLs makes working with teammates way easier

What's Next?#

You know how to deploy and preview now. But what about configuration? Next lesson we're getting into environment variables.