spa/.planning/phase-1-foundation/03-vite-dev-proxy.md

Task 1.3 — Vite dev proxy + path aliases + tsconfig hardening

Phase: 1 — Foundation Status: ⬜ Not started Depends on: 1.2 Wiki refs: docs/wiki/entities/react-spa.md §Auth pattern

Goal

Configure Vite's dev server to proxy /api, /ws-business, /ws-live, and /config.json to the appropriate local services so the SPA dev experience matches the stage/prod reverse-proxy topology. Same-origin in dev means cookies flow correctly, identical to stage/prod where Traefik does the routing. Also: add path aliases (@/) so imports stay short, and tighten tsconfig.json for stricter type safety.

After this task, pnpm dev against a locally-running Directus + (eventually) Processor lets the SPA exercise the real auth flow without CORS workarounds.

Deliverables

• vite.config.ts updated:
  • server.proxy configured for:
    • /api → http://localhost:8055 (Directus REST/GraphQL).
    • /ws-business → ws://localhost:8055/websocket (Directus business-plane WS), with ws: true and rewrite to strip /ws-business.
    • /ws-live → ws://localhost:8081 (Processor live WS, once Phase 1.5 lands), with ws: true and rewrite to strip /ws-live.
    • Don't proxy /config.json — it's served from public/ by Vite directly in dev.
  • resolve.alias for @/ → src/.
  • server.port pinned to 5173 (Vite default; mention in README so anyone running other Vite apps avoids the conflict).
• tsconfig.app.json updated:
  • compilerOptions.baseUrl to ., paths to { "@/*": ["src/*"] }.
  • Add noUncheckedIndexedAccess: true (matches tcp-ingestion / processor strictness).
  • Add noImplicitOverride: true.
  • verbatimModuleSyntax: true is fine if already on; otherwise leave for now.
• README.md updated: a "local dev" section listing the assumed local services + how to override the proxy targets via env vars (next bullet).
• Optional: env-var override for proxy targets:
  • VITE_DEV_DIRECTUS_URL (default http://localhost:8055).
  • VITE_DEV_PROCESSOR_WS_URL (default ws://localhost:8081).
  • Read in vite.config.ts via loadEnv.
  • Document in .env.dev.example (committed) and .env.dev.local (gitignored).

Specification

Why proxy in dev instead of CORS

CORS-with-credentials requires:

1. The browser sending withCredentials: true on every request.
2. The server responding with Access-Control-Allow-Origin: <exact-origin> (not *) and Access-Control-Allow-Credentials: true.
3. Cookies being scoped correctly (SameSite=None; Secure for cross-site — which means HTTPS even in dev).

This works but it's three places that must agree, and SameSite=None; Secure requires localhost-with-TLS in dev (extra setup). The dev proxy collapses all of it into "everything is one origin," matching stage/prod's reverse-proxy topology. Pick the dev proxy.

Proxy config shape

// vite.config.ts
import { defineConfig, loadEnv } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';
import path from 'node:path';

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), 'VITE_');
  const directusUrl = env.VITE_DEV_DIRECTUS_URL ?? 'http://localhost:8055';
  const processorWsUrl = env.VITE_DEV_PROCESSOR_WS_URL ?? 'ws://localhost:8081';

  return {
    plugins: [react(), tailwindcss()],
    resolve: {
      alias: { '@': path.resolve(__dirname, './src') },
    },
    server: {
      port: 5173,
      proxy: {
        '/api': {
          target: directusUrl,
          changeOrigin: true,
          rewrite: (p) => p.replace(/^\/api/, ''),
        },
        '/ws-business': {
          target: directusUrl,
          ws: true,
          changeOrigin: true,
          rewrite: (p) => p.replace(/^\/ws-business/, '/websocket'),
        },
        '/ws-live': {
          target: processorWsUrl,
          ws: true,
          changeOrigin: true,
          rewrite: (p) => p.replace(/^\/ws-live/, ''),
        },
      },
    },
  };
});

The path namespacing (/api, /ws-business, /ws-live) is what the SPA code calls. The proxy strips the namespace and forwards. Stage/prod's Traefik does the same routing under the public domain — same paths, same code, no env branching in the SPA.

Path alias

@/ is the convention shadcn/ui assumes (its components.json config wires @/components/..., @/lib/utils). Aligning Vite + tsconfig with it means imports look like:

import { Button } from '@/ui/primitives/button';
import { useAuthStore } from '@/auth/store';

instead of ../../../ui/primitives/button. Don't add other top-level aliases — @/ for src/ is enough.

Why noUncheckedIndexedAccess

Without it, arr[0] is typed as T even when the array might be empty. With it, arr[0] is typed T | undefined, forcing a check. Catches a real class of bugs in map-position code (where "first device" assumptions are easy to make and easy to get wrong when the array is empty during reconnect).

The processor and tcp-ingestion both have this on. Match.

Vite proxy and WebSocket behaviour

The ws: true flag on the proxy entry tells Vite (which uses http-proxy-middleware) to forward the upgrade request. Cookies attached to the upgrade carry through transparently — that's the whole point of running same-origin in dev.

One gotcha: the proxy's target for a WS route must use a ws:// or wss:// scheme, not http://. If you accidentally use http://, the upgrade fails silently and the SPA gets a connection error. Document in the README.

Acceptance criteria

• pnpm dev starts at http://localhost:5173; the SPA loads.
• With Directus running locally on :8055, fetch('/api/server/info') from the browser console returns Directus's server info — proxy is forwarding.
• WebSocket smoke test: new WebSocket('ws://localhost:5173/ws-business') connects (returns code 1006 if Directus's WS endpoint is locked down without auth, but the upgrade itself succeeds — that's the test).
• import { foo } from '@/auth/foo' resolves both at type-check time and at runtime.
• pnpm typecheck is stricter — adding arr[0].whatever without a check should now fail.
• No CORS errors in the browser console when calling /api/... from http://localhost:5173.

Risks / open questions

• Directus's WS path is /websocket, not /ws. Confirmed by reading Directus 11.x source. The proxy rewrite rule reflects this.
• Processor WS path is unsettled. processor-ws-contract uses /processor/ws as illustrative; the actual path will be set by the proxy config in stage/prod (trm/deploy). For dev we assume the Processor binds to :8081 with no path prefix, and the proxy adds the /ws-live prefix on the SPA side. Reconcile if Phase 1.5 lands with a different path convention.
• Multiple Vite apps on one machine. Pinning to :5173 collides if another Vite app is running. Document the override (VITE_PORT=5174 pnpm dev works as a one-off; permanent change needs the config edit).

Done

(Filled in when the task lands.)