Workflow

Build Your First AI-Assisted Website

Build a complete Next.js website from scratch using Claude Code as your AI coding agent. Learn the full workflow from project creation to live deployment.

BeginnerNext.jsClaude CodeAIdeploymentVercel

Goal

Build a live, deployed Next.js website using an AI coding agent — and understand every step of the process so you can repeat and extend it.

What you will build

A working Next.js website with:

  • A homepage with your content
  • A clean dark theme
  • Responsive layout
  • Deployed live on Vercel

Why it matters

Building your first website teaches you the complete loop: write → build → deploy → verify. Once you understand this loop, every future project is a variation on it. The AI agent accelerates the coding step — but the loop remains the same.

The loop is more important than the code

The website you build in this workflow will be replaced or improved. What you keep is the loop: create project → write code → run build → commit → push → verify deployment. Understand this loop deeply. Everything else is detail.

Tools needed

Folder structure

After project creation, your project will look like this:

my-website/
  app/
    layout.tsx      — shared HTML wrapper, head tags, fonts
    page.tsx        — the homepage
    globals.css     — global styles
  public/           — static assets (images, favicon)
  package.json      — project metadata and scripts
  tsconfig.json     — TypeScript settings
  next.config.ts    — Next.js configuration
  .gitignore        — files Git should ignore

Step-by-step workflow

Create the Next.js project

Open your terminal and run:

npx create-next-app@latest my-website

When prompted, choose:

  • TypeScript: Yes
  • ESLint: Yes
  • Tailwind CSS: Yes
  • App Router: Yes
  • Turbopack: Yes

This creates the full project structure automatically.

Open the project in VS Code

cd my-website
code .

VS Code opens with your project loaded.

Run the development server

npm run dev

Open http://localhost:3000 in your browser. You should see the default Next.js homepage. This is your starting point.

Start Claude Code

In a new terminal tab inside VS Code:

claude

Claude Code starts. It can now read and edit your entire project.

Describe your website to Claude Code

Tell Claude Code what you want. Be specific about the outcome, not the steps:

Build a homepage for my personal website. Dark theme with a navy/black background. 
Hero section with my name, title "AI & Robotics Engineer", and a short bio. 
Below that, a section with 3 project cards. Clean, modern design using Tailwind CSS. 
No placeholder lorem ipsum — use real-looking content.

Read every file Claude Code modifies. Do not accept changes you do not understand.

Verify the build

After Claude Code finishes:

npm run build

If there are errors, paste the error into Claude Code: "Fix this build error: [paste error]". Repeat until the build passes.

Commit to Git

git add .
git commit -m "Add homepage with hero and project cards"

Push to GitHub and deploy

Create a new repository on GitHub. Then:

git remote add origin https://github.com/YOUR_USERNAME/my-website.git
git push -u origin main

Import the repository on Vercel. Your site will be live in ~30 seconds.

What each file does

| File | Purpose | |------|---------| | app/layout.tsx | Wraps every page — fonts, metadata, shared components like navbar | | app/page.tsx | The homepage at / | | app/globals.css | Global CSS — base styles, custom properties | | public/ | Static files served directly — images, favicon | | next.config.ts | Next.js configuration — custom settings | | package.json | Lists dependencies and defines npm run dev, npm run build |

Common Mistakes
  • Not reading Claude Code's changes — the agent can write code that compiles but doesn't match your intent. Read the diff.
  • Skipping the build step — the development server hides some errors that only appear in the production build. Always run npm run build before deploying.
  • Committing node_modules/ — check your .gitignore. It should already exclude node_modules/.
How to Verify It Works
  • npm run dev runs without errors
  • The homepage shows your content in the browser
  • npm run build completes with no errors
  • The site is live on a *.vercel.app URL
  • The Vercel deployment log shows no errors
Final Checklist
  • Node.js and npm are installed (node -v shows version 18+)
  • npm run dev works and shows your homepage
  • Homepage has your actual content, not placeholders
  • npm run build passes with no TypeScript or build errors
  • Code is committed to GitHub with a clear commit message
  • Vercel deployment is live and accessible from a public URL
  • You have visited the live URL and confirmed it matches local

Next Steps

Push a project to GitHub

Deeper Git workflow

Deploy GitHub repo to Vercel

Full deployment configuration

Debug AI-generated code

When things go wrong

Next workflow