# Frontend Development Mode - Setup & Usage

## 🚀 Quick Start

### Option 1: Using the Helper Script (Recommended)

```bash
# 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

```bash
# 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

```bash
# 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
```bash
./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
```bash
./dev-mode.sh logs-all
```

### Open Terminal in Container
```bash
./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

```bash
# 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`:

```yaml
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
```bash
# Check logs
./dev-mode.sh logs

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

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

### Changes not reflecting
```bash
# 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
```bash
./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](https://nextjs.org/docs/app/api-reference/cli/next/dev)
- [Docker Compose Override](https://docs.docker.com/compose/extends/)
- [React DevTools](https://react-devtools-tutorial.vercel.app/)

---

**Last Updated:** 2025-11-07