Deploy Your First App Free With Vercel + Claude Code

Claude Code can build your app. Most guides stop there. This one covers what happens next — getting that local project onto a real URL, free, without touching a single config file yourself.

The workflow is shorter than you think: Claude Code handles the Git setup, installs the Vercel CLI, authenticates your account, and runs the deploy. You supply the prompts. Vercel supplies the URL.

What You'll Need Before You Start

A working project folder

You need something to deploy. If you already have a project Claude Code built for you, open that folder. If you're starting from scratch, give Claude Code this prompt first:

Create a simple single-page web app in this folder. Use plain HTML, CSS, and JavaScript. Make it a portfolio page with my name, a short bio section, and three placeholder project cards.

That gives you a deployable project in under a minute. The same workflow below applies to Next.js apps, React projects, or anything else Claude Code builds.

A free Vercel account

Go to vercel.com and sign up. Signing up with GitHub is recommended — Vercel's production deployment workflow is built around Git pushes, so connecting GitHub now saves a manual step later. Email signup is also available but won't connect a Git provider by default.

The Hobby plan is free, requires no credit card, and covers everything in this guide.

Claude Code installed and running

You need Claude Code open in your project folder before you start. If you haven't installed it yet, see the setup guide for Windows or Mac.

Step 1 — Initialize a Git Repo (Claude Code Does This for You)

Why Vercel wants a Git repo

Vercel's production deploys are tied to a Git repository. Every time you push to your main branch, Vercel rebuilds and republishes your site automatically. This is the right default — it means deployments are tracked, reversible, and automatic.

You can technically deploy a local folder without GitHub using vercel deploy --prod, but connecting a repo is the better path for anything you'll update later.

The exact prompt to give Claude Code

Initialize a Git repository in this folder, create an initial commit with all existing files, and push it to a new GitHub repository. Name the repo [your-project-name].

Claude Code will run git init, stage everything, make the first commit, create the GitHub repo via the GitHub CLI (if you have it), and push. If it hits a snag, it'll tell you exactly what's missing.

What to do if you don't have GitHub set up yet

If you've never used Git or GitHub, Claude Code will tell you it needs credentials. The fastest fix: create a GitHub account at github.com, then tell Claude Code:

Help me configure Git with my GitHub credentials so I can push this repo.

It will walk you through git config, SSH key setup, or GitHub CLI auth depending on what's already installed on your machine.

Step 2 — Install the Vercel CLI via Claude Code

Why the CLI beats the Vercel dashboard for beginners

The Vercel dashboard is fine for browsing deployments after the fact. But for your first deploy, the CLI is faster and Claude Code can drive it directly from the terminal — no copying and pasting settings into a browser UI, no guessing which dropdowns to click.

The one-line prompt

Install the Vercel CLI globally and log me into my Vercel account.

Claude Code will run:

npm i -g vercel
vercel login

It'll then tell you to check your browser — Vercel opens a confirmation page using OAuth device flow for you to approve. Click approve, come back to the terminal, and you're logged in.

What the login flow looks like

After vercel login, Vercel opens your default browser and shows an OAuth confirmation screen. Approve it, return to the terminal, and you'll see a confirmation that your account is linked. No passwords, no API keys to copy manually.

Step 3 — Deploy With One Claude Code Prompt

The prompt

Deploy this project to Vercel on the free tier. Use the Hobby plan settings and set the production branch to main.

Claude Code will run the deploy command and answer Vercel CLI's setup questions for you — project name, which directory to deploy, what build command to use, and what the output directory is.

What Claude Code configures automatically

For a plain HTML/CSS/JS project, there's no build step — Vercel detects this and serves files directly. For a Next.js or React app, Vercel auto-detects the framework and sets the correct build command (npm run build) and output directory (/.next or /dist). Claude Code will confirm these settings in its output before committing.

If you used Claude Code to scaffold the project, it knows the structure already. It won't guess at a build command — it'll read the package.json it created and pull the right value.

Reading the output — what a successful deploy looks like

A successful deploy ends with something like:

✅  Production: https://your-project-name.vercel.app [2s]

That URL is live immediately. Share it with anyone.

Step 4 — Your Live URL and What to Do With It

Preview URLs vs production URLs

Every deploy to your main branch creates a production URL: your-project-name.vercel.app. Every other branch or manual deploy creates a preview URL — a unique, temporary link like your-project-name-abc123.vercel.app. Preview URLs are useful for showing someone a work-in-progress without touching your live site.

For now, your production URL is the one to share.

How to set a custom domain

Vercel lets you connect a custom domain for free on the Hobby plan. In the Vercel dashboard, go to your project → Settings → Domains, and add your domain. Vercel gives you DNS records to add at your registrar. The process takes about five minutes and Claude Code can't automate the DNS part — that lives in your domain registrar's control panel, not your terminal.

Sharing your URL

Anyone with the URL can visit your app. No login required, no preview mode — it's a real public URL. For a portfolio or demo project, this is exactly what you want.

What Vercel's Free Tier Actually Covers

Hobby plan limits

The Hobby plan includes 100 GB of bandwidth per month, which is more than enough for a personal project or portfolio getting hundreds of daily visitors.

Serverless functions (if your app uses them for things like API routes) are included — 1 million invocations per month on the free tier.

Build minutes are capped at 6,000 per month — for a project that deploys once or twice a week, you'll stay well within that limit. Static HTML projects don't consume build minutes at all.

The Hobby plan does not support commercial use under Vercel's terms of service. For a personal project, demo, or learning exercise, you're fine. For something you're charging users for, you'd move to the Pro plan.

What will actually push you to a paid plan

For a beginner project: almost nothing. You'd need sustained high traffic, multiple team members needing dashboard access, or advanced features like password protection on preview URLs to need a paid plan. Don't worry about it for your first deploy.

For a deeper comparison of what Vercel covers versus Netlify's free tier, see Netlify vs Vercel: Free Hosting Compared.

When Things Go Wrong

Build command errors

If the deploy fails with a build error, Claude Code's output will include the exact error message from Vercel's build log. Copy it back to Claude Code:

The deploy failed with this error: [paste the error]. Fix it and redeploy.

Claude Code will diagnose the issue — a missing dependency, a wrong build command, a TypeScript error — fix it, and run the deploy again.

Blank page after deploy

The most common cause: the output directory is wrong. If you built a React app and the output goes to /build but Vercel is looking in /dist, it'll deploy an empty folder. Tell Claude Code:

My Vercel deploy succeeded but the site shows a blank page. Check the build output directory and redeploy with the correct setting.

It will inspect your package.json, confirm the output folder, update the Vercel project settings, and redeploy.

"Command not found" — PATH issues with the Vercel CLI

If you open a new terminal window after installing the CLI and get vercel: command not found, npm's global binary path isn't in your shell's PATH. Tell Claude Code:

I installed the Vercel CLI but my terminal says "command not found". Help me fix my PATH so the vercel command works.

This is a one-time fix — once your PATH includes npm's global bin directory, all future CLI tools install cleanly.

Next Steps After Your First Deploy

Pushing updates automatically

Once your project is connected to GitHub, every git push to your main branch triggers a new Vercel deploy. You don't need to run any commands manually. The workflow becomes: make changes → tell Claude Code to commit and push → Vercel redeploys within seconds.

Commit all my changes and push to main.

That's the entire update workflow.

Connecting a real domain

When you're ready to move from your-project.vercel.app to yourproject.com, buy a domain from any registrar (Namecheap, Cloudflare Registrar, Google Domains) and follow Vercel's domain setup in the dashboard. Claude Code can't automate the DNS records step, but it can walk you through what records to add if you paste the Vercel instructions back to it.

Adding environment variables for API keys

If your app uses an API key (for OpenAI, a weather API, etc.), don't put it in your code. Add it in Vercel's dashboard under Project → Settings → Environment Variables. Then tell Claude Code to update your code to read it from process.env.YOUR_KEY_NAME instead of a hardcoded string.

My app uses an API key that's currently hardcoded. Refactor it to read from an environment variable called NEXT_PUBLIC_API_KEY, and tell me how to add it in Vercel.

This keeps your keys out of GitHub and out of your public URL.

---

For more on what Claude Code can build before you deploy it, see the build your first app with PokéAPI guide — it's a natural "now deploy what you built" follow-up. And if you're still deciding which AI coding tools belong in your stack, the best free AI coding tools in 2026 has a complete breakdown.

Vercel is the right default for anything Claude Code builds. Free, fast, and zero config for the frameworks Claude Code reaches for first.