Hot Reload¶

Development environment with automatic code reloading.

Overview¶

Hot reload enables instant feedback during development:

Change Type	Reload Time	State Preserved
Python (.py)	~1 second	No
React (.tsx)	< 1 second	Yes
Tailwind (CSS)	Instant	Yes

Docker Development¶

Start Services¶

# Using dev script
./dev.sh start

# Or directly
docker-compose up -d

How It Works¶

flowchart LR
    Editor["Your Editor<br/>(save file)"] --> Volume["Docker Volume<br/>(sync)"]
    Volume --> Container["Container<br/>(detect)"]
    Container --> Reload["Reload Process"]

Backend Hot Reload¶

Uvicorn watches for file changes:

# docker-compose.yml
backend:
  volumes:
    - ./backend:/app    # Mount source code
  command: uvicorn app.main:app --reload --host 0.0.0.0

Process:

Save Python file
Docker syncs to container (~100ms)
Uvicorn detects change
Server restarts (~1 second)
API ready

Frontend Hot Reload¶

Next.js Fast Refresh:

# docker-compose.yml
frontend:
  volumes:
    - ./frontend:/app
    - /app/node_modules  # Exclude node_modules
    - /app/.next         # Exclude build cache
  command: pnpm dev

Process:

Save React file
Next.js detects change
Browser updates (< 1 second)
Component state preserved

Testing Hot Reload¶

Backend Test¶

Open backend/app/main.py
Find the startup log line
Change it slightly:

logger.info(f"🚀 Starting {settings.PROJECT_NAME}")

Save file
Check logs: ./dev.sh logs backend

Frontend Test¶

Open http://localhost:3000
Edit frontend/src/app/page.tsx
Change visible text
Save file
Browser updates automatically

Troubleshooting¶

Hot Reload Not Working (Backend)¶

Check Uvicorn is in reload mode:

docker-compose logs backend | grep "reloader"
# Should see: "Started reloader process using WatchFiles"

Check volume mount:

docker-compose exec backend ls -la /app
# Should show your source files

Restart backend:

docker-compose restart backend

Hot Reload Not Working (Frontend)¶

Check dev mode:

docker-compose logs frontend | grep "Ready"
# Should see: "Ready in X.Xs"

Clear Next.js cache:

docker-compose exec frontend rm -rf .next
docker-compose restart frontend

Slow Hot Reload¶

Optimize file watching:

Add to .vscode/settings.json:

{
  "files.watcherExclude": {
    "**/.git/**": true,
    "**/node_modules/**": true,
    "**/.next/**": true,
    "**/__pycache__/**": true
  }
}

Check Docker resources:

docker stats
# Ensure containers have enough memory

Local Development (Without Docker)¶

Backend¶

cd backend
source .venv/bin/activate
uvicorn app.main:app --reload --port 8000

Frontend¶

cd frontend
pnpm dev

Both run with hot reload enabled by default.

Performance Optimization¶

Docker Volume Performance (macOS)¶

Use delegated volume mounts for better performance:

volumes:
  - ./backend:/app:delegated

Exclude Unnecessary Files¶

Create .dockerignore:

__pycache__
*.pyc
.git
node_modules
.next
*.log

Use Named Volumes for Dependencies¶

volumes:
  - ./backend:/app
  - backend_venv:/app/.venv  # Persist virtual environment