Running the dev server & hot reloading (lab)

Lab Overview

In this lab, you'll learn everything about running your Next.js development server, understanding hot reloading, and using the dev environment efficiently. These are skills you'll use every single day as a Next.js developer.

Starting the Development Server

Navigate into your Next.js project folder and run:

cd my-nextjs-app
npm run dev

What happens next:

▲ Next.js 14.1.0
- Local:        http://localhost:3000
- Environments: .env.local

✓ Starting...
✓ Ready in 1532ms

Now open your browser at http://localhost:3000

You're now running a local development server — it's only accessible on your machine.

What is Hot Reloading?

Hot Reloading (also called Fast Refresh in Next.js) is one of the most productive features for developers. It means:

When you save a file, the browser automatically updates — without a full page reload — and without losing your app's state.

![Hot Reloading Demo] - i will add the image here

Without Hot Reloading (Old Way):

1. Edit code → Save
2. Manually press F5 / Ctrl+R to refresh
3. Lose all your input state, scroll position, etc.

With Hot Reloading (Next.js Way):

1. Edit code → Save
2. Browser instantly shows the change
3. State is preserved (form inputs stay filled, modal stays open, etc.)

Lab: See Hot Reloading in Action

Step 1 — Open app/page.tsx

// app/page.tsx (default content)
export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-between p-24">
      <h1>Hello World</h1>
    </main>
  );
}

Step 2 — Make a change and save

Change "Hello World" to anything:

export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-between p-24">
      <h1>🚀 I changed this and it updated instantly!</h1>
      <p>Hot reloading is amazing!</p>
    </main>
  );
}

Step 3 — Watch the browser

The browser updates immediately without you doing anything. That's Fast Refresh at work!

Understanding the Dev Server Output

When you run npm run dev, the terminal shows useful information:

▲ Next.js 14.1.0
- Local:        http://localhost:3000     ← Your app URL
- Network:      http://192.168.1.5:3000  ← Access from other devices on same WiFi

✓ Ready in 1532ms

○ Compiling / ...                         ← Compiling the route being visited
✓ Compiled / in 1.5s (512 modules)       ← Successfully compiled

GET / 200 in 1521ms                       ← HTTP request log

What the symbols mean:

Accessing Your Dev Server from Other Devices

Want to test your app on your phone while developing?

# Start server accessible on your local network
npm run dev -- --hostname 0.0.0.0

Then on your phone (connected to same WiFi), visit the Network URL shown in the terminal:

Changing the Default Port

By default, the dev server runs on port 3000. If that port is busy, you can change it:

# Run on a different port
npm run dev -- --port 4000
# or
npm run dev -p 4000

Or set it permanently in package.json:

"scripts": {
  "dev": "next dev --port 4000"
}

Turbopack — The Faster Dev Server

Next.js 14+ includes Turbopack, a Rust-based bundler that makes the dev server significantly faster:

# Enable Turbopack (if not already set up)
npm run dev --turbo

Or in package.json:

"scripts": {
  "dev": "next dev --turbo"
}

Turbopack vs Webpack Speed Comparison:

🚀 Turbopack is up to 10x faster than Webpack for large projects!

Types of Updates in Fast Refresh

Next.js Fast Refresh handles three types of changes differently:

1. Pure Component Changes

If you only edit the JSX/rendering logic — Fast Refresh updates only that component, preserving all state.

// Edit the text → only the text updates, form state preserved
<h1>Changed title</h1>

2. Custom Hooks / Modules

If you edit a custom hook or utility that a component uses — that component fully remounts.

3. Non-React Files (config, utils)

If you edit next.config.mjs or server-side files — the entire page reloads (full refresh).

Stopping the Dev Server

Press Ctrl + C in the terminal to stop the server.

^C   ← Ctrl+C stops the server

Common Dev Server Errors & Fixes

Error: Port 3000 is already in use

# Find what's using port 3000
# Mac/Linux:
lsof -i :3000

# Windows:
netstat -ano | findstr :3000

# Kill the process (Mac/Linux):
kill -9 <PID>

# Or just use a different port:
npm run dev -p 3001

Error: Module not found

# Fix: reinstall dependencies
rm -rf node_modules
npm install
npm run dev

Error: Cannot find module 'next'

# Fix: install Next.js
npm install next react react-dom

Dev Server vs Production Server

Always test your app with npm run build && npm run start before deploying — dev mode hides some production issues.

The .next/ Folder During Development

Every time you make a change, Next.js recompiles only the affected modules and stores them in .next/cache/. This is why subsequent loads are faster than the first!

Full Lab Exercise

Try all of these while your dev server is running:

1. Edit app/page.tsx — change the text, watch it update instantly ✓
2. Edit app/globals.css — change a color or font, watch it update ✓
3. Create a new file app/about/page.tsx — visit /about in the browser ✓
4. Introduce a syntax error — notice the error overlay in the browser ✓
5. Fix the error — watch it recover automatically ✓

// app/about/page.tsx — create this file!
export default function About() {
  return (
    <div>
      <h1>About Page</h1>
      <p>This page was created during the hot reloading lab! 🎉</p>
    </div>
  );
}

After saving, visit http://localhost:3000/about — it works automatically!

Watch This Lab in Action

Fireship's Next.js in 100 Seconds + dev server walkthrough — best quick overview of the dev experience.

Lab Checklist

• Dev server started with npm run dev
• Visited http://localhost:3000 in browser
• Edited page.tsx and saw instant hot reload
• Created a new page at app/about/page.tsx
• Understood the difference between dev and production server
• Know how to change ports and stop the server