Deploy a React App to Vercel: Complete Guide

By Yanni Papoutsis | 7 min read | 2026-07-04

TL;DR

Vercel is the fastest path from a React repository to a live URL. Import your repo, set environment variables, and you are deployed in under three minutes. This guide covers both the Vite and Create React App build setups, environment variable handling, custom domains, preview deployments per branch, and the Vercel CLI for terminal-driven workflows.

Prerequisites

Why Vercel for React?

Vercel was built by the team behind Next.js and has first-class support for all React-based frameworks. It detects your framework automatically at import time and pre-fills build settings. The free Hobby plan supports unlimited personal projects with 100GB bandwidth per month and automatic HTTPS.

The key differentiator over Cloudflare Pages (see the Cloudflare Pages guide) is Vercel's preview deployment system: every pull request gets its own live URL, commented directly on the PR by the Vercel bot. This makes code review significantly faster for front-end teams.

Step 1: Import Your Repository

  1. Go to vercel.com and log in.
  2. Click Add New > Project in the top right.
  3. Under Import Git Repository, click Continue with GitHub (or your chosen provider).
  4. Authorise the Vercel GitHub app. Grant access to specific repositories rather than all repositories.
  5. Find your React project in the list and click Import.

Step 2: Configure Your Build

Vercel will attempt to auto-detect your framework. For Vite and CRA:

Vite

Vercel detects Vite automatically. The default settings are correct in most cases:

If Vercel selects the wrong preset, click Edit and set it manually.

Create React App

Note: Create React App is no longer actively maintained. The React team now recommends Vite or a meta-framework like Next.js for new projects.

Custom Build Commands

If your project requires pre-build steps (generating types, running code generation, etc.):

# Example: generate GraphQL types before building
npm run codegen && npm run build

Enter this in the Build Command field. Vercel runs it in sequence.

Step 3: Add Environment Variables

Before deploying, add any environment variables your application needs. Click Environment Variables to expand the section.

Important rules for React environment variables:

Vite: variables must be prefixed with VITE_ to be available in the browser bundle.

VITE_API_URL=https://api.yourdomain.com
VITE_SUPABASE_URL=https://your-project-ref.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key-here

Create React App: variables must be prefixed with REACT_APP_.

REACT_APP_API_URL=https://api.yourdomain.com
REACT_APP_SUPABASE_URL=https://your-project-ref.supabase.co

Never put secret keys in front-end environment variables. Variables prefixed with VITE_ or REACT_APP_ are bundled into the JavaScript that is sent to every browser. Use only public keys (such as Supabase anon keys or public API URLs). See the guide on Supabase Auth with Google OAuth for how to structure auth credentials safely.

Vercel lets you scope environment variables to three environments:

Set the same variable name to different values per environment as needed (for example, a staging API URL in Preview and the live API URL in Production).

Step 4: Deploy

Click Deploy. Vercel clones your repository, installs dependencies, runs your build command, and uploads the output to its CDN.

The first deployment typically takes 60 to 120 seconds. You will see a real-time build log:

[09:14:01] Cloning github.com/yourname/your-react-app (Branch: main, Commit: a3f9c12)
[09:14:03] Running "npm install"
[09:14:18] Running "vite build"
[09:14:22] Build Completed in /vercel/output [4s]
[09:14:23] Deploying outputs...
[09:14:24] Deployment complete: https://your-react-app-abc123.vercel.app

Once complete, Vercel shows you:

Step 5: Add a Custom Domain

  1. In your project dashboard, go to Settings > Domains.
  2. Enter your domain name and click Add.
  3. Vercel checks whether your domain is managed by Vercel DNS or external DNS.

Option A: Add the domain to Vercel DNS Transfer your nameservers to Vercel's nameservers. Vercel will manage all DNS records automatically. This is the simplest option.

Option B: Keep external DNS and add CNAME Add a CNAME record at your DNS provider:

Type:  CNAME
Name:  www
Value: cname.vercel-dns.com

For apex domains (bare yourdomain.com without www), use an A record instead:

Type:  A
Name:  @
Value: 76.76.21.21

SSL is provisioned automatically. Propagation typically takes under 10 minutes on Cloudflare DNS and up to 48 hours on slower providers.

Preview Deployments

Every push to a non-production branch creates a preview deployment. This is one of Vercel's most useful features.

When you open a pull request on GitHub, the Vercel bot comments with:

Vercel: Preview deployment ready
URL: https://your-project-git-feature-branch-yourname.vercel.app
Build time: 48s

You and your reviewers can click the URL, test the feature, and leave feedback -- all before merging. Preview deployments use your Preview environment variables, so they can point to a staging API automatically.

To disable preview deployments for a branch:

  1. Go to Settings > Git.
  2. Under Ignored Build Step, add a condition to skip builds from specific branches.

Step 6: Vercel CLI

The Vercel CLI gives you the same power as the dashboard from your terminal.

Install:

npm install -g vercel

Log in:

vercel login

Choose your preferred login method (GitHub, GitLab, email). Your credentials are stored in ~/.local/share/com.vercel.cli.

Link your project:

Navigate to your project directory and run:

vercel link

This links the local directory to your Vercel project, pulling down environment variables and project settings.

Deploy to preview:

vercel

Running vercel without flags deploys to a preview environment and gives you a unique URL.

Deploy to production:

vercel --prod

Pull environment variables to local .env file:

vercel env pull .env.local

This is extremely useful for local development -- you get the exact same variables that run in production without copying and pasting from the dashboard.

Useful CLI commands:

# List all deployments
vercel ls

# Inspect a specific deployment
vercel inspect https://your-project-abc123.vercel.app

# Promote a preview deployment to production
vercel promote https://your-project-abc123.vercel.app

# Roll back production to a previous deployment
vercel rollback

Handling Single Page Application Routing

React apps that use React Router or similar client-side routing need a rewrite rule so that all routes serve index.html. Without this, refreshing on a path like /about returns a 404.

Create a vercel.json in your project root:

{
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/index.html"
    }
  ]
}

Commit this file and redeploy. Vercel will serve index.html for all paths and let React Router handle the routing client-side.

Troubleshooting Common Issues

"Error: No Output Directory named 'dist' found" Your build command did not produce output in the configured directory. Check whether your vite.config.js has a custom build.outDir setting. Update the Vercel output directory to match.

Environment variable not available at runtime Variables in Vite must be prefixed with VITE_. Without the prefix, Vite strips them from the bundle for security. Check your variable names in the Vercel dashboard and in your source code.

SPA routes return 404 on refresh Add the vercel.json rewrite rule described above. This is the most common issue for new React deployments.

Build works locally but fails on Vercel Vercel's build environment runs on Linux. Common causes of local-passes-but-Vercel-fails include: case-sensitive import paths (Windows is case-insensitive, Linux is not), missing peer dependencies, or a postinstall script that requires a build tool not installed on Vercel.

FAQ

Is Vercel free for commercial projects? The Hobby (free) plan prohibits commercial use per Vercel's terms of service. For commercial projects, the Pro plan starts at $20 per month per member. Check vercel.com/pricing for current details.

Can I use Vercel for a full-stack app with an API? Yes. Vercel supports serverless functions in the /api directory alongside your React app. Functions can be Node.js, Python, Ruby, or Go. They scale to zero automatically and bill per invocation on the Pro plan.

How do I set different API URLs for production and staging? Add the same variable name (for example, VITE_API_URL) with different values scoped to the Production and Preview environments in Settings > Environment Variables. Preview deployments will automatically use the staging URL.

What is the build timeout limit? On the free Hobby plan, builds time out after 45 minutes. On Pro, the limit is 45 minutes per function but you can configure longer timeouts for edge functions.

Can Vercel host a monorepo? Yes. Configure the Root Directory in project settings to point to the subdirectory containing your React app. For example, packages/web in a monorepo structure.

Once your React app is live and connected to a backend, check the guide on Supabase Auth with Google OAuth for adding authentication. For AI-powered features in your app, explore 1000+ free AI tools.