learning_ai_common_plat/docs/devops/vercel/ROADMAP_EFFORISE.md

EffoRise Client — Vercel Deployment Roadmap

App: effo-rise-ai (Vite SPA) Repo: learning_ai_efforise → root vite.config.ts, client source in client/ Status: ⚠️ Partial — Vite SPA needs rewrites + API proxy strategy

---

Current State

• Framework: Vite 7.1.7, React 19.2.1, TailwindCSS v4, shadcn/ui
• Build: vite build → output at dist/public/
• Routing: wouter (client-side SPA routing)
• Dependencies: 8 @bytelyst/* — all via Gitea registry ✅ (no file: refs)
• API proxy: Dev server proxies /api → http://localhost:4020 (Fastify backend)
• No Next.js — this is a pure Vite SPA, not SSR

Gaps to Fix

Gap 1: Vercel Framework Configuration (~10 min)

Vercel supports Vite out of the box, but needs correct settings.

• Create vercel.json in repo root:

  {
    "buildCommand": "pnpm build",
    "outputDirectory": "dist/public",
    "framework": "vite",
    "rewrites": [
      { "source": "/api/(.*)", "destination": "https://YOUR_BACKEND_URL/api/$1" },
      { "source": "/(.*)", "destination": "/index.html" }
    ]
  }
  

Gap 2: API Proxy Strategy (~10 min)

The SPA proxies /api to the Fastify backend. On Vercel, options:

Options:

• A) Vercel Rewrites — proxy /api/* to the deployed backend URL (recommended)
• B) Direct API calls — configure VITE_API_URL env var, update API client to use absolute URLs
• C) Vercel Serverless Functions — not feasible (backend is Fastify, not Node serverless)

Recommended: Option A with Vercel rewrites, falling back to Option B.

• Choose proxy strategy
• Update vercel.json or API client accordingly
• Set VITE_BACKEND_URL env var for API base URL

Gap 3: SPA Client-Side Routing (~5 min)

wouter handles routing client-side. All routes must serve index.html.

• Add catch-all rewrite in vercel.json: { "source": "/(.*)", "destination": "/index.html" }

Gap 4: Registry Access (~5 min)

Once Gitea is deployed to the Azure VM with a public HTTPS URL, update .npmrc.

• Update .npmrc to Azure VM Gitea URL
• Set GITEA_NPM_TOKEN as a Vercel environment variable

Gap 5: Build Output Directory (~5 min)

Vite outputs to dist/public/ (custom, not default dist/). Vercel needs to know.

• Set Output Directory to dist/public in Vercel project settings or vercel.json

Deployment Steps

Step 1: Create vercel.json (~10 min)

Step 2: Fix registry access (~5 min)

Step 3: Create Vercel Project (~5 min)

• Connect learning_ai_efforise repo
• Framework preset: Vite
• Root directory: / (vite.config.ts is at root)
• Build command: pnpm build
• Output directory: dist/public

Step 4: Environment Variables (~5 min)

• VITE_BACKEND_URL — EffoRise backend endpoint (port 4020)
• (Client-side only — all VITE_* vars are embedded at build time)

Step 5: Verify (~10 min)

• Test SPA routing (navigate between pages, refresh deep links)
• Test API connectivity (identity CRUD, habit tracking)
• Verify shadcn/ui components render correctly

Step 6: Domain (~5 min)

• Add custom domain (e.g., app.efforise.app)

Risks

• API proxy reliability: Vercel rewrites to external backend add a hop. Latency depends on backend hosting location.
• Build-time env vars: Vite embeds VITE_* vars at build time. Changing backend URL requires a redeploy.
• No SSR: Pure SPA — no SEO benefits. Landing page should be separate or use meta tags.

Estimated Total Effort: ~40 minutes