15 min read

Your First Next.js Project

Scaffold a real Next.js app with the NerdSystem stack and understand every file it generates.

Let's Build Something

You've got your tools installed. Now it's time to create an actual project — one you'll keep building on throughout this course.

We're going to use Next.js with the stack that powers most modern web apps: TypeScript, Tailwind CSS, and the App Router.

The App Router is the recommended approach for all new Next.js projects. It uses React Server Components by default and has a simpler mental model for layouts and data fetching.

Scaffolding the Project

Next.js ships with a CLI tool called create-next-app that sets up everything for you. Run it and answer the prompts like this:

$ npx create-next-app@latest nerdsystem-app

✔ Would you like to use TypeScript? … Yes
✔ Would you like to use ESLint? … Yes
✔ Would you like to use Tailwind CSS? … Yes
✔ Would you like your code inside a src/ directory? … Yes
✔ Would you like to use App Router? (recommended) … Yes
✔ Would you like to use Turbopack for next dev? … Yes
✔ Would you like to customize the import alias (@/* by default)? … No

Creating a new Next.js app in ./nerdsystem-app...

Installing dependencies:
- react
- react-dom
- next

Installing devDependencies:
- typescript
- @types/node
- @types/react
- @types/react-dom
- eslint
- eslint-config-next
- tailwindcss
- @tailwindcss/postcss
- postcss

Success! Created nerdsystem-app at ./nerdsystem-app

Let's walk through each choice so you know why it matters:

0 of 6 complete

TypeScript — Yes

TypeScript catches bugs before they reach your users. AI tools also generate better code when they have type information to work with.

ESLint — Yes

Automatically flags code quality issues. It's like a spell-checker for your code.

Tailwind CSS — Yes

Utility-first CSS that lets you style components without switching between files. We'll cover it in depth later.

src/ directory — Yes

Keeps your application code separate from config files at the root. Cleaner project, cleaner mind.

App Router — Yes

The modern routing system in Next.js. Uses file-based routing inside the app/ directory.

Turbopack — Yes

A faster bundler for development. Your dev server will start and refresh noticeably quicker.

What's in the Box?

Here's what create-next-app just generated for you:

File Structure

nerdsystem-app/
├── src/
│   └── app/
│       ├── layout.tsx       # Root layout — wraps every page
│       ├── page.tsx         # Home page (localhost:3000/)
│       ├── globals.css      # Global styles + Tailwind imports
│       └── favicon.ico      # Browser tab icon
├── public/
│   ├── file.svg             # Static assets served at /file.svg
│   ├── globe.svg
│   ├── next.svg
│   ├── vercel.svg
│   └── window.svg
├── package.json             # Dependencies + scripts
├── tsconfig.json            # TypeScript configuration
├── next.config.ts           # Next.js settings
├── postcss.config.mjs       # PostCSS config (used by Tailwind)
├── eslint.config.mjs        # ESLint rules
├── .gitignore               # Files git should ignore
└── README.md                # Project readme

Let's break down the important files:

package.json — Lists your dependencies and defines scripts like dev, build, and start. This is the "table of contents" for your project.

tsconfig.json — Tells TypeScript how strict to be and where to find your code. The @/* alias lets you import from src/ without messy relative paths like ../../../.

next.config.ts — Where you configure Next.js behavior: redirects, environment variables, image domains, and more. It starts nearly empty — you'll add to it as your app grows.

src/app/layout.tsx — The root layout. It wraps every page in your app with shared HTML structure (the <html> and <body> tags, fonts, metadata). Think of it as your app's skeleton.

src/app/page.tsx — The home page. In the App Router, every page.tsx file becomes a route. This one maps to /.

src/app/globals.css — Imports Tailwind's base styles and is where you'd add any global CSS.

App Router vs Pages Router — what's the difference?

Next.js has two routing systems. The Pages Router (pages/ directory) was the original — each file in pages/ became a route, and data fetching used special functions like getServerSideProps.

The App Router (app/ directory) is the modern replacement. It uses React Server Components by default, supports nested layouts, and has a simpler approach to loading states and error handling.

You'll see both in tutorials online. If a tutorial mentions pages/, getServerSideProps, or getStaticProps, it's using the old system. Everything in this course uses the App Router.

Start the Dev Server

Time to see your app running:

$ cd nerdsystem-app
$ npm run dev

▲ Next.js 15.3.1 (Turbopack)
- Local:    http://localhost:3000
- Network:  http://192.168.1.42:3000

✓ Starting...
✓ Ready in 1.2s

Open http://localhost:3000 in your browser. You should see the default Next.js welcome page.

Make Your First Change

Let's prove this is real. Open src/app/page.tsx and replace the entire contents with:

src/app/page.tsx

export default function Home() {
return (
  <div className="flex min-h-screen items-center justify-center">
    <h1 className="text-4xl font-bold">
      NerdSystem is live 🚀
    </h1>
  </div>
);
}

Save the file and check your browser — it updates instantly. That's Turbopack's hot reload in action. No restart needed.

You just wrote a React Server Component styled with Tailwind CSS. Every className like text-4xl and font-bold is a utility that maps to a CSS property. You'll get comfortable with these fast.

Quick Recap

You now have a real Next.js project with TypeScript, Tailwind, and the App Router. You understand what every generated file does, and you've made your first change.

What does the src/app/layout.tsx file do?

In the App Router, how does a file become a route?

What does Turbopack do?

Troubleshooting common errors

Port 3000 already in use Another process is using port 3000. Either stop it or start Next.js on a different port:

npx kill-port 3000
# or
npm run dev -- --port 3001

TypeScript errors on a fresh project The install may not have finished cleanly. Delete node_modules and reinstall:

rm -rf node_modules
npm install

Page doesn't update after saving Hot reload might be stuck. Try a hard refresh in your browser (Cmd+Shift+R on macOS, Ctrl+Shift+R on Windows/Linux). If that doesn't work, stop the dev server and restart it with npm run dev.

Exercise: Customize Your Home Page

Open src/app/page.tsx and update it to show your name, a brief one-line description of what you do, and a styled link to your GitHub profile. Use at least three Tailwind utility classes from this lesson (e.g., text-4xl, font-bold, flex).

Try doing this manually first to get familiar with TSX and Tailwind, or use Claude Code: "Update src/app/page.tsx to show my name, a description, and a GitHub link. Use Tailwind for styling." Both approaches are valid — we'll cover the AI workflow in depth in the next module.

Show hint

Look at the className patterns shown in the "Make Your First Change" section. You can use text-lg for the description text and text-blue-500 hover:underline for the link.

Show solution

export default function Home() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center gap-4">
      <h1 className="text-4xl font-bold">Your Name</h1>
      <p className="text-lg text-gray-600">Building things with Next.js and AI</p>
      <a
        href="https://github.com/your-username"
        className="text-blue-500 hover:underline"
      >
        GitHub Profile
      </a>
    </div>
  );
}

Next Up

Your project exists on your machine, but it's not safe yet. In the next lesson, you'll learn Git and GitHub — how to save your work, track changes, and push your code somewhere it can't be lost.