6.5 KiB
6.5 KiB
WebUI Live Reload Implementation — Summary
Date: 2026-03-17
Status: ✅ Implemented
Impact: Frontend development cycle reduced from 35-70 seconds to 3-5 seconds
What Changed
1. New Dev Dockerfile
File: frontend/Dockerfile.webui.dev
- Lightweight Alpine image with Node 20
- Runs
npm run dev→ Vite dev server on all interfaces - Source code mounted from host (no rebuild needed on changes)
2. Updated package.json
File: frontend/package.json
- Changed:
"dev": "vite"→"dev": "vite --host 0.0.0.0" - Now listens on all interfaces for Docker port mapping
3. Updated Docker Compose
File: stemengine.yml
- Added frontend source volume mount:
volumes: - ${SEFOLDER}/frontend:/app/frontend - Switched to dev Dockerfile by default:
dockerfile: ${WEBUI_DOCKERFILE:-Dockerfile.webui.dev} - Updated traefik port from 80 to
${WEBUI_PORT:-5173}
4. Environment Configuration
File: .env
- Added
WEBUI_DOCKERFILE=Dockerfile.webui.dev(enables live reload) - Added
WEBUI_PORT=5173(Vite dev server port)
How to Use
Start with Live Reload (Recommended for Development)
cd /home/translator/docker
docker compose up -d --build stemengine-webui
What happens:
- Container builds with dev Dockerfile
- Vite dev server starts on port 5173
- Frontend source is mounted from host
- Changes to
.tsx/.tsfiles trigger instant HMR
Switch to Production Build
Edit .env:
WEBUI_DOCKERFILE=Dockerfile.webui
Then rebuild:
docker compose up -d --build stemengine-webui
Developer Workflow
Edit → Test Cycle
Before (Old Workflow)
1. Edit src/components/MyComponent.tsx
2. Run: docker compose up -d --build stemengine-webui
3. Wait 30-60 seconds for rebuild
4. Hard refresh browser
5. See changes
Total: 35-70 seconds ⏱️
After (New Workflow)
1. Edit src/components/MyComponent.tsx
2. Save file
3. Browser auto-reloads (HMR) within 2-3 seconds
4. See changes immediately
Total: 3-5 seconds ⏱️
HMR Behavior
| Change Type | Behavior |
|---|---|
| CSS import | Instant style update (no reload) |
| Component JSX | Page auto-reload, state preserved where possible |
| TypeScript errors | Shows in browser console + terminal |
| Import path changes | Full reload (module graph changed) |
Technical Details
Why This Works
Vite Dev Server:
- Serves modules as-is (unbundled ES modules)
- File watchers trigger rebuilds automatically
- HMR protocol pushes changes to browser without full reload
Volume Mount:
${SEFOLDER}/frontend:/app/frontendexposes host source to container- Vite's chokidar watches mounted files for changes
- No Docker rebuild needed
CORS Already Configured:
- Backend CORS settings already include
localhost:5173 - Dev server can call
/api/*endpoints on backend without modification
Fallback to Production Build
If issues occur, switch back to production:
WEBUI_DOCKERFILE=Dockerfile.webui
This uses the original two-stage build (static nginx serving), which is proven stable.
Testing Checklist
- Rebuild:
docker compose up -d --build stemengine-webui - Check logs:
docker logs stemengine-webui(should show Vite startup) - Access http://localhost:5173 (should load frontend)
- Edit a .tsx file in
frontend/src/ - Save and watch browser update within 2-3 seconds
- Open browser console (F12) for any TypeScript/runtime errors
- Verify
/api/*calls still work (backend communication)
Files Modified
| File | Change | Impact |
|---|---|---|
frontend/Dockerfile.webui.dev |
NEW | Dev-mode image with Vite server |
frontend/package.json |
Line 7 | Added --host 0.0.0.0 to dev script |
stemengine.yml |
Lines 115-142 | Added volume mount, switched Dockerfile, updated port config |
.env |
Lines 30-32 | Added WEBUI_DOCKERFILE, WEBUI_PORT settings |
Known Limitations
Page Reloads vs True HMR
- CSS-only changes: Instant (true HMR, no reload)
- Component logic changes: Page reloads (preserves component state where possible)
- This is standard Vite behavior, same as
npm run devlocally
No TypeScript Compilation Step
- Browser shows runtime errors directly (standard for dev mode)
- Run
npm run typecheckin terminal for ahead-of-time checking - CI/CD still validates TypeScript before production builds
VITE_STEMENGINE_API_BASE
- Build-time variable from
.env/ docker-compose args - To change backend URL at runtime: Use Settings → Integrations (UI override)
- Dev builds use
${VITE_STEMENGINE_API_BASE:-http://localhost:8000}from env
Troubleshooting
"Port 5173 already in use"
# Find process using port 5173
lsof -i :5173
# Kill it (if not needed)
kill -9 <PID>
# Or change WEBUI_PORT in .env to something else
Changes not showing up
# Check Vite is running
docker logs stemengine-webui
# Look for "[vite] hmr update received"
# Try hard refresh: Ctrl+Shift+R (or Cmd+Shift+R on Mac)
Backend API calls failing
# Verify backend is running on port 8000
docker logs stemengine
# Check CORS settings in .env cover your access URL
# Edit CORS_ORIGINS or CORS_ORIGIN_REGEX if needed
TypeScript errors not showing
# Open browser DevTools console (F12)
# Check for syntax errors
# Run type check locally:
cd frontend
npm run typecheck
Rollback Plan
If live reload causes issues, immediately switch to production:
# Edit .env
WEBUI_DOCKERFILE=Dockerfile.webui
# Rebuild static version
cd /home/translator/docker
docker compose up -d --build stemengine-webui
This reverts to the original static Dockerfile (nginx + pre-built dist), which requires docker compose up -d --build for changes but is stable and production-ready.
Next Steps
- ✅ Test live reload workflow:
docker compose up -d --build stemengine-webui - ✅ Edit a
.tsxfile and verify instant HMR - ✅ Check browser console for any runtime errors
- ✅ Verify API calls to backend still work
- Optional: Document custom dev setup (e.g., local Vite + tunneling to backend)
References
- Vite Docs: https://vitejs.dev/guide/
- HMR Configuration: https://vitejs.dev/guide/features.html#hot-module-reload
- Docker Compose: https://docs.docker.com/compose/
- Previous Plan: 20260317_WebUI_Live_Reload_Plan.md