Vercel Basic How-To Tutorial

What Vercel Is

Vercel is a deployment and hosting platform for modern web projects. It is especially popular for frontend projects such as React, Vite, Astro, Next.js, and static HTML/CSS/JavaScript sites.

A simple way to think about it is this:

GitHub stores your code.
Vercel builds and publishes your website.

When you connect a GitHub repository to Vercel, Vercel can automatically deploy your project every time you push new code.

Why Use Vercel?

Vercel is useful when you want to:

• Put a website online quickly.
• Deploy directly from GitHub, GitLab, or Bitbucket.
• Create preview deployments before making changes live.
• Host static websites, React apps, Vite apps, Astro sites, and Next.js apps.
• Add custom domains such as yourdomain.com.
• Manage environment variables for API keys and configuration values.

The Basic Vercel Workflow

The standard Vercel workflow looks like this:

Write code locally
      ↓
Push code to GitHub
      ↓
Import the project into Vercel
      ↓
Vercel builds the project
      ↓
Vercel gives you a live URL
      ↓
Every new Git push creates a new deployment

This makes Vercel feel like a publish button connected to your Git repository.

Before You Deploy

Before sending your project to Vercel, make sure it works on your own computer.

For many JavaScript projects, you should run:

npm install
npm run dev

Then test the production build:

npm run build

If npm run build fails locally, it will probably fail on Vercel too. Fix the local build first.

Common Build Settings

Vercel usually detects your framework automatically, but it helps to understand the common settings.

Push Your Project to GitHub

Vercel works best when your project is stored in a Git repository. If your project is not already on GitHub, you can create a repository and push your code.

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin YOUR_GITHUB_REPO_URL
git push -u origin main

Replace YOUR_GITHUB_REPO_URL with the actual repository URL from GitHub.

Create a Vercel Account

Go to the Vercel website and create an account. The easiest option for most beginners is to sign in with GitHub.

Sign in with GitHub

This allows Vercel to see your repositories and import the one you want to deploy.

Import Your Project

Inside the Vercel dashboard, follow this path:

Add New...
      ↓
Project
      ↓
Import your GitHub repository

Vercel will inspect your project and try to detect the framework. Review the settings before deploying.

Deploy Your Project

After the project is imported and the settings look correct, click:

Deploy

Vercel will then:

• Install your dependencies.
• Run your build command.
• Create a deployment.
• Give you a live website URL.

The first live URL usually looks something like this:

your-project-name.vercel.app

Update Your Website

After your project is connected to Vercel, updating the live site is usually as simple as pushing new code.

git add .
git commit -m "Update homepage"
git push

Vercel will automatically notice the Git push and create a new deployment.

Production Deployments and Preview Deployments

Vercel commonly creates two important kinds of deployments.

Preview deployments are useful because they let you test changes before making them live.

main branch       → production website
feature branch    → preview website

Environment Variables

Environment variables are values stored outside your source code. They are often used for API keys, database URLs, and secret configuration values.

Example:

API_KEY=abc123

In Vercel, environment variables are added here:

Project
  ↓
Settings
  ↓
Environment Variables

Important rule: do not hard-code secret API keys directly into your frontend code.

Some frontend tools require public environment variables to use a specific prefix.

Custom Domains

Vercel gives your project a free .vercel.app URL, but you can also connect your own domain.

Project
  ↓
Settings
  ↓
Domains
  ↓
Add Domain

After you add the domain, Vercel will show DNS instructions. You will usually need to update DNS records wherever your domain was purchased.

Deploying a Plain HTML Site

For a simple project like this:

my-site/
  index.html
  about.html
  styles/
    main.css
  scripts/
    app.js

Use these Vercel settings:

Framework Preset: Other
Build Command: leave blank
Output Directory: .

This is the simplest possible deployment style.

Deploying a Vite Project

Create or open your Vite project:

npm create vite@latest my-app
cd my-app
npm install
npm run dev

Test the production build:

npm run build

Common Vercel settings:

Framework Preset: Vite
Build Command: npm run build
Output Directory: dist

Deploying an Astro Project

Create or open your Astro project:

npm create astro@latest
npm install
npm run dev
npm run build

Common Vercel settings:

Framework Preset: Astro
Build Command: npm run build
Output Directory: dist

Astro is a strong option for documentation sites, worldbuilding sites, tutorial sites, and content-heavy projects.

Optional: Basic vercel.json File

Most beginner projects do not need a vercel.json file. However, it can be useful when you want to customize behavior.

Example:

{
  "cleanUrls": true
}

This can make URLs cleaner by removing .html from displayed routes.

Common Problems and Fixes

Build Failed

Check these questions:

• Does npm run build work locally?
• Are all dependencies listed in package.json?
• Are any files missing from the repository?
• Are required environment variables missing?

Page Not Found

Common causes include:

• The output directory is wrong.
• The project is missing an index.html file.
• A single-page app has a routing configuration issue.
• The wrong framework preset was selected.

Environment Variable Is Undefined

Check:

• Did you add it in Vercel Project Settings?
• Did you redeploy after adding it?
• Did you use the correct public prefix for your framework?
• Are you trying to expose a server-only secret in browser code?

Images or Assets Are Broken

Make sure your image paths point to files inside the project, not your local computer.

Good:

<img src="/images/logo.png" alt="Logo">

Bad:

<img src="C:\Users\Ray\Desktop\logo.png" alt="Logo">

Best Practices

• Test your project locally before deploying.
• Run npm run build before pushing major changes.
• Keep secret values in environment variables.
• Use preview deployments for large changes.
• Keep project folders organized.
• Write clear Git commit messages.

Example project structure for a simple static site:

project/
  index.html
  styles/
    main.css
  scripts/
    app.js
  images/
    logo.png

Simple Mental Model

Vercel is like a restaurant kitchen for your website.

Your code       = ingredients
GitHub          = pantry/storage
Vercel build    = kitchen preparation
Deployment      = finished meal served to visitors
Custom domain   = restaurant sign out front

You do not usually upload files manually. You push your code to GitHub, and Vercel handles the publishing process.

Beginner Checklist

• The project runs locally.
• The project builds locally.
• The code is pushed to GitHub.
• The repository is imported into Vercel.
• The framework preset is correct.
• The build command is correct.
• The output directory is correct.
• Environment variables are added if needed.
• The deployment succeeds.
• The live URL works.

Quick Practice Project

Create a folder called vercel_practice_site with this structure:

vercel_practice_site/
  index.html
  styles/
    main.css

Use this basic index.html file:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My First Vercel Site</title>
  <link rel="stylesheet" href="/styles/main.css">
</head>
<body>
  <h1>Hello, Vercel!</h1>
  <p>This site is deployed online.</p>
</body>
</html>

Deploy settings:

Framework Preset: Other
Build Command: leave blank
Output Directory: .

After deployment, open the live URL and confirm that your page appears.