Claude Code → GitHub → Vercel — the full first-deploy walkthrough

Set up the working folder

1. 1.Create the project folder

   Open Terminal (macOS) or your WSL Ubuntu terminal (Windows). Create a folder for your site and cd into it.

   mkdir -p ~/Sites/my-site
   cd ~/Sites/my-site

   Naming the folder

   Use the same name as your eventual GitHub repo. Lowercase, hyphen-separated, no spaces. 'my-personal-site' is fine; 'My Personal Site' will give you escaping headaches later.

2. 2.Drop in your CLAUDE.md and brand-brief.md

   Open your text editor (TextEdit, Notepad, or VS Code if you have it) and create two files in the project folder: CLAUDE.md (use the starter template) and brand-brief.md (use the personal or business template).

   If you don't have these yet, see /templates/claude-md-starter and /templates/personal-brand-brief (or business-brand-brief).

Open Claude Code and scaffold

1. 3.Launch Claude Code in the project folder

   From inside the project folder, run:

   claude

   First-time start

   Claude opens a browser tab for authentication on first run. Approve. Subsequent runs skip this.

2. 4.Paste the scaffold prompt

   Once Claude Code is ready (you'll see the prompt indicator), paste this:

   Scaffold a Next.js 16 + TypeScript + Tailwind 4 site for my personal/business website.
   
   Read CLAUDE.md and brand-brief.md (both are in this folder) before doing anything else. Match the voice and stack described there.
   
   Pages I need: home, about, services, contact, blog (with 3 sample MDX or markdown posts).
   
   Single accent colour. One heading font, one body font. Mobile-first responsive. SEO meta tags on every page using Next.js Metadata API.
   
   Don't add: framer-motion, any UI library beyond Tailwind utilities, animation libraries, state management libraries, testing libraries, or alternative hosts.
   
   Use git init and create the first commit. Don't push yet — I'll do GitHub in the next step.

   Resist the urge to ask for everything

   The temptation is to add 'and an admin dashboard and a contact form that posts to Slack and dark mode toggle.' Don't. Get the basic scaffold deploying first. You can add anything later — and it'll be easier when there's a working baseline.

3. 5.Watch Claude work

   Claude Code will write files. Each file write shows you a diff before applying. Approve each one — or, for trust-building, watch the first 3-4 closely and then auto-approve the rest.

   Total time: ~3-5 minutes for the scaffold. Claude reads CLAUDE.md, brand-brief.md, then writes app/layout.tsx, app/page.tsx, app/about/page.tsx, etc.

   Claude Code's diff view shows red (deletions) and green (additions) lines with the file path at the top. There's a [y/n/a] prompt for approve, reject, or approve-all.

4. 6.Run npm install and npm run dev

   Claude Code typically runs these for you, but if not, do it manually:

   • •npm install pulls all dependencies (~30 seconds).
   • •npm run dev starts the local dev server on http://localhost:3000.
   • •Open that URL in your browser. You should see your scaffolded site.

   npm install
   npm run dev

   First sight

   The first time you see your scaffold load on localhost is a quietly satisfying moment. The site has your real brand colour, your real headings, and pages that match your brief. Take 30 seconds.

Push to GitHub

1. 7.Create the GitHub repo

   With Claude Code still open in another tab, run this in a second terminal:

   • •--private starts the repo private. You can flip to public later with gh repo edit my-site --visibility public.
   • •--source=. uses the current folder as the source.
   • •--remote=origin sets up the standard remote name.
   • •--push pushes the initial commit immediately.

   gh repo create my-site --private --source=. --remote=origin --push

   If you get a permission error

   Run gh auth status first. If it shows you're authenticated but the push fails, your repo name might collide with an existing one. Pick a different name. Or your gh might be authenticated to a different account than the one you want to push to — gh auth switch fixes that.

2. 8.Confirm the repo is up

   Visit https://github.com/YOUR-USERNAME/my-site. You should see your code with the initial commit message.

Deploy to Vercel

1. 9.Import the repo into Vercel

   Go to https://vercel.com/new. You'll see a list of your GitHub repositories (because you connected GitHub at setup).

   Find my-site and click Import.

   Vercel auto-detects Next.js and pre-fills the build configuration. You shouldn't need to change anything.

   The Vercel 'New Project' screen shows your GitHub repos in a list, each with an Import button. After clicking Import, the configuration screen has Framework Preset (Next.js, auto-detected), Build Command (next build, default), and Output Directory (.next, default) already filled.

2. 10.Click Deploy and wait

   Click the Deploy button at the bottom. Vercel builds your site (~60-90 seconds) and gives you a *.vercel.app URL.

   Open the URL on your phone. Take a screenshot. That's your site, live on the internet.

   Celebrate this

   Even if the site is ugly and unfinished, getting to a live URL is the unblocker. The rest of CW-2 is iteration; this was the leap.

The iterate-then-push loop

From here, every change you make follows the same loop. This is the rhythm of the rest of CW-2.

1. 1.Ask Claude Code for a change

   Go back to Claude Code. Describe the change in plain English: 'The home page hero is too generic. Rewrite the headline three times in different angles from brand-brief.md — I'll pick.'

   Claude proposes; you pick. Claude applies; you review the diff.

2. 2.Commit and push

   Once you're happy with a change, ask Claude Code to commit and push, or do it manually:

   git add -A
   git commit -m "Better hero headline"
   git push

3. 3.Vercel auto-deploys

   Within ~60 seconds of your push, Vercel rebuilds and your live URL updates. No deploy command, no manual trigger. Watch your *.vercel.app URL — it'll reflect the new hero copy.