1. Introduction

Next.js is a powerful React framework for building modern web applications with server-side rendering (SSR), static site generation (SSG), API routes, and full-stack capabilities. This guide covers **installation, setup, configuration, and common errors**.

2. Prerequisites

• Node.js (Recommended v18 or later)
• npm or yarn (comes with Node.js)
• Basic knowledge of JavaScript and React
• Code editor like VSCode
• Terminal / Command Prompt access

3. Check Node.js and npm

node -v
npm -v

Ensure Node.js and npm are installed. Example output:

v18.16.0
9.8.0

Common Errors

• Command not found → Node.js not installed → Install Node.js from official site.
• Old Node version → Some Next.js features fail → Upgrade Node.js.

4. Create a Next.js Project

Option 1: Using create-next-app

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

Steps:

• Enter project name → e.g., my-next-app
• Select TypeScript or JavaScript
• Include ESLint and Tailwind if desired

Option 2: Using yarn

yarn create next-app my-next-app

Option 3: Using pnpm

pnpm create next-app my-next-app

Real-life Analogy

Think of this command as hiring a contractor who builds a **ready-to-use restaurant** with tables, kitchen, and chairs (project skeleton).

Common Errors

• npx not found → install Node.js / npm properly.
• Permission denied → use sudo (Linux/macOS) or run as administrator (Windows).
• Old create-next-app version → Update npm or npx.

5. Navigate into Project

cd my-next-app

Verify structure:

my-next-app/
├── app/
├── node_modules/
├── public/
├── package.json
├── next.config.js
└── .gitignore

Common Errors

• Cannot find module → forgot to cd into project
• npm run dev fails → dependencies not installed → run npm install

6. Run Development Server

npm run dev

Output:

Local:   http://localhost:3000
Network: http://192.168.1.100:3000

Visit in browser → default Next.js welcome page.

Alternative Commands

yarn dev
pnpm dev

Common Errors

• Port 3000 in use → specify another port: npm run dev -- -p 4000
• Module not found → run npm install

7. Install Additional Dependencies

Optional but common dependencies:

• Tailwind CSS:

  npm install -D tailwindcss postcss autoprefixer
  npx tailwindcss init -p

• Prisma (database ORM):

  npm install @prisma/client
  npm install prisma --save-dev
  npx prisma init

• Axios (HTTP requests):

  npm install axios

Common Errors

• PostCSS error → Tailwind not configured correctly
• Prisma schema missing → database connection fails

8. Project Structure Overview

my-next-app/
├── app/            # Pages and layouts (App Router)
├── public/         # Images, fonts, static files
├── node_modules/   # Packages
├── package.json    # Dependencies and scripts
├── next.config.js  # Next.js configuration
└── styles/         # CSS files (optional)

All development happens inside app/ folder.

Real-life Analogy

app/ → tables & menus (pages) public/ → store front / showcase (images & static files) node_modules/ → warehouse (dependencies) package.json → project blueprint next.config.js → rules & regulations of restaurant styles/ → decoration & design

9. Building & Production

Build Project

npm run build

Start Production Server

npm start

Common Errors

• Missing build → run npm run build
• Environment variable missing → process.env error
• Port in use → specify port with PORT=4000 npm start

10. Optional Setup for Database

• Install Prisma or other ORM
• Create .env file with DATABASE_URL="mysql://user:pass@localhost:3306/dbname"
• Run migrations:

  npx prisma migrate dev --name init

• Use lib/prisma.js to export Prisma client.

Common Errors

• Invalid DATABASE_URL → cannot connect to DB
• Migration error → database already exists / wrong schema

11. Summary & Best Practices

• Always use Node.js v18+ for Next.js 14+
• Use npx create-next-app for official project structure
• Check project folder structure before running dev server
• Install all dependencies correctly
• Use .env for secrets and database connections
• Use recommended ports (3000) unless occupied
• Follow app/ folder conventions for pages, layouts, and components