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 2.

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. Notice how much of the thinking happens in the prompt — every line below closes off a decision you'd otherwise have to undo later:

> Goal: turn this into a dashboard.

  Shell: a left sidebar for navigation, a top bar with the page
  title, and a main content area — plain Tailwind, no second UI
  library.

  Data parts with Tremor: four stat cards across the top, a line
  chart of events over time, and a recent-activity table below it.

  Style: take every color, spacing value and radius from the @theme
  block in app/globals.css. Don't invent new ones.

  Data: seed realistic event-log rows — timestamp, source, level,
  message — so the chart and table have something to show. I'll
  wire the real API in Part 5.

  Constraints: put the shell in one <DashboardLayout> component so
  every page can reuse it, and make it work down to phone width.

  Build the dashboard page only. Show me it before going further.

Once you like it, roll it out — and keep the agent on a short leash while it touches pages that already work:

> Now move the existing pages onto it: wrap each one in
  <DashboardLayout>, swap any hand-rolled cards for Tremor's Card,
  and delete the CSS that's now unused. One page at a time — show
  me each before you start the next.

Every one of those galleries is built on the same two things, and they do completely different jobs. A few minutes here saves a lot of confusion later — especially because you are already using one of them.

Tailwind CSS — how the styling gets written

The traditional way to style a page is two files: you invent a class name in your HTML, then write the rules for it in a stylesheet. Tailwind deletes the invention step. It gives you hundreds of tiny single-purpose classes — flex, p-6, rounded-xl — and you compose the design directly on the element:

// The traditional way — two files, and a name you had to think up
<div class="price-card"> … </div>

// styles.css
.price-card {
  display: flex;
  gap: 0.75rem;
  padding: 1.5rem;
  border-radius: 0.75rem;
  background: #1a2236;
}

// Tailwind — the same card, one file, nothing to name
<div class="flex gap-3 p-6 rounded-xl bg-slate-800"> … </div>

It looks noisy the first time you see it, and that reaction is normal. What you get back is worth the noise: the styling is where the element is. To change how something looks you edit that line — you never go hunting through a stylesheet wondering which rule is winning, and deleting a component deletes its CSS with it.

Tremor — the dashboard parts Tailwind doesn't give you

Tailwind styles things. It does not give you things — there is no chart class, because a chart is not a style, it's a component. Tremor is a set of React components built for dashboards: KPI cards, charts, and data tables. Because it's built on Tailwind, it inherits the same spacing and color scale as the rest of your app instead of looking bolted on.

import { Card, LineChart } from '@tremor/react';

<Card>
  <LineChart data={revenue} index="month" categories={['eur']} />
</Card>
// ~4 lines for a chart that is responsive, themed, and has tooltips

How the pieces stack

Every gallery above sits somewhere on this ladder:

  your app        app/page.tsx — your content and your data
  ───────────────────────────────────────────────────────────
  components      shadcn/ui  → buttons, dialogs, tables, forms
  (pick one)      Tremor     → KPI cards, charts, dashboard tables
  ───────────────────────────────────────────────────────────
  Tailwind CSS    the utility classes both are built out of

A good way to learn Tailwind is to make the agent teach you from your own code:

> Explain the Tailwind classes on this component line by line in
  plain English. Then pull the repeated ones into a reusable
  <StatCard> component so I'm not copying the same 12 classes.

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.

…and a DESIGN.md for the look

CLAUDE.md tells the agent how you build. DESIGN.md tells it how you look — a single file at the repo root holding your colors, type scale, spacing and component rules, in a format agents read natively. It solves the problem you hit around page four: the new page is fine on its own, but it doesn't match the three you already have.

It's an open format from Google Labs — text, Git-versionable, readable by Claude Code, Cursor or Copilot alike. And you don't have to write one from scratch: getdesign.md is a catalog of a few hundred DESIGN.md files reverse-engineered from real products, so you can start from a visual language that already works.

Steps to implement it

1. Pick a starting point. Browse the catalog at getdesign.md/design-md and grab the analysis whose feel is closest to what you're after — or skip the catalog and have Claude Code write one from your existing pages (step 3).
2. Save it as DESIGN.md at the repo root, next to CLAUDE.md. YAML front matter carries the tokens an agent can act on; the prose below explains the intent:

   ---
   name: Ember
   colors:
     primary: "#1A1C1E"
     tertiary: "#B8422E"
     neutral: "#F7F5F2"
   typography:
     h1: { fontFamily: Public Sans, fontSize: 3rem }
     body-md: { fontFamily: Public Sans, fontSize: 1rem }
   rounded: { sm: 4px }
   spacing: { sm: 8px }
   ---
   
   ## Overview        ← the sections the spec expects, in this order
   ## Colors
   ## Typography
   ## Layout
   ## Elevation & Depth
   ## Shapes
   ## Components
   ## Do's and Don'ts

3. Point Claude Code at it — once, in plain English:

   > Read DESIGN.md and restyle the homepage to match it exactly —
     its colors, type scale, spacing and radii. Don't invent values
     that aren't in the file. Then add a line to CLAUDE.md telling
     future sessions to follow DESIGN.md for anything visual.

   That last sentence is the important one: it makes the design brief stick across sessions instead of being a one-off instruction.
4. Check it's valid. The official linter catches broken token references and flags contrast that fails accessibility checks:

   $ npx @google/design.md lint DESIGN.md

5. Turn the tokens into Tailwind. This is where it meets the section above — export your tokens and paste them into the @theme block in app/globals.css, and your DESIGN.md colors become real utility classes:

   $ npx @google/design.md export --format json-tailwind DESIGN.md

6. Commit it. Like CLAUDE.md, its whole value is being in the repo — every future session, and every teammate's agent, inherits the same visual language for free.

Let Claude Code see your app in the browser

Up to now you've been the messenger: you look at localhost:3000, spot something wrong, describe it, and copy the console error back into the terminal. The Chrome integration removes that round trip. Claude Code drives a real Chrome window — it opens your app, clicks through it, reads the console, and then fixes the code that caused the error, in one go.

Two pieces have to meet: the Claude in Chrome extension in your browser, and Claude Code started with the --chrome flag.

1. Install the extension — Claude in Chrome from the Chrome Web Store (v1.0.36 or newer).
2. Start Claude Code with the browser attached. The first launch shows a one-time dialog explaining how site permissions work:

   $ claude --chrome

3. Ask it to go and look. Leave npm run dev running in its own terminal first:

   > Open localhost:3000, click through every link in the nav, and
     tell me if anything 404s or throws a console error.

   The first browser action asks permission to use the claude-in-chrome skill — approve it and a new tab opens.
4. Use /chrome when something's off. It shows the connection status — you want Status: Enabled and Extension: Installed — and lets you manage site permissions or reconnect if the extension goes idle during a long session.

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.