learning_ai_common_plat/docs/devops/vercel/ROADMAP_ACTIONTRAIL_WEB.md

ActionTrail Web — Vercel Deployment Roadmap

App: @actiontrail/web Repo: learning_ai_trails → web/ Status: ⚠️ Partial — hardcoded standalone output

---

Current State

• Framework: Next.js 16.1.6, React 19.2.3
• Output: ❌ Hardcoded output: 'standalone'
• Styling: No TailwindCSS (minimal CSS)
• Dependencies: 7 @bytelyst/* — all via Gitea registry ✅ (no file: refs)
• Build: next build --webpack
• Client-side focused — timeline, approvals, agents, insights, traces, welcome, settings
• SSE support — real-time toast notifications via EventSource

Gaps to Fix

Gap 1: Make output Vercel-aware (~5 min)

File: web/next.config.ts

- output: 'standalone',
+ ...(process.env.VERCEL ? {} : { output: 'standalone' }),

• Update next.config.ts
• Verify Docker build still works

Gap 2: 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 3 (optional): SSE Compatibility

Vercel serverless functions have a 25-second timeout (Hobby) / 300s (Pro). SSE streams via GET /api/events/stream will be cut short.

• Consider using Vercel's Edge Runtime for SSE endpoints (longer timeout)
• Or switch to polling on Vercel, keep SSE for Docker/self-hosted

Deployment Steps

Step 1: Fix output mode (~5 min)

Step 2: Fix registry access (~5 min)

Step 3: Create Vercel Project (~5 min)

• Connect learning_ai_trails repo
• Set Root Directory to web
• Framework preset: Next.js

Step 4: Environment Variables (~5 min)

• NEXT_PUBLIC_BACKEND_URL — ActionTrail backend endpoint (port 4018)

Step 5: Verify (~10 min)

• Test timeline page with action list
• Test approval queue
• Test agent card grid
• Verify SSE toast notifications work (or gracefully degrade)

Step 6: Domain (~5 min)

• Add custom domain (e.g., app.actiontrail.dev)

Estimated Total Effort: ~35 minutes