CIA/e-voting-system/DEV_MODE.md

Frontend Development Mode - Setup & Usage

🚀 Quick Start

Option 1: Using the Helper Script (Recommended)

# Start frontend in development mode
./dev-mode.sh start

# In another terminal, stream logs
./dev-mode.sh logs

# To stop
./dev-mode.sh stop

Option 2: Direct Docker Compose Commands

# Start dev frontend with other services
docker compose -f docker-compose.yml -f docker-compose.dev.yml up frontend-dev

# Stream logs
docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f frontend-dev

# Stop
docker compose -f docker-compose.yml -f docker-compose.dev.yml down

---

✨ Features in Development Mode

✓ Hot Module Reload (HMR)

• Changes to .ts, .tsx, .css files automatically refresh in browser
• No need to rebuild container
• Source maps for debugging

✓ Detailed Logging

• Browser console logs visible in Docker logs
• Server-side render logs
• API request/response debugging
• Network timing information

✓ Development Tools

• Next.js dev server with full diagnostics
• TypeScript error messages with line numbers
• React Fast Refresh for component updates
• Network tab in browser DevTools

✓ Volume Mounting

• ./frontend:/app - all source code hot-reloaded
• /app/node_modules - isolated for performance
• /app/.next - isolated build cache

---

🔧 Available Commands

# Start development mode
./dev-mode.sh start

# Stop development mode
./dev-mode.sh stop

# Stream frontend logs only
./dev-mode.sh logs

# Stream ALL services logs
./dev-mode.sh logs-all

# Rebuild dev image (after package.json changes)
./dev-mode.sh rebuild

# Open shell in dev container
./dev-mode.sh shell

# Check container status
./dev-mode.sh status

---

📍 Access Points

Service	URL	Purpose
Frontend (Dev)	http://localhost:3000	Application with hot reload
Backend API	http://localhost:8000	API endpoint
API Docs	http://localhost:8000/docs	Swagger documentation
Database Admin	http://localhost:8081	MariaDB management

---

🔍 Debugging Tips

View Detailed Frontend Logs

./dev-mode.sh logs

# Or use grep to filter
docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f frontend-dev | grep -i error

Check All Services

./dev-mode.sh logs-all

Open Terminal in Container

./dev-mode.sh shell

# Inside container, you can run:
npm run lint
npm run type-check
npm run build

Browser DevTools

1. Open http://localhost:3000
2. Open DevTools (F12 or Ctrl+Shift+I)
3. View:
   • Console - see all logs from Next.js
   • Network - see API requests/responses
   • Sources - debug TypeScript code
   • Application - inspect state/localStorage

---

🛠️ When to Rebuild

# After changing package.json or package-lock.json
./dev-mode.sh rebuild

# After changing environment variables in Dockerfile.frontend.dev
./dev-mode.sh rebuild

# Usually NOT needed for code changes (hot reload works)

---

📊 Environment Variables in Dev Mode

Automatically set in docker-compose.dev.yml:

NODE_ENV: development          # Enable dev features
NEXT_PUBLIC_DEBUG: 'true'      # Frontend debug mode
NEXT_PUBLIC_API_URL: http://localhost:8000

---

🔄 Hot Reload Workflow

1. Edit a file → frontend/components/something.tsx
2. Save → File is mounted in container
3. Next.js detects change → ~500ms
4. Fast Refresh → Browser auto-reloads
5. View in DevTools → Console shows updates

---

🐛 Common Issues

Container won't start

# Check logs
./dev-mode.sh logs

# Rebuild from scratch
./dev-mode.sh rebuild
./dev-mode.sh start

Port 3000 already in use

# Change port in docker-compose.dev.yml
# Or kill existing process
lsof -ti:3000 | xargs kill -9

Changes not reflecting

# Try full refresh in browser
Ctrl+Shift+R (hard refresh)

# Or restart container
./dev-mode.sh stop
./dev-mode.sh start

Need to see all npm commands

./dev-mode.sh shell
cat package.json | grep -A 10 '"scripts"'

---

📝 Production vs Development

Aspect	Production	Development
Build	Optimized, minified	Unoptimized for speed
HMR	✗ No	✓ Yes
Logging	Minimal	Verbose
Performance	Fast	Slower (for debugging)
File Size	~100KB	~5MB
Startup	5-10s	30-60s

---

🚀 Performance Notes

• Dev mode is intentionally verbose for debugging
• Larger bundle size than production
• Slower startup is normal
• HMR eliminates need for full rebuilds

Use production mode for performance testing.

---

📚 Further Reading

• Next.js Dev Server
• Docker Compose Override
• React DevTools

---

Last Updated: 2025-11-07