Vercel Deployment

Vercel is recommended for development and staging environments. Deployments use Vercel's native Git integration (automatic on push).

Overview

Vercel provides:

• ✅ Automatic Git deployments (preview on PRs, production on main/develop)
• ✅ Preview deployments for PRs and branches
• ✅ Zero-config Next.js support
• ✅ Edge network (CDN)
• ✅ Serverless functions
• ✅ Environment variable management

Note: Vercel is great for convenience, but this project is designed to be portable. Other platforms (Google Cloud, AWS, etc.) can be used without code changes. See Portability Strategy for migration paths.

Setup

1. Connect Repository

1. Log in to Vercel
2. Click "Add New Project"
3. Import your GitHub repository
4. Vercel auto-detects Next.js configuration

2. Configure Environment Variables

Set environment variables in Vercel project settings:

For API (apps/fastify):

DATABASE_URL=postgresql://user:pass@host:5432/dbname
ENCRYPTION_KEY=<64-char-hex>
JWT_SECRET=<min-32-chars-not-dev-default>
OPEN_ROUTER_API_KEY=sk-...
RESEND_API_KEY=re_...
PORT=3001
NODE_ENV=production
SENTRY_DSN=https://...

For Web (apps/next):

NEXT_PUBLIC_API_URL=https://api.yourdomain.com
NEXT_PUBLIC_SENTRY_DSN=https://...

For Docs (apps/docu):

NEXT_PUBLIC_SITE_URL=https://docs.yourdomain.com

3. Deploy

Git deployments are enabled. Vercel automatically builds and deploys on push: preview environments for PRs and branches, production for main/develop. CI workflows (next-e2e, api-e2e, packages-test) run tests locally; they do not trigger deploys.

Deployment Configuration

vercel.json (Optional)

Monorepo apps use custom configs. Example for apps/next:

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "ignoreCommand": "npx turbo-ignore @repo/next --fallback=HEAD^1",
  "buildCommand": "cd ../.. && pnpm turbo run build --filter=@repo/next...",
  "installCommand": "cd ../.. && pnpm install",
  "framework": "nextjs",
  "outputDirectory": ".next"
}

Root Directory must be set in Vercel project settings (e.g. apps/next).

Environment-Specific Configuration

Development

• Preview deployments for every PR
• Uses staging environment variables
• Automatic URL generation

Production

• Deploys from main branch
• Uses production environment variables
• Custom domain configuration

Path-Based Deploys

Each app uses ignoreCommand in vercel.json (e.g. turbo-ignore @repo/next --fallback=HEAD^1) so Vercel skips builds when the app and its dependencies are unchanged. The build command uses --filter=@repo/<app>... to include dependencies. Vercel also has built-in skipping unaffected projects for monorepos; turbo-ignore provides explicit control when Vercel cannot compare against a previous deployment (e.g. new branches).

Branch Preview Coupling

Next's apps/next/next.config.mjs derives NEXT_PUBLIC_API_URL for preview branches as basilic-fastify-git-{branch}-*.vercel.app. Ensure Fastify and Next projects are connected to the same Git repo so both get preview deploys on PR branches.

Monorepo Configuration

For monorepo apps, Vercel needs to know the root directory:

1. Go to Vercel project settings
2. Set "Root Directory" to apps/next (or apps/docu, apps/fastify)
3. Vercel automatically detects package dependencies

Fork or different project names: Next's next.config.mjs uses API_PROJECT_NAME and TEAM_SLUG to compute preview API URLs. Update these constants to match your Fastify Vercel project name and team slug.

Custom Domains

1. Go to project settings → Domains
2. Add your custom domain
3. Configure DNS records (Vercel provides instructions)
4. Vercel handles SSL certificates automatically

E2E Testing

CI runs E2E against local servers only (no Vercel URLs). For manual E2E against preview deployments: set ALLOW_TEST=true for Preview env. When Deployment Protection is enabled, use VERCEL_AUTOMATION_BYPASS_SECRET and Protection Bypass for Automation. See E2E Testing.

Best Practices

1. Use preview deployments - Test changes before merging
2. Set environment variables - Don't commit secrets
3. Monitor builds - Check build logs for errors
4. Use production branch protection - Require PR reviews before merging to main

Migration to Other Platforms

This project is designed to be portable. When you need to move away from Vercel:

• Google Cloud Run - Enterprise security and compliance
• AWS ECS/EC2 - AWS ecosystem integration
• Self-hosted - Full control and customization

See Portability Strategy for detailed migration paths.

Troubleshooting

Build Fails

• Check build logs in Vercel dashboard
• Verify environment variables are set
• Ensure all dependencies are installed

Deployment Not Created

• Vercel auto-deploys from Git integration. Ensure projects are connected in Vercel dashboard.
• Check that relevant paths changed; ignoreCommand in vercel.json may skip deploys for unrelated changes.

Environment Variables Not Applied

• Redeploy after changing environment variables
• Check variable names match exactly (case-sensitive)
• Verify variables are set for the correct environment (production/preview)

"spawn pnpm ENOENT" or path ".../apps/docu/apps/docu" does not exist

• pnpm ENOENT: The workflow uses npx pnpm in vercel.json install/build commands so Vercel's build subprocess can find pnpm. Ensure corepack enable runs before deploy (already in workflows).
• Path duplication: Ensure Vercel project settings → General → Root Directory is . or blank for monorepo apps.

Related Documentation

• Deployment Overview - GitHub Flow and CI/CD pipelines
• Portability Strategy - Migration to Google Cloud, AWS, or self-hosted
• Installation - Environment variable configuration