Skip to content

OWTS Frontend (ESP32 Web UI)

This folder contains the OWTS web UI (Single Page App) that is built into the ESP32 firmware’s SPIFFS image and served by the device.

The UI talks to the device via relative API calls under /api/* (same origin on-device). For local development, Vite can proxy /api to a real device (see below).

Tech stack

  • React + TypeScript
  • Vite (dev server + build)
  • MUI (UI components + theming)
  • React Router (client-side routes)
  • TanStack Query (API fetch/caching/mutations)
  • i18next (DE/EN localization)

API reference (repo-relative)

  • OpenAPI spec: docs/assets/api/openapi.json (symlinked at src/api/schema/openapi.json)
  • Regenerate types with npm run generate:api after the spec changes
  • Firmware web server / routing / static file serving: main/web/

When in doubt about runtime behavior, the ESP32 firmware is the source of truth.

Output location (SPIFFS)

Production builds are written to main/frontend/ (repo root relative). The build is tuned to be ESP32/SPIFFS-friendly:

  • Stable filenames (no hashes): assets/main.js, assets/main.css
  • Pre-gzipped assets: during npm run build we gzip text assets and keep only *.gz versions to reduce transfer size and SPIFFS churn
  • Git LFS: committed main/frontend/**/*.gz files are LFS-tracked. Clones need Git LFS installed (git lfs install) so those assets hydrate correctly.

Local development against a device

Create a frontend/.env file and point it at a device:

VITE_API_HOST=http://10.10.1.247

Then run:

npm run dev

Vite will serve the UI locally and proxy /api/* to VITE_API_HOST.

Fresh checkout: install + build

From OWTS/frontend/:

npm install
npm run build

After npm run build, the device-serving files are in OWTS/main/frontend/.