Files
stemengine_old/20260317_WebUI_Live_Reload_Plan.md
T

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
  • 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 .py files trigger auto-reload, available immediately
  • Workflow: Edit→Save→Test (no build needed)

Problem Analysis

Why Rebuild is Required Now

  1. No volume mount: Frontend source not mounted in stemengine-webui container
  2. Static serving: nginx serves pre-built dist folder (no watch/rebuild)
  3. Full Docker rebuild: Only way to pick up changes is docker compose up -d --build

Why Backend Works Without Rebuild

  1. Volume mount: ${SEFOLDER}/backend:/app/backend mounts source
  2. Auto-reload: uvicorn --reload watches source files
  3. Immediate effect: Changes detected, server restarts transparently

Solution Architecture

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:

  1. Mount frontend source: ${SEFOLDER}/frontend:/app/frontend
  2. Replace nginx with Vite dev server on port 5173
  3. 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:

  1. Mount frontend source
  2. Run vite build --watch in background
  3. nginx serves rebuilt dist folder

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 dev as 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.0 in 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 .tsx file 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:

  1. Comment out WEBUI_BUILD_MODE in .env
  2. Docker compose defaults to Dockerfile.webui (production)
  3. Rebuild: docker compose up -d --build stemengine-webui
  4. Back to static serving with rebuild required