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

Cloudflare Pages (local preview)

Production deploys go to Cloudflare Pages (Azure DevOps → pipelines/azure-pipelines.yml). To approximate the Pages runtime locally:

cp .dev.vars.example .dev.vars   # set API_BACKEND_URL to your backend origin
npm run build
npx wrangler pages dev ./dist

VITE_* variables are inlined at npm run build time — set them in .env / CI before building, not in .dev.vars (.dev.vars is for the Pages Functions proxy: API_BACKEND_URL).

See Frontend/docs/cloudflare-pages-deploy.md in the monorepo for Entra redirect URIs and smoke tests.

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.