Back to Playbook
GuideBeginner

Your First Next.js App

From zero to running app in 15 minutes. No fluff, no theory—just the exact steps to get something on screen.

Before You Start

  • ✓Node.js 18+ installed — check with node -v
  • ✓VS Code or any code editor
  • ✓Terminal access — VS Code has one built in (Ctrl+`)
1

Create the Project

Open your terminal and run this command. It creates a new Next.js project with all the modern defaults.

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

Answer the prompts like this:

  • TypeScript? Yes
  • ESLint? Yes
  • Tailwind CSS? Yes
  • src/ directory? No (simpler for beginners)
  • App Router? Yes (the new standard)
  • Turbopack? Yes (faster dev server)
  • Import alias? Just press Enter
2

Open in VS Code

Navigate into your new project and open it in VS Code:

bash
cd my-first-app
code .

The code . command opens VS Code in the current folder. If it doesn't work, open VS Code manually and use File → Open Folder.

3

Start the Dev Server

In VS Code, open the terminal (Ctrl+`) and run:

bash
npm run dev

Your app is now running! Open http://localhost:3000 in your browser.

You should see the Next.js welcome page!

This means everything is working. 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
public/← Static files (images, etc.)
5

Make Your First Edit

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

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 automatically updates—no refresh needed!

6

Add Some Interactivity

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

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
          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"?

When you use useState or any React hooks, you need to add "use client" at the top. This tells Next.js the component needs to run in the browser.

7

Create a Second Page

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

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!

You Did It!

You just built a Next.js app with multiple pages, styling, and interactivity. This is the foundation for everything else.

What You Learned

Project Setup

create-next-app, npm run dev

File-Based Routing

Folders become URLs

Client Components

"use client" for interactivity

Tailwind CSS

Utility classes for styling

Common Issues

"command not found: node"

Node.js isn't installed. Download from nodejs.org

"Port 3000 already in use"

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

"useState is not defined"

Missing import! Add import { useState } from "react"; at the top

Page not updating?

Make sure you saved the file (Ctrl+S). Check the terminal for errors.

Next Steps

Learn Next.js Concepts

Deep dive into Server vs Client Components, App Router, and more.

Read Playbook

Deploy to the Internet

Put your app online for free with Vercel in 2 minutes.

Read Playbook

Connect a Database

Store real data with Neon Postgres and Drizzle ORM.

Start Guide

Save Your Code

Learn Git to save versions and collaborate with others.

Read Playbook