Local Development — Cloud Frontend

Prerequisites

• Node.js 20+
• npm
• Cloud Backend running locally (see Cloud Backend Local Dev)

Setup

cd Frontend
cp .env.example .env
npm install

Environment variables

All variables are documented in Frontend/.env.example.

Variable	Default	Notes
VITE_API_URL	http://localhost:8000	Cloud Backend API origin — no trailing slash, no /api/v1 path
VITE_WS_URL	ws://localhost:8000/api/ws	WebSocket base URL
VITE_ADMIN_PANEL_ENABLED	off	Set to true to show admin routes
VITE_PLATFORM_ADMIN_EMAIL_DOMAIN	monozu.io	Email domain for admin access
VITE_CLARITY_PROJECT_ID	off	Microsoft Clarity (leave unset locally)

Start dev server

npm run dev
# SPA available at http://localhost:3000

The Vite dev server proxies API requests to the backend based on VITE_API_URL. No manual proxy config needed — the Axios client in lib/config/api.ts uses VITE_API_URL as the base URL.

Build for production

npm run build
# Output in dist/
npm run preview  # Preview production build locally

Lint

npm run lint

Cross-origin cookie setup (local dev)

When the SPA runs at http://localhost:3000 and the API at http://localhost:8000, they are on different ports but the same hostname (localhost). For cookie purposes, this is typically treated as same-site.

If you run into issues with the refresh cookie not being sent:

1. Keep REFRESH_COOKIE_SAMESITE=strict (default) on the backend
2. Ensure ALLOW_ORIGINS=http://localhost:3000,http://127.0.0.1:3000 is set on the backend
3. Do not set VITE_WS_URL to use a different host

Docker (nginx)

The Frontend Dockerfile builds the SPA and serves it with nginx on port 8080:

docker build -t monozu-frontend .
docker run -p 8080:8080 \
  --build-arg VITE_API_URL=https://api.cloud.monozu.io \
  monozu-frontend

Note: Vite env vars are baked into the build at npm run build time. Pass them as --build-arg in Docker, not as runtime environment variables.

TypeScript

npx tsc --noEmit  # Type check without building

Type errors in one module won’t prevent other modules from running during dev, but all types must pass for the production build.