Back to Knowledge
Updated Sep 2026
GuideBeginner

Your First Next.js App

From zero to a running Next.js

Next.js

A React framework that adds routing, server rendering, API endpoints, and caching. The go-to for modern web apps. Current releases (Next.js 16) default to Turbopack, use proxy.ts instead of middleware.ts, and make caching explicit with Cache Components.

"Like React with a jetpack. Everything you need to go from idea to production."

app in about 15 minutes, then hand the keyboard to Claude Code. No fluff, no theory—just the exact steps to get something on screen.

Before You Start

  • ✓Node.js

    Node.js

    A runtime that lets you run JavaScript outside of a web browser. It's the engine that powers most modern dev tools, including Claude Code.

    "Like installing a game console. You need the console (Node) before you can play any games (run tools)."

     24 (the current Active LTS)     — check with node -v. You want v24.x. Node 18 and 20 are end-of-life, and Next.js 16 refuses to run on anything older than 20.9. Node 22 still works if that's what you have.
  • ✓A code editor — VS Code, Cursor, or anything you like
  • ✓Terminal access — VS Code and Cursor have one built in (Ctrl+`)

Missing any of these? Do Setup Your Workspace first, then come back.

1

Create the Project

Open your terminal in the folder where you keep projects and run:

Terminal

npx create-next-app@latest my-first-app

Answer the prompts like this:

  • Project name? Press Enter (my-first-app)
  • Use the recommended Next.js defaults? Yes, use recommended defaults

That one "yes" gives you the modern stack: TypeScript

TypeScript

JavaScript with superpowers. It adds types (like 'this must be a number') to catch errors before your code runs. Loved by teams and AI tools alike.

"Like JavaScript wearing a seatbelt. Same car, but way safer."

, ESLint, Tailwind CSS

Tailwind CSS

A utility-first CSS framework: instead of writing custom CSS, you use small classes like 'bg-blue-500' or 'p-4' directly in your markup. Tailwind v4 is CSS-first, so setup is just `@import "tailwindcss";` in your CSS plus the PostCSS plugin, with no config file required.

"Like a box of pre-labeled LEGO pieces. You build by combining small, predictable utilities."

 (v4), the App Router

App Router

Next.js's routing system based on the /app directory (the default since Next.js 13). Folders become routes, layouts nest, and components are Server Components by default. In Next.js 16, `params`, `searchParams`, `cookies()`, and `headers()` must all be awaited.

"Like a GPS that automatically knows every street in your app. Create a folder = create a route."

, Turbopack

Turbopack

The Rust-based bundler built into Next.js. Since Next.js 16 it's the default for both `next dev` and `next build`, no flag needed; you can opt out with `next build --webpack` if a plugin still needs webpack.

"Like swapping a bicycle courier for a motorbike. Same packages delivered, just a lot faster."

, the @/* import alias, and an AGENTS.md file that teaches coding agents to write up-to-date Next.js code.

Want zero prompts? The --yes flag accepts the defaults for you:

Terminal

npx create-next-app@latest my-first-app --yes
2

Open It in Your Editor

Move into your new project and open it:

Terminal

cd my-first-app
code .

code . opens VS Code in the current folder. If it doesn't work (or you use Cursor or another editor), open the editor manually and use File → Open Folder.

3

Start the Dev Server

In your editor's terminal (Ctrl+`), run:

Terminal

npm run dev

Your app is now running. Open http://localhost:3000 in your browser. Turbopack is the default bundler in Next.js 16, so there's no flag to add—it's just fast.

You should see the Next.js welcome page!

This means everything is working. Leave this terminal running and time to make it yours.

4

Understand the File Structure

Here's what matters right now:

my-first-app/
app/← Your pages live here
page.tsx← Homepage (edit this!)
layout.tsx← Wraps all pages
globals.css← Global styles + Tailwind import
public/← Static files (images, etc.)
AGENTS.md← Instructions for AI coding agents
next.config.ts← Next.js settings (leave it alone for now)
postcss.config.mjs← Plugs Tailwind into the build

Where's tailwind.config?

Gone, and that's on purpose. Tailwind v4 is CSS-first: one line, @import "tailwindcss";, at the top of globals.css is the whole setup. If an AI assistant or an old tutorial tells you to create a tailwind.config.js, it's working from stale info.

5

Make Your First Edit

Open app/page.tsx and replace ALL the content with this:

app/page.tsx

export default function Home() {
  return (
    <main className="min-h-screen flex items-center justify-center bg-black">
      <div className="text-center">
        <h1 className="text-5xl font-bold text-white mb-4">
          Hello, World!
        </h1>
        <p className="text-gray-400 text-xl">
          I just built my first Next.js app
        </p>
      </div>
    </main>
  );
}

Save the file (Ctrl+S). Your browser updates automatically—no refresh needed!

6

Add Some Interactivity

Let's add a button that does something. Replace your page.tsx with:

app/page.tsx

"use client";

import { useState } from "react";

export default function Home() {
  const [count, setCount] = useState(0);

  return (
    <main className="min-h-screen flex items-center justify-center bg-black">
      <div className="text-center">
        <h1 className="text-5xl font-bold text-white mb-4">
          Count: {count}
        </h1>
        <button
          type="button"
          onClick={() => setCount(count + 1)}
          className="px-6 py-3 bg-orange-500 text-white rounded-lg font-bold hover:bg-orange-600 transition-colors"
        >
          Click me!
        </button>
      </div>
    </main>
  );
}

Why "use client"?

Components in the App Router are Server Components

Server Component

A React component that runs ONLY on the server. Can directly access databases, fetch data, and keeps secrets safe. The default in Next.js App Router.

"Like the kitchen in a restaurant. Customers never see it, but that's where the magic happens."

by default: they render on the server and ship no JavaScript. The moment you use useState, click handlers, or any React hook, add "use client" at the top to make it a Client Component

Client Component

A React component that runs in the browser. Required for interactivity (useState, onClick, useEffect). Add "use client" at the top of the file.

"Like the dining room. The customer sees it, interacts with it, and clicks the buttons."

 that runs in the browser.

7

Create a Second Page

Create a new file at app/about/page.tsx:

app/about/page.tsx

import Link from "next/link";

export default function About() {
  return (
    <main className="min-h-screen flex items-center justify-center bg-black">
      <div className="text-center">
        <h1 className="text-5xl font-bold text-white mb-4">
          About Page
        </h1>
        <Link
          href="/"
          className="text-orange-500 hover:underline"
        >
          Go back home
        </Link>
      </div>
    </main>
  );
}

Now visit localhost:3000/about. The URL matches the folder name—that's file-based routing!

8

Bring in Claude Code

You just did it by hand so you know what's happening under the hood. Now let an agent do the typing. Open a second terminal (keep npm run dev running in the first), make sure you're inside my-first-app, and start Claude Code

Claude Code

Anthropic's agentic coding tool. It lives in your terminal (and in VS Code, JetBrains, and on the web), reads your codebase, edits files, runs commands, and ships code. Install with the native installer (`curl -fsSL https://claude.ai/install.sh | bash` on macOS/Linux, `irm https://claude.ai/install.ps1 | iex` on Windows); it needs a Pro, Max, Team, Enterprise, or Console account.

"Like having a senior developer living in your terminal, ready to help 24/7."

:

Terminal (second tab)

cd my-first-app
claude

Don't have it yet? The Claude Code setup guide covers the one-line native installer (and needs a paid Claude plan or Console account).

Your project already ships with AGENTS.md (plus a CLAUDE.md that points to it), so Claude starts out knowing modern Next.js conventions. Run /init once to have Claude suggest project-specific additions to that CLAUDE.md

CLAUDE.md

A Markdown file Claude Code reads at the start of every session: project context, commands, conventions, and rules. Put it at `./CLAUDE.md` (shared with the team), `~/.claude/CLAUDE.md` (personal, all projects), or `CLAUDE.local.md` (personal, gitignored). Run `/init` to generate a starter; AGENTS.md is read too.

"Like a welcome packet for a new team member. It tells Claude everything it needs to know about your project."

. Then try a first prompt:

Prompt

Turn the homepage into a simple landing page for a dog-walking business:
a hero with a headline and a "Book a walk" button, three service cards,
and a footer. Use Tailwind. Keep the counter on the /about page instead.
Show me the plan before you edit anything.

Watch the browser while Claude works

Every file Claude saves hot-reloads in the tab you already have open. Asking for "the plan first" is a lightweight version of Plan Mode—a great habit from day one. Before you let it make bigger changes, set up Git so you can undo anything.

You Did It!

You just built a Next.js app with multiple pages, styling, and interactivity—and pointed an AI agent at it. This is the foundation for everything else.

What You Learned

Project Setup

create-next-app with recommended defaults, npm run dev

File-Based Routing

Folders become URLs

Server vs. Client Components

"use client" only where you need interactivity

Tailwind CSS v4

Utility classes, no config file

Common Issues

"command not found: node"

Node.js isn't installed (or your terminal was open before you installed it). Follow Setup Your Workspace, then open a fresh terminal.

An error about your Node.js version

Next.js 16 needs Node 20.9 or newer. Run node -v; if it says v18 or v20, install Node 24 LTS and try again.

"Port 3000 already in use"

Another app is using port 3000. Close it or run npm run dev -- -p 3001

"useState is not defined" or "only works in a Client Component"

Missing import or missing directive. Add "use client"; as the first line and import { useState } from "react"; below it.

Page not updating?

Make sure you saved the file (Ctrl+S) and that npm run dev is still running. Check that terminal for errors.

Next Steps

Save Your Code

Learn Git so every AI change has an undo button.

Read Playbook

Deploy to the Internet

Push to GitHub and put your app online with Vercel's free Hobby plan.

Read Playbook

Learn Next.js Concepts

Server vs. Client Components, layouts, proxy.ts, and caching.

Read Playbook

Get Better with Claude Code

Prompts, context, and habits that keep the agent on track.

Read Guide