Dev Environment Patterns

Development Environment Patterns

Institutional knowledge for local dev-server networking, learned from real forge-ui debugging. All code here mirrors the live config in forge-ui/vite.config.ts and forge-ui/src/services/api-client.ts (ports: UI 5050 → proxies to API/WS 5051).

---

Pattern: Multi-Device Development Access

Severity: Critical (blocks all functionality from non-localhost devices).

Symptom

API/WS calls fail only when accessed from a phone, tablet, or another PC:

• Cross-Origin Request Blocked: localhost:5051
• NetworkError when attempting to fetch resource
• WebSocket connection failures

Root cause

localhost on the remote device points at that device, not the dev server. Any URL that names localhost (hardcoded or via VITE_API_URL) is unreachable off-machine. The fix is relative URLs proxied by Vite, so the browser only ever talks same-origin to whatever host it loaded the page from.

Correct pattern (matches live source)

// src/services/api-client.ts — env var wins, else relative /api in dev
const getApiBaseUrl = () => {
  if (import.meta.env.VITE_API_URL) return import.meta.env.VITE_API_URL; // prod only
  if (import.meta.env.DEV) return "/api";                                // Vite proxies this
  const host = typeof window !== "undefined" ? window.location.hostname : "localhost";
  return `http://${host}:5051/api`;                                       // prod fallback
};

// vite.config.ts — bind all interfaces + proxy /api, /ws, /terminal to 5051
server: {
  host: "0.0.0.0",     // accept connections from any device
  port: 5050,
  strictPort: true,    // FAIL if taken — does NOT auto-increment
  proxy: {
    "/api":      { target: "http://localhost:5051", changeOrigin: true },
    "/ws":       { target: "ws://localhost:5051", ws: true, changeOrigin: true },
    "/terminal": { target: "ws://localhost:5051", ws: true },
  },
}

# .env — never hardcode localhost. Leave VITE_API_URL UNSET in dev.
# VITE_API_URL=http://localhost:5051/api   # WRONG — breaks every non-local device