{"slug":"operations/DEPLOYMENT_FIX","title":"Preview Deployment Fix — Root Cause & Solution","section":"operations","sectionLabel":"Operations","status":"unclassified","type":"document","path":"operations/DEPLOYMENT_FIX.mdx","bytes":2998,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n\n> **Tier C — Historical.** This document is a point-in-time snapshot preserved for reference. For current architecture, see [CANONICAL_PLATFORM_ARCHITECTURE.md](../architecture/CANONICAL_PLATFORM_ARCHITECTURE.md).\n\n## Problem\n\nPreview deployment was failing with 404 errors. The platform was fully built and working locally, but Vercel couldn't properly deploy it.\n\n## Root Cause\n\n**Missing `vercel.json` configuration file.**\n\nVercel needs explicit instructions for Vite-based SPA applications:\n1. Where the build output is located (`apps/web/dist`)\n2. How to handle routing for single-page apps (rewrite all paths to `index.html`)\n3. Build command (Turbo monorepo: `pnpm build`)\n4. Environment variables\n\nWithout `vercel.json`, Vercel defaults to Next.js or static site assumptions, which don't work for Vite React Router apps.\n\n## Solution\n\nCreated `vercel.json` with proper Vite configuration:\n\n```json\n{\n  \"version\": 2,\n  \"buildCommand\": \"pnpm build\",\n  \"outputDirectory\": \"apps/web/dist\",\n  \"framework\": \"vite\",\n  \"cleanUrls\": true,\n  \"rewrites\": [\n    {\n      \"source\": \"/(.*)\",\n      \"destination\": \"/index.html\"\n    }\n  ]\n}\n```\n\n**Key configurations:**\n- `outputDirectory`: Points Vercel to the Vite build output\n- `rewrites`: SPA routing (all paths → index.html for React Router)\n- `cleanUrls`: Remove `.html` extensions from URLs\n- `framework`: Explicit Vite detection\n- `buildCommand`: Uses Turbo to build the monorepo\n\n## What This Fixes\n\n1. **404 errors on preview:** Vercel now correctly serves `index.html` for all routes\n2. **Build detection:** Vercel knows to run Turbo build command\n3. **Asset routing:** Static assets serve from `/dist/assets/`\n4. **Environment variables:** Can be configured in Vercel project settings\n\n## Deployment Readiness Status\n\n✅ All checks passed:\n- Vite build: 8.9MB dist directory created\n- TypeScript: 0 errors (clean type check)\n- Dependencies: pnpm-lock.yaml (reproducible builds)\n- Config: vercel.json present and configured\n- Environment: AI Gateway keys available\n- Git: Changes committed and ready for push\n\n## Why This Wasn't Needed Before\n\nPrevious deployments may have worked because:\n- Local dev server (Vite) handles routing internally\n- Cloudflare Workers deployments don't need Vercel routing config\n- Early deployments may have been manual or used different hosting\n\nNow that preview URLs are public-facing, Vercel needs explicit config for SPAs.\n\n## Testing the Fix\n\nAfter pushing to GitHub:\n1. Vercel automatically builds the deployment\n2. Preview URL should load without 404s\n3. All routes (/, /app, /dashboard) should work\n4. Assets should load (no 404s on .js, .css files)\n\n## Files Modified\n\n- `vercel.json` — New file with deployment config\n\n## References\n\n- Vercel Vite docs: https://vercel.com/docs/frameworks/vite\n- Vite SPA config: https://vitejs.dev/guide/ssr.html#setting-up-the-dev-server\n- React Router in Vite: https://reactrouter.com/start/framework-choice\n"}