Skip to main content
Each lesson in the Next.js Noob Playground is a complete, standalone Next.js application. This guide will walk you through running any lesson, making changes, and troubleshooting common problems.

​
Prerequisites

Before running any lesson, ensure you have:
1

Node.js installed

You need Node.js version 18 or higher.Check your version:
node --version
If you see v18.0.0 or higher, you’re good to go.Don’t have Node.js? Download it from nodejs.org
2

A code editor

We recommend VS Code, but any code editor works.
3

A terminal/command line

  • Mac: Use Terminal (built-in)
  • Windows: Use Command Prompt, PowerShell, or Git Bash
  • Linux: Use your default terminal

​
Running Your First Lesson

1

Navigate to a lesson folder

Open your terminal and navigate into any lesson folder. Let’s start with the first one:
cd 01-hello-saas
On Windows, use \ instead of / for paths: cd 01-hello-saas
2

Install dependencies

Every lesson needs its dependencies installed first. Run:
npm install
This command:
  • Reads the package.json file
  • Downloads all required packages (React, Next.js, etc.)
  • Creates a node_modules folder with the packages
Expected output:
added 152 packages, and audited 153 packages in 8s
You only need to run npm install once per lesson (unless you add new dependencies later).
3

Start the development server

Now start the Next.js development server:
npm run dev
Expected output:
▲ Next.js 14.0.0
- Local:        http://localhost:3000
- Network:      http://192.168.1.x:3000

✓ Ready in 1.2s
Don’t close this terminal window! The development server must keep running.
4

Open in browser

Open your web browser and go to:
http://localhost:3000
You should see the lesson’s home page!

​
Making Changes & Hot Reloading

One of the best features of Next.js is hot reloading - your changes appear instantly in the browser without refreshing.

​
Try It Yourself

1

Open the code in your editor

With the dev server still running, open the lesson folder in your code editor.
2

Edit the home page

Open app/page.js and change some text:
app/page.js
export default function HomePage() {
  return (
    <div>
      <h1>🚀 My Amazing SaaS App!</h1>  {/* Change this text */}
    </div>
  )
}
3

Save the file

Press Cmd+S (Mac) or Ctrl+S (Windows/Linux)
4

Watch the magic

Look at your browser - the changes appear instantly without refreshing!
Hot reloading preserves your application state, making development much faster.

​
Understanding npm Scripts

Each lesson’s package.json defines several useful scripts: 
npm run dev
# Starts development server at http://localhost:3000
# Hot reloading enabled
# Shows helpful error messages

​
When to Use Each Command

CommandUse Case
npm run devDaily development work
npm run buildBefore deploying to production
npm run startRunning production build locally

​
Working with Multiple Lessons

You can run multiple lessons simultaneously, but they’ll conflict on port 3000.

​
Solution 1: Stop Previous Server

Press Ctrl+C in the terminal to stop the current server, then start a different lesson.

​
Solution 2: Use Different Ports

# Terminal 1: Run lesson 1 on port 3000
cd 01-hello-saas
npm run dev

# Terminal 2: Run lesson 3 on port 3001
cd 03-tailwind-components
npm run dev -- -p 3001
Now visit:
  • Lesson 1: http://localhost:3000
  • Lesson 3: http://localhost:3001
Lessons with multiple pages (Lesson 2 onwards) have navigation: 
http://localhost:3000          → Home page
http://localhost:3000/pricing  → Pricing page
http://localhost:3000/about    → About page
http://localhost:3000/login    → Login page
The URL path matches the folder structure in app/:
  • app/page.js → /
  • app/pricing/page.js → /pricing
  • app/about/page.js → /about

​
Troubleshooting Common Issues

​
Port 3000 Already in Use

Error: 
Error: Port 3000 is already in use
Solutions:
Mac/Linux:
lsof -ti:3000 | xargs kill -9
Windows:
netstat -ano | findstr :3000
taskkill /PID <PID_NUMBER> /F

npm run dev -- -p 3001
Then visit http://localhost:3001

​
Module Not Found Errors

Error: 
Error: Cannot find module 'next'
Solution: You forgot to run npm install. Install dependencies: 
npm install

​
Changes Not Appearing

Problem: You saved changes but don’t see them in the browser. Solutions:
1

Check if dev server is running

Look at your terminal - you should see messages like:
✓ Compiled /page in 234ms
2

Hard refresh browser

  • Mac: Cmd+Shift+R
  • Windows/Linux: Ctrl+Shift+R
3

Restart dev server

Press Ctrl+C in terminal, then run npm run dev again.

​
Syntax Errors

Error: 
SyntaxError: Unexpected token '<'
Cause: You have a JavaScript syntax error in your code. Solution:
  1. Check the terminal - it shows which file has the error
  2. Look at the line number mentioned
  3. Common issues:
    • Missing closing bracket }
    • Missing closing parenthesis )
    • Missing closing tag </div>
Next.js error messages are very helpful! Read them carefully - they usually tell you exactly what’s wrong and where.

​
Cannot Access localhost

Problem: Browser shows “This site can’t be reached” Solutions:
Look at your terminal - do you see:
✓ Ready in 1.2s
If not, the server isn’t running. Start it with npm run dev.
Make sure you’re visiting exactly:
http://localhost:3000
Not:
  • https:// (http, not https)
  • localhoat (typo)
  • 127.0.0.1 (use localhost)
If Chrome doesn’t work, try Firefox or Safari.

​
Dependencies Installation Failed

Error: 
npm ERR! network request failed
Solutions:
  1. Check your internet connection
  2. Try clearing npm cache: 
    npm cache clean --force
npm install
  3. Delete node_modules and package-lock.json, then reinstall: 
    rm -rf node_modules package-lock.json
npm install

​
Development Best Practices

​
Keep Dev Server Running

Leave npm run dev running while you code. Don’t stop and restart it constantly.

​
Check Terminal for Errors

Always keep your terminal visible. Next.js shows helpful error messages there.

​
Save Files Frequently

Get in the habit of saving (Cmd+S / Ctrl+S) after every small change to see results immediately.

​
Read Error Messages

Next.js error messages are beginner-friendly:
  • They show the exact file and line number
  • They often suggest how to fix the issue
  • They highlight the problematic code

​
Quick Reference

​
Essential Commands

# Navigate to lesson
cd 01-hello-saas

# Install dependencies (first time only)
npm install

# Start dev server
npm run dev

# Stop dev server
Ctrl+C

# Start on different port
npm run dev -- -p 3001

​
File Locations

FilePurpose
app/page.jsHome page - start editing here
app/layout.jsWraps all pages (navbar, fonts, etc.)
package.jsonLists dependencies and scripts
node_modules/Installed packages (auto-generated)

​
Keyboard Shortcuts

ActionMacWindows/Linux
Save fileCmd+SCtrl+S
Stop serverCtrl+CCtrl+C
Hard refreshCmd+Shift+RCtrl+Shift+R

​
Next Steps

Now that you can run lessons, learn how to customize them for your own SaaS:

Customize Lessons

Adapt the code to build your own unique SaaS product

Build docs developers (and LLMs) love

Get started for freeTalk to us