Vercel tutorial: deploy a web app from Git or the CLI

Sep 16, 2026

Learn how to deploy a web app to Vercel, use preview and production deployments, add environment variables, Functions, domains, logs, and rollbacks.

~~~

Vercel turns a Git repository into a live web application.

Connect a repository, and Vercel builds the project on every push. You get a production site, a preview for each branch, HTTPS, a CDN, and server-side Functions without managing a server.

Vercel works with Next.js, Astro, SvelteKit, Nuxt, Vite, and many other frameworks. It can also deploy a plain HTML site.

In this tutorial we’ll deploy an Astro site. The Vercel parts are almost identical with another framework.

Projects and deployments

Before we deploy anything, I want to clarify two words.

A project is the permanent home of an application in Vercel. It holds the Git connection, domains, environment variables, and settings.

A deployment is one built version of that project. Every push creates a new deployment with its own URL.

The project stays. Deployments accumulate inside it.

Vercel has three default environments:

Local is the app on your computer
Preview is a deployment you can test before release
Production is the version your users see

This separation is one of the best parts of Vercel. You can test a real deployment without touching production.

Create an Astro project

If you already have an application, skip this section.

Create a small Astro site:

npm create astro@latest vercel-demo

Choose the minimal template and install the dependencies.

Then open the new directory:

cd vercel-demo
npm run dev

Astro prints the local URL. Open it in the browser and make sure the site works.

Always run the production build before the first deployment:

npm run build

This catches missing files and build-only errors on your computer.

Deploy from Git

The usual Vercel workflow starts with GitHub, GitLab, or Bitbucket.

Push the project to a Git repository. Then:

Sign in to Vercel
Click New Project
Import the repository
Check the detected framework and build settings
Click Deploy

Vercel detects Astro and builds the site without extra configuration.

When the build finishes, you get a URL ending in .vercel.app. This is already a production deployment.

Now change some text and push it to a new Git branch. Vercel creates a preview deployment with a different URL.

Push or merge the change into the production branch, usually main, and Vercel creates a new production deployment.

The flow looks like this:

feature branch push -> preview deployment
production branch push -> production deployment

Each deployment is immutable. A new push creates a new one instead of editing the old deployment.

This makes previews and rollbacks possible.

Deploy with the Vercel CLI

You can also deploy any local directory from the terminal.

Install the Vercel CLI:

npm install -g vercel

vercel login

The current login flow opens a device authorization page in your browser.

Now run this from the project directory:

vercel

The first run asks which account to use and whether you want to link an existing project. Choose to create a project if this is the first deployment.

The vercel command creates a preview deployment.

When you are ready to publish it to production, run:

vercel --prod

My advice is to connect Git for normal work. Use the CLI for experiments, automation, and deployments from repositories Vercel cannot connect to directly.

Understand the build settings

Vercel normally detects these values from your framework:

the install command
the development command
the build command
the output directory

For an Astro site, the build command is npm run build and the output directory is dist.

You can change these values under Project Settings → Build and Deployment.

Do this only when your project needs it. The detected defaults are usually correct.

If your app lives inside a monorepo, set its Root Directory. For example, an app inside apps/site must build from that directory instead of the repository root.

Add environment variables

API keys and database credentials must not live in Git.

Open Project Settings → Environment Variables and add a value such as:

NEWSLETTER_API_KEY=your-secret-key

Choose where the variable is available:

Development
Preview
Production

Preview and production often need different values. A test database should not point at production by accident.

An environment variable change only affects new deployments. Redeploy the app after changing one.

You can also manage variables with the CLI:

vercel env add NEWSLETTER_API_KEY production

Pull the Development variables into a local file:

vercel env pull .env.local

Add .env.local to .gitignore.

Remember that variables exposed to browser code are public. Frameworks use prefixes such as PUBLIC_ or NEXT_PUBLIC_ for those values.

Never expose a secret with one of those prefixes.

Add a Vercel Function

A static site cannot safely call a private API with a secret key. That code must run on the server.

Vercel can turn files inside the root api directory into Vercel Functions.

Create api/hello.ts:

export default {
  async fetch(request: Request) {
    const url = new URL(request.url)
    const name = url.searchParams.get('name') || 'World'

    return Response.json({ message: `Hello ${name}!` })
  },
}

Deploy the project, then open:

https://your-project.vercel.app/api/hello?name=Flavio

The response is:

{
  "message": "Hello Flavio!"
}

The function only runs when a request reaches it. Vercel handles the server, scaling, and HTTPS.

Frameworks such as Next.js have their own route conventions. Use the framework-native approach when one exists.

To test Vercel-specific Functions and routing locally, run:

vercel dev

If your framework’s normal development command already supports everything you use, keep using that command.

Add a custom domain

Every project gets a .vercel.app address. You can attach your own domain from Project Settings → Domains.

Enter the domain, and Vercel shows the exact DNS records to add.

If Vercel manages your DNS, it can create the records for you. If Cloudflare or another provider manages it, copy the records into that provider’s dashboard.

You can also inspect the required records with the CLI:

vercel domains add myapp.com my-project
vercel domains inspect myapp.com

Run inspect again after changing DNS. Vercel automatically provisions the TLS certificate after verification.

If you use both myapp.com and www.myapp.com, redirect one to the other. This gives the site one canonical address.

Read build and runtime logs

There are two logs you’ll use most often.

Build logs show dependency installation and the build command. Open them when a deployment fails.

Runtime logs show Vercel Function requests and console.log() output. Open them when the build succeeded but an API route fails.

You can inspect a deployment from the terminal:

vercel inspect https://your-deployment.vercel.app

Add --logs to print its build logs:

vercel inspect https://your-deployment.vercel.app --logs

For production runtime errors, use:

vercel logs --environment production --status-code 5xx --since 30m

Start with the first real error. Later failures are often just consequences of it.

Roll back a broken deployment

Because old deployments still exist, Vercel can point production back to one of them without rebuilding.

To return to the previous production deployment:

vercel rollback

Check its status:

vercel rollback status

On the Hobby plan, you can roll back to the previous production deployment. Pro and Enterprise projects can select older eligible deployments.

After a rollback, fix the bug and deploy again. Do not treat the rollback as the fix.

Notice that a rollback restores old built code. It does not roll back your database or an external API.

Do you need a `vercel.json` file?

Usually, no.

Framework detection covers the normal build and routing setup. Add vercel.json only when you need platform-specific configuration such as redirects, headers, rewrites, or Function settings.

For example, this redirects an old path:

{
  "redirects": [
    {
      "source": "/old-page",
      "destination": "/new-page",
      "permanent": true
    }
  ]
}

Keep platform configuration small. Prefer your framework’s configuration when it provides the same feature.

A practical deployment checklist

Before sending a Vercel project to real users, check these items:

Run the production build locally
Confirm Preview and Production use the right environment variables
Test server-side routes on a preview deployment
Add a custom domain and verify its redirect
Check build and runtime logs
Know how to run vercel rollback
Review the current limits and pricing for your plan

That is the core Vercel workflow.

Connect Git for automatic deployments. Use previews to test changes. Promote only working code to production, and keep the previous deployment ready if something goes wrong.

Tagged: Services · All topics

Follow @flaviocopes

Want me to talk about your product? You can sponsor this site.

~~~