Build a Web App with Claude Code

What you'll build

A real web app — a page you can open in any browser — built with Next.js, without writing the code by hand. You'll describe what you want in plain English and let Claude Code do the typing. This part takes you from nothing to the app running on your own machine. Putting it online comes next, in Part 3.

The tools you'll meet

Before you start

• A Claude account at claude.ai (Pro or Max includes Claude Code).
• A GitHub account at github.com — for later.

Install Node.js

Install the LTS build from nodejs.org, then check it in your terminal (Mac: ⌘+Space → "Terminal"; Windows: PowerShell):

node --version   # should print v22.x.x or similar

Install Claude Code

npm install -g @anthropic-ai/claude-code

mkdir my-first-app && cd my-first-app
claude            # follow the login link the first time

Ask Claude Code to build your app

Describe the purpose and the vibe; let it make the technical choices:

> Create a new Next.js app in this folder using TypeScript and the
  App Router. Build a one-page personal site with a hero, an "about"
  section, a list of projects as cards, and a contact footer. Clean
  dark theme, blue accent. Then start the dev server so I can see it.

It creates the files, installs what it needs, and asks before running commands — say yes.

What Claude Code actually runs

Behind that one request, it runs the same commands a developer would type by hand — and asks before each:

npx create-next-app@latest . --typescript --app   # scaffold the Next.js project here
npm install                                        # download the libraries it needs
npm run dev                                         # start the dev server
# ➜ Local:  http://localhost:3000

You don't have to remember any of these — Claude Code picks and runs them. Seeing them helps you follow along, and recognize them when it asks for permission.

Run it locally — and stop here

npm run dev
# ➜ Local:  http://localhost:3000

Open http://localhost:3000. Leave it running — the page refreshes on every edit. Keep asking for changes until you like it. This is the finish line for Part 1: a working app on your machine. You don't need to deploy anything yet.

What all these files are: the Next.js layout

my-first-app/
├─ app/                # your pages live here
│  ├─ layout.tsx       # shared shell around every page
│  ├─ page.tsx         # the homepage  →  "/"
│  ├─ globals.css      # site-wide styles
│  └─ about/
│     └─ page.tsx      # the about page  →  "/about"
├─ public/             # images & static files, served as-is
├─ package.json        # dependencies + dev/build scripts
└─ node_modules/       # installed libraries (never edit)

• Folders in app/ become URLs. A folder with a page.tsx is a page.
• layout.tsx is the frame — nav, footer, fonts on every page.
• public/ is for assets — drop logo.png there, use it at /logo.png.

npm, yarn, pnpm — what are these?

You keep typing npm. It's a package manager — it downloads the open-source libraries your app depends on (into node_modules/) and runs your project's scripts. There are three common ones; they do the same job, just faster or tidier:

What's in package.json?

package.json is your project's ID card — the one file that says what your app is called, what it depends on, and what commands it can run. Every package manager reads it:

// package.json
{
  "name": "my-first-app",
  "scripts": {                 // the commands you can run
    "dev": "next dev",          // npm run dev  → start locally
    "build": "next build",      // npm run build → production build
    "start": "next start",
    "lint": "eslint"
  },
  "dependencies": {            // libraries your app needs to run
    "next": "^15.0.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  },
  "devDependencies": {         // tools needed only while developing
    "typescript": "^5",
    "eslint": "^9"
  }
}

• scripts — shortcuts you run with npm run <name> (that's where npm run dev comes from).
• dependencies — packages shipped with your app; devDependencies — tools only used while building (linters, types).
• The ^ means "compatible newer versions are OK"; the lock file records the exact versions actually installed.

Make it look designed, not default

Claude Code has Skills for design — ask for them by name so your app doesn't look templated:

> Use your frontend-design skill to give this a stronger visual
  identity — deliberate type, generous spacing, one accent color.
  Avoid a generic "AI landing page" look.

Start from a template — especially for dashboards

You don't have to build the layout from scratch. A template is a ready-made skin — the sidebar, top bar, cards, tables, and charts already arranged — so you just drop in your content and data. Dashboards are mostly the same furniture every time, which is exactly where a template saves the most work.

And yes — there are gallery pages you browse exactly like PrimeVue's templates showcase: preview a design, then clone it and start editing. The best for a Next.js + React app:

Tell Claude Code to build on one instead of starting from a blank page:

> Set up shadcn/ui and use its dashboard block as the skin: a left
  sidebar, a top bar, and a main area with four stat cards, a line
  chart (use Tremor), and a recent-activity table. Fill it with
  placeholder data for now — I'll wire real data in Part 4.

How to prompt for web development

Good prompts answer four things — goal, context, style, constraints:

> Build a homepage for a coffee roaster called "Ember". Sections:
  hero with tagline, short "our story", three product cards with
  price, footer with address + Instagram. Warm palette (browns,
  cream), rounded corners. Must look great on a phone.

• Show, don't just tell: "make it feel like stripe.com — clean, lots of air."
• Describe problems, not CSS: "the text is too close to the edge on mobile."
• One change at a time, and ask for options when exploring.

Give the project a CLAUDE.md

Drop a CLAUDE.md at the repo root so Claude Code knows your conventions every session (/init scaffolds one for you):

# CLAUDE.md

## What this is
Personal / marketing site. Next.js (App Router) + TypeScript. No backend yet.

## Commands
- Dev / Build / Lint: npm run dev / build / lint   (dev on :3000)

## Structure
- app/            routes (folder + page.tsx = a URL)
- app/layout.tsx  shared shell (nav, fonts)
- public/         static assets, served at /
- components/     reusable UI

## Conventions
- Dark theme, blue accent. Reuse tokens in app/globals.css — don't hardcode colors.
- One component per file; keep them small.

## Verify
Run the dev server; check the changed page on desktop + mobile.

Tips for working with Claude Code

• Work in small steps — one change, look, next.
• Commit often — ask Claude Code to save progress to git; it's your undo.
• Give it the error — paste error messages; fixing them is what it's best at.
• Ask it to explain — "what does this file do?" is how you learn while building.