Builder Toolkit · 06 / 11

Vercel Basics

Connect a repository, understand builds, tell preview from production, and read a failed build log.

Vercel Basics

What this is

Vercel takes the code in your GitHub repository, builds it, and serves the result at a public URL.

The one idea

Vercel deploys what is on GitHub, not what is on your laptop. If you did not push it, it does not exist to Vercel.

Why it matters

Local work is invisible. A live URL is the first thing you can put in front of a person, and it is what proof and portfolios are made of.

It is also where a whole class of new errors appears. Code that runs locally can still fail to build, and understanding why is the difference between shipping and being stuck.

What to do

Understand the flow

Terminal command

git push → Vercel detects the change → build runs → live URL updates

Swipe sideways if a command is long.

Every push to your main branch triggers a new deployment. You do not click anything after the first setup.

Connect the project

Go to vercel.com and sign in with GitHub.
Choose Add New, then Project.
Import the correct repository. Check the name carefully.
Leave the detected framework settings alone.
Add environment variables only if your project needs them.
Deploy, wait for the build to finish, and open the URL.

Tell preview from production

Type	Where it comes from	What it is for
Production	Your `main` branch	The real site. This is the URL you share.
Preview	Any other branch or pull request	Testing a change before it goes live.

Early on you will only have production. Share that URL. Preview URLs change and expire, so they are a poor thing to put on a CV.

Do this now

Open your live URL on your phone, not just your laptop. Deployment problems and layout problems often only appear on a real device.

Check yourself

My live URL opens and shows my project.
I know which branch produces the production URL.
I have pushed a change and watched a new deployment appear.
I know where the build logs are in the Vercel dashboard.

Read a failed build properly

When a build fails, work down this list in order. It resolves most failures without guessing:

Does npm run build succeed on your own machine?
Did you actually push your latest commit?
Is Vercel connected to the right repository?
Does the log mention a missing environment variable?
Does the project depend on a file that .gitignore excludes?

Then open the build log and read the first red error. Everything below it is usually a consequence of that one line.

If you need AI help, give it real information:

Copy

My Vercel deployment failed.

Does it build locally: [yes / no]
The first red error in the log:
[paste the error]

Explain what this means and give me only the next step to try.

If the build passes but the page is broken

That is not a build problem. Go to Deployment troubleshooting.

Common mistakes

Deploying a project that does not build locally, then blaming the host.
Forgetting to push, then wondering why the live site is missing your latest work.
Importing the wrong repository and debugging someone else's project.
Reading the last line of a build log instead of the first red one.
Sharing a preview URL as if it were permanent.
Adding environment variables and expecting the existing deployment to pick them up, which the next page explains.

Next step

Your project is live. Now learn why it might work locally and break online: Environment Variables.