Setting Up a Next.js Project

Creating a new project

npx create-next-app@latest my-app
cd my-app
npm run dev

The CLI asks a few questions (TypeScript, ESLint, Tailwind CSS, src/ directory, App Router, import alias) and scaffolds a ready-to-run project. Since Next.js 16, create-next-app also offers an "AI-ready" scaffold option that adds an AGENTS.md file with project conventions for coding agents.

The App Router folder structure

my-app/
├── app/
│   ├── layout.tsx      # root layout, wraps every page
│   ├── page.tsx         # the "/" route
│   ├── globals.css
│   ├── about/
│   │   └── page.tsx     # the "/about" route
│   └── blog/
│       ├── page.tsx     # "/blog"
│       └── [slug]/
│           └── page.tsx # "/blog/:slug"
├── public/               # static files served as-is
├── next.config.ts
├── package.json
└── tsconfig.json

Special file names inside app/ are conventions the router understands: page.tsx (a route's UI), layout.tsx (shared UI that wraps children), loading.tsx (a loading fallback), error.tsx (error boundary), not-found.tsx, and route.ts (an API endpoint) — covered in later chapters.

App Router vs Pages Router

Next.js has two routing systems. The App Router (app/ directory) is the current, actively developed system — it supports Server Components, layouts, streaming, and Server Actions. The older Pages Router (pages/ directory) still works and is fully supported, but new features ship to the App Router first. This course uses the App Router throughout, since it's what the Next.js team recommends for all new projects.

Key configuration files

// next.config.ts
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  images: { domains: ['example.com'] },
  experimental: {
    cacheComponents: true, // enable Cache Components (Next.js 16+)
  },
};

export default nextConfig;

// package.json scripts
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  }
}

Running and building

npm run dev     # local development server with Turbopack, hot reload
npm run build   # production build
npm run start   # run the production build locally