Vercel Configuration for HG Content Monorepo¶

Overview¶

The HG Content system uses Vercel for hosting with auto-deploys from GitHub. Each Vercel project is configured with a specific Root Directory to build from the correct app folder in the monorepo.

Project Configurations¶

1. hg-content (Main Application)¶

Domain: hgcontent.com

Vercel Dashboard Settings: - Root Directory: apps/frontend - Framework Preset: Next.js (auto-detected) - Install Command: pnpm install --no-frozen-lockfile - Build Command: (leave blank for auto) - Output Directory: .next (auto by framework) - Node.js Version: 20.x (stable with Next 14)

Toggles: - ✅ Include files outside the root directory in the Build Step - ✅ Skip deployments when there are no changes to the root directory or its dependencies

Environment Variables: - NEXT_PUBLIC_SUPABASE_URL - NEXT_PUBLIC_SUPABASE_ANON_KEY - Additional Supabase vars as needed

2. hg-content-docs (Internal Documentation)¶

Domain: dev.hgcontent.com

Vercel Dashboard Settings: - Root Directory: apps/internal-docs - Framework Preset: Next.js (auto-detected)
- Install Command: pnpm install --no-frozen-lockfile - Build Command: (leave blank for auto) - Output Directory: .next (auto by framework) - Node.js Version: 20.x

Toggles: - ✅ Include files outside the root directory in the Build Step - ✅ Skip deployments when there are no changes to the root directory or its dependencies

Environment Variables: - NEXT_PUBLIC_SUPABASE_URL - NEXT_PUBLIC_SUPABASE_ANON_KEY

3. Public Documentation (NOT on Vercel)¶

Domain: docs.hgcontent.com

The public documentation continues to deploy via: - GitHub Actions → MkDocs → GitHub Pages - Uses mike for versioning - Do NOT create a Vercel project for public docs

Why This Configuration Works¶

Root Directory Solution¶

Vercel builds each project from the correct app folder
Next.js is properly detected from each app's package.json
Eliminates "No Next.js version detected" errors
Prevents 404 NOT_FOUND errors from incorrect output paths

Monorepo Benefits¶

pnpm used consistently across all builds
Avoids npm peer dependency conflicts
Workspace dependencies properly resolved
Build optimization through selective changes

Auto-Deploy Reliability¶

GitHub pushes trigger automatic deployments
No manual scripts required
Root Directory configuration ensures consistent builds
Change detection prevents unnecessary deployments

Authentication & Redirects¶

Both applications implement cookie synchronization for proper auth redirects:

dev.hgcontent.com (Internal Docs)¶

Sign-in page subscribes to onAuthStateChange
POSTs session to /api/auth/[...supabase] for server-side cookies
Uses router.replace for seamless redirects

hgcontent.com (Frontend)¶

Added /api/auth/set/route.ts using createRouteHandlerClient
AuthContext POSTs to /api/auth/set on auth state changes
Middleware can read auth state from cookies

Optional Optimizations¶

Ignored Build Step (Skip Unrelated Changes)¶

Add to Vercel project settings under "Ignored Build Step":

Frontend (hg-content):

if git diff --quiet $VERCEL_GIT_PREVIOUS_SHA $VERCEL_GIT_COMMIT_SHA -- apps/frontend packages; then echo 'skip'; exit 0; else echo 'build'; exit 1; fi

Internal Docs (hg-content-docs):

if git diff --quiet $VERCEL_GIT_PREVIOUS_SHA $VERCEL_GIT_COMMIT_SHA -- apps/internal-docs internal mkdocs-internal.yml; then echo 'skip'; exit 0; else echo 'build'; exit 1; fi

Common Pitfalls to Avoid¶

❌ Don't build from repo root - Always use Root Directory
❌ Don't add root vercel.json - Avoid framework/output overrides
❌ Don't use Node 22.x - Stick with 20.x for Next 14 stability
❌ Don't create Vercel project for public docs - Use GitHub Pages

Deployment Workflow¶

Development: Work in feature branches
Testing: Deploy to staging branches if needed
Production: Push to main branch
Auto-Deploy: Vercel automatically builds and deploys
Verification: Check both domains for proper function

Legacy Scripts¶

The deployment scripts (deploy-frontend.sh, deploy-internal-docs.sh) are now deprecated and will warn users to use GitHub auto-deploys instead. They remain for reference but should not be used for production deployments.