Basilic
Deployment

Vercel Deployment

Deploy Next.js apps to Vercel for rapid iteration with preview environments.

Vercel is recommended for development and staging. Git integration deploys automatically: preview on PRs, production on main/develop. Zero-config Next.js, edge CDN, serverless functions, env vars in the dashboard. The app is portable — see Portability.

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/api):

DATABASE_URL=postgresql://user:pass@host:5432/dbname
ENCRYPTION_KEY=<64-char-hex>
JWT_SECRET=<min-32-chars-not-dev-default>
# AI: Anthropic direct API (preferred). See [AI Architecture](/docs/architecture/ai).
ANTHROPIC_API_KEY=sk-ant-...
# OPEN_ROUTER_API_KEY=sk-or-...
# OLLAMA_BASE_URL=https://ollama.yourdomain.com
RESEND_API_KEY=re_...
PORT=3001
NODE_ENV=production
SENTRY_DSN=https://...
# Optional: OAuth — see [Authentication](/docs/architecture/authentication) for GITHUB_*, GOOGLE_*, OAUTH_*_CALLBACK_URL(S).

Scope DATABASE_URL per Vercel environment. Production and Preview must not share a URL. Preview builds skip db:migrate unless RUN_PG_MIGRATE=true (use that only with an isolated Preview database).

For Web (apps/web):

NEXT_PUBLIC_API_URL=https://api.yourdomain.com
NEXT_PUBLIC_APP_URL=https://app.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 (web-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/web:

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

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

API (apps/api) compiles via turbo run build, then Vercel’s Fastify bundler type-checks server.ts. Do not set functions on server.ts — that key only matches files under api/. Keep colocated *.spec.ts / *.test.ts out of the upload with apps/api/.vercelignore. Then db:migrate runs only when VERCEL_ENV is not preview (or when RUN_PG_MIGRATE=true):

{
  "buildCommand": "cd ../.. && pnpm turbo run build --filter=@repo/api... && if [ \"$VERCEL_ENV\" != \"preview\" ] || [ \"$RUN_PG_MIGRATE\" = \"true\" ]; then pnpm turbo run db:migrate --filter=@repo/api; fi"
}

Production migrations run against that environment's Postgres and take a PostgreSQL advisory lock so concurrent deploys serialize. They no-op under PGLITE or NODE_ENV=test (CI E2E). Preview defaults to skip so a shared Production DATABASE_URL cannot be migrated from a PR build.

Turbo remote cache

Optional: set TURBO_TOKEN and TURBO_TEAM in Vercel project environment variables (same token as GitHub Actions) for cross-deploy cache hits. Per-package build.env in turbo.json must list only output-affecting vars. See Development Tooling.

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/web --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/web/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/web (or apps/docu, apps/api)
  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.

Migration to Other Platforms

You can deploy this project on other hosts. When you need to move away from Vercel, see Portability Strategy for host options and DATABASE_URL configuration — not a step-by-step migration guide.

Docs host crawl

The docs app (apps/docu) welcomes crawlers on HTML pages (opposite of the web app's disallow / policy).

  • app/robots.ts allows /, /docs, /og, /llms.txt, /llms-full.txt, and /sitemap.xml; disallows /api/ (Orama search).
  • app/sitemap.ts lists / and every Fumadocs page from source.getPages() (HTML only — not LLM dump paths).
  • Absolute loc URLs use NEXT_PUBLIC_SITE_URL.
  • LLM crawlers: start at /llms.txt, then fetch /llms-full.txt.

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.

Mobile CI/CD

EAS builds, preview distribution, and PR OTA updates for the Expo app. Android-only v1.

Self-Hosted LLM (Ollama)

Run local LLMs for data privacy. Recommended when prompts must stay on your infrastructure.

On this page

Setup1. Connect Repository2. Configure Environment Variables3. DeployDeployment Configurationvercel.json (Optional)Turbo remote cacheEnvironment-Specific ConfigurationDevelopmentProductionPath-Based DeploysBranch Preview CouplingMonorepo ConfigurationCustom DomainsE2E TestingMigration to Other PlatformsDocs host crawlTroubleshootingBuild FailsDeployment Not CreatedEnvironment Variables Not Applied"spawn pnpm ENOENT" or path ".../apps/docu/apps/docu" does not existRelated Documentation