K
K12worX Education501(c)(3) Public Charity
Jamboree

Running the Dev Server

The development server lets you see the website on your computer and watch changes update in real-time. It's the core of your development workflow!

What is a Dev Server?

Development Server = Local web server that runs on your computer

Instead of visiting www.k12worx.org, you'll visit http://localhost:3000 - the website running on your own machine!

Benefits:

  • Test changes instantly
  • Work offline
  • Fast iteration (edit → save → see result in < 1 second!)
  • No risk of breaking the live website

Step 1: Install Dependencies

Before running the server, we need to install all required packages.

What are Dependencies?

Dependencies are code libraries our project needs:

  • Next.js (framework)
  • React (UI library)
  • Tailwind CSS (styling)
  • TypeScript (language)
  • And many more...

These are listed in package.json. The npm install command downloads them all.

Run npm install

# Make sure you're in the website folder
cd ~/Documents/projects/k12worx-jamboree/website

# Install all dependencies
npm install

What happens:

  1. npm reads package.json
  2. Downloads all packages from npm registry
  3. Saves them in node_modules/ folder
  4. Creates package-lock.json (locks versions)

Time: 1-3 minutes depending on internet speed

You'll see:

added 312 packages in 45s

(Numbers will vary)

Understanding node_modules

After npm install, you'll see a new node_modules/ folder:

website/
├── app/
├── components/
├── node_modules/     ← NEW! Contains all dependencies
├── package.json
└── ...

Important: Never edit files in node_modules/! This folder is auto-generated.

Step 2: Start the Dev Server

Now let's run the website!

npm run dev

What happens:

  1. Next.js starts a development server
  2. Compiles all TypeScript and React code
  3. Watches for file changes
  4. Serves the website at localhost:3000

You'll see:

 ▲ Next.js 15.0.7
 - Local:        http://localhost:3000
 - Network:      http://192.168.1.x:3000

 ✓ Ready in 2.3s

Leave this terminal running! The server must stay running for the website to work.

Step 3: Open in Browser

Open your web browser and visit:

http://localhost:3000

You should see: The K12worX Learning Jamboree website!

If you see an access gate (password prompt):

  • This is normal - the site is in "launching" mode
  • Enter the password (check with your coordinator)
  • Or disable it temporarily (we'll learn how later)

Understanding localhost:3000

What is localhost?

localhost = Your own computer

When you visit localhost:3000:

  • ✅ Only you can see it (not on the internet)
  • ✅ Changes happen instantly
  • ✅ Safe to break things!

What is :3000?

:3000 = Port number (like an apartment number)

Different apps use different ports:

  • 3000 - Next.js default
  • 3001 - If 3000 is busy
  • 5173 - Vite (different framework)
  • 8080 - Other common port

Hot Reload / Fast Refresh

This is where the magic happens!

Try It:

  1. Keep browser open at localhost:3000
  2. Open app/page.tsx in VS Code
  3. Find this line (around line 17): 
    Every Student Can Achieve Their Full Academic Potential
  4. Change it to: 
    Every Student Has Amazing Potential
  5. Save the file (Cmd+S / Ctrl+S)
  6. Watch the browser - it updates automatically!

No manual refresh needed! This is called "Fast Refresh" or "Hot Module Replacement" (HMR).

Development Workflow

Your typical workflow:

1. Edit file in VS Code
2. Save (Cmd+S / Ctrl+S)
3. Browser updates automatically (< 1 second!)
4. See result, continue editing

Repeat this loop thousands of times! It becomes natural quickly.

npm Commands Explained

npm run dev

npm run dev
  • Starts development server
  • Use this 99% of the time
  • Includes hot reload

npm run build

npm run build
  • Creates production build
  • Optimizes code for deployment
  • Use before deploying to live site

npm run lint

npm run lint
  • Checks code quality
  • Finds errors and style issues
  • Good practice before committing code

npm start

npm start
  • Previews production build locally
  • First run npm run build, then npm start

Stopping the Dev Server

When you're done:

  1. Go to the terminal where server is running
  2. Press Ctrl + C
  3. Confirm if asked (Y/N)

To start again: npm run dev

Troubleshooting

"Port 3000 is already in use"

Problem: Another app is using port 3000

Solutions:

Option 1: Kill the other process

# Mac/Linux
lsof -ti:3000 | xargs kill -9

# Windows
netstat -ano | findstr :3000
# Note the PID, then:
taskkill /PID <pid> /F

Option 2: Use a different port

# Specify different port
PORT=3001 npm run dev

# Then visit http://localhost:3001

"MODULE_NOT_FOUND" error

Problem: Dependencies not installed or corrupted

Solution:

# Delete node_modules and package-lock.json
rm -rf node_modules package-lock.json

# Reinstall
npm install

"Command not found: npm"

Problem: Node.js/npm not installed

Solution: Review Installing Node.js

Server starts but browser shows errors

Problem: Code errors or missing files

Solutions:

  1. Read the error message (in browser and terminal)
  2. Make sure you're on the main branch: git checkout main
  3. Pull latest changes: git pull
  4. Reinstall: rm -rf node_modules && npm install

Changes not appearing in browser

Problem: Hot reload not working

Solutions:

  1. Hard refresh: Cmd+Shift+R (Mac) / Ctrl+Shift+R (Windows)
  2. Restart dev server: Ctrl+C, then npm run dev
  3. Check terminal: Look for errors
  4. Clear cache: Browser settings → Clear cache

"Cannot find module 'next'"

Problem: Next.js not installed

Solution:

# Make sure you're in website folder
cd website

# Install dependencies
npm install

Understanding the Terminal Output

When server is running, you'll see updates:

event - compiled client and server successfully in 420 ms (247 modules)

✅ Successful compilation

wait  - compiling /page (client and server)...

⏳ Currently compiling

error - ./app/page.tsx:10:5
Syntax error: Unexpected token

❌ Error in your code - fix it!

Tips for Working with Dev Server

1. Keep Terminal Visible

Use VS Code's integrated terminal so you can see both code and server output.

2. One Server at a Time

Only run one npm run dev at a time (per project).

3. Restart If Weird

If things seem broken and you don't know why:

  1. Stop server (Ctrl+C)
  2. Start it again (npm run dev)

Often fixes mysterious issues!

4. Check Terminal for Errors

If the browser shows errors, check the terminal. Often has more details!

5. Browser DevTools

Open browser console (F12) to see JavaScript errors and logs.

Next Steps

Your dev server is running! Let's explore what you're seeing:

Exploring Localhost →

Quick Reference

Install dependencies:

npm install

Start dev server:

npm run dev

Stop server:

Ctrl + C

Open website:

http://localhost:3000

Common issue - port in use:

PORT=3001 npm run dev

External Resources

Next.js CLI: https://nextjs.org/docs/app/api-reference/next-cli

  • When to use: Understanding Next.js commands

npm Scripts: https://docs.npmjs.com/cli/v9/using-npm/scripts

  • When to use: Understanding how npm run works