5.8 KiB
5.8 KiB
WebUI Live Reload Implementation Plan
Date: 2026-03-17
Issue: Frontend changes require full Docker rebuild/restart to take effect
Goal: Enable hot-reload development workflow—changes to .tsx/.ts files immediately visible in browser
Current Architecture
Production Setup
- Dockerfile.webui: Two-stage build
- Stage 1 (
node:20-alpine): Builds Vite dist folder - Stage 2 (
nginx:1.27-alpine): Serves static dist via nginx
- Stage 1 (
- Result: Static bundle, zero hot-reload capability
- Use case: Production deployments where rebuild is acceptable
Development Setup (Backend Reference)
- backend: Mounted from host via
${SEFOLDER}/backend:/app/backend - Uvicorn reload:
python3.11 -m uvicorn backend.main:app --reload - Result: Changes to
.pyfiles trigger auto-reload, available immediately - Workflow: Edit→Save→Test (no build needed)
Problem Analysis
Why Rebuild is Required Now
- No volume mount: Frontend source not mounted in stemengine-webui container
- Static serving: nginx serves pre-built dist folder (no watch/rebuild)
- Full Docker rebuild: Only way to pick up changes is
docker compose up -d --build
Why Backend Works Without Rebuild
- Volume mount:
${SEFOLDER}/backend:/app/backendmounts source - Auto-reload: uvicorn
--reloadwatches source files - Immediate effect: Changes detected, server restarts transparently
Solution Architecture
Option A: Vite Dev Server (Recommended)
Pros:
- HMR (hot module reload) out-of-box
- Handles TypeScript/JSX transformation on-the-fly
- Matches local development workflow exactly
- Zero build steps needed
Cons:
- Separate service running (not just nginx)
- Slightly slower than production build (no tree-shaking/minification)
Implementation:
- Mount frontend source:
${SEFOLDER}/frontend:/app/frontend - Replace nginx with Vite dev server on port 5173
- Watch mode enabled by default (chokidar polling for WSL2 compat)
Option B: Vite Watch + Nginx (Hybrid)
Pros:
- Uses nginx (production-like environment)
- Still watches/rebuilds on changes
Cons:
- No HMR (full page refresh needed)
- More complex to coordinate two processes
- Slower feedback loop than dev server
Implementation:
- Mount frontend source
- Run
vite build --watchin background - nginx serves rebuilt dist folder
Recommended Implementation: Option A (Vite Dev Server)
Changes Required
1. Update stemengine.yml
Add volume mount for frontend source:
stemengine-webui:
volumes:
- ${SEFOLDER}/frontend:/app/frontend
2. Create Dockerfile.webui.dev
Lightweight dev-mode image:
FROM node:20-alpine
WORKDIR /app
# Install dependencies once
COPY package*.json ./
RUN npm ci
# Mount source from host (volume)
# Source copied in compose file
EXPOSE 5173
CMD ["npm", "run", "dev"]
3. Update package.json
Ensure dev script targets Vite dev server:
{
"scripts": {
"dev": "vite --host 0.0.0.0",
"build": "vite build",
"preview": "vite preview"
}
}
4. Update stemengine.yml Build Config
Switch to dev Dockerfile when in development:
stemengine-webui:
build:
context: ${SEFOLDER}/frontend
dockerfile: Dockerfile.webui.dev # Dev mode
# OR: dockerfile: Dockerfile.webui # Production mode
5. Environment Variable to Control Mode
Add to .env:
# Use 'Dockerfile.webui' for production, 'Dockerfile.webui.dev' for development
WEBUI_BUILD_MODE=dev
Then in compose:
dockerfile: Dockerfile.webui${WEBUI_BUILD_MODE:+.dev}
Workflow Comparison
Current (Production)
Edit TSX file
↓
docker compose up -d --build stemengine-webui (30-60 sec)
↓
Browser refresh (5-10 sec)
↓
See changes (35-70 sec total)
New (Development)
Edit TSX file
↓
Auto-rebuild on save (2-3 sec)
↓
Browser auto-reload (HMR) (1-2 sec)
↓
See changes (3-5 sec total)
Implementation Steps
Phase 1: Create Dev Dockerfile
- Create
Dockerfile.webui.dev - Set
npm run devas entrypoint
Phase 2: Update Docker Compose
- Add frontend volume mount
- Add dockerfile selection logic
- Add WEBUI_BUILD_MODE to .env
Phase 3: Verify Package.json
- Confirm
vite --host 0.0.0.0in dev script - Confirm dependencies include vite, react, typescript
Phase 4: Testing
- Build and run:
docker compose up -d --build stemengine-webui - Verify container started:
docker logs stemengine-webui - Access http://localhost:5173 in browser
- Edit a
.tsxfile and save - Verify instant HMR/auto-reload (no browser refresh needed)
Fallback: Keep Both Modes
Users can keep both Dockerfiles:
Dockerfile.webui→ Production (static dist)Dockerfile.webui.dev→ Development (Vite dev server)
Set WEBUI_BUILD_MODE in .env:
# Uncomment one:
# WEBUI_BUILD_MODE=dev # Development (instant HMR)
WEBUI_BUILD_MODE=prod # Production (built dist)
Compatibility Notes
WSL2 + Docker
- Vite polling configured via
npm run dev(auto-detects) - No special setup needed—just works
Hot Module Reload Limitations
- CSS changes: Instant (no page reload)
- Component logic changes: Page auto-reload (preserves state where possible)
- Import changes: Full reload (module graph changes)
CORS & API Calls
- Backend on port 8000
- WebUI dev server on port 5173
- CORS env vars already configured in stemengine.yml (covers localhost:5173)
Rollback Plan
If Vite dev server causes issues:
- Comment out
WEBUI_BUILD_MODEin.env - Docker compose defaults to
Dockerfile.webui(production) - Rebuild:
docker compose up -d --build stemengine-webui - Back to static serving with rebuild required