Deployment Guide

Vercel Deployment Configuration

Working Configuration

The following vercel.json configuration successfully deploys the homepage-dev monorepo to Vercel:

{
  "buildCommand": "turbo build --filter=web",
  "outputDirectory": ".next",
  "installCommand": "pnpm install --frozen-lockfile"
}

Key Configuration Details

• buildCommand: turbo build --filter=web

  • Uses Turborepo to build only the web app and its dependencies
  • Runs from the repository root directory
  • Automatically handles workspace dependencies

• outputDirectory: .next

  • Must be relative to the app directory context
  • CRITICAL: Do NOT use apps/homepage-web/.next as this causes path duplication
  • Vercel already operates in the correct app context

• installCommand: pnpm install --frozen-lockfile

  • Uses pnpm (the project's package manager)
  • --frozen-lockfile ensures reproducible builds

Troubleshooting Notes

Common Issues and Solutions

1. Path Duplication Error:

   • Error: The file '/vercel/path0/apps/homepage-web/apps/homepage-web/.next/routes-manifest.json' couldn't be found
   • Cause: Using "outputDirectory": "apps/homepage-web/.next"
   • Solution: Use "outputDirectory": ".next"

2. Build Directory Not Found:

   • Error: cd: apps/homepage-web: No such file or directory
   • Cause: Incorrect buildCommand or project structure assumptions
   • Solution: Use turbo build --filter=web from repository root

3. Dependencies Not Found:

   • Error: Various module resolution errors
   • Cause: Not using correct package manager or missing lockfile
   • Solution: Use pnpm install --frozen-lockfile

Environment Requirements

• Node.js: >=20
• Package Manager: pnpm
• Build System: Turborepo
• Framework: Next.js 15.4.1

Deployment Process

1. Code is pushed to the main branch
2. Vercel automatically detects the push
3. Runs pnpm install --frozen-lockfile to install dependencies
4. Executes turbo build --filter=web to build the app
5. Looks for build output in .next directory
6. Deploys the built application

Success Indicators

A successful deployment will show:

• ✅ Dependencies installed successfully
• ✅ Turborepo build completes for web app
• ✅ Next.js compilation successful
• ✅ All static pages generated
• ✅ routes-manifest.json found and processed
• ✅ Deployment URL generated

Historical Context

This configuration was refined through multiple iterations:

• Initially failed with various buildCommand approaches
• Path duplication issue was the final blocker
• Working configuration established January 2025