Skip to Content
Settlr

Deployment

Deploy the web app and Convex backend to Vercel, and the docs as a second project.

Web app and backend

The web app is a standard Next.js app, deployable to Vercel or anywhere Node.js runs (pnpm build && pnpm start). The backend is deployed with convex deploy from packages/backend.

On Vercel

The Vercel project for the web app uses:

SettingValue
Root Directoryapps/web
FrameworkNext.js
Build Commandfrom apps/web/vercel.json
EnvironmentCONVEX_DEPLOY_KEY, NEXT_PUBLIC_CONVEX_SITE_URL

Vercel installs the whole pnpm workspace from the repository root, then runs the build command in apps/web/vercel.json:

cd ../../packages/backend && pnpm exec convex deploy \
  --cmd "cd ../../apps/web && pnpm build" \
  --cmd-url-env-var-name NEXT_PUBLIC_CONVEX_URL

convex deploy pushes convex/ to the deployment that CONVEX_DEPLOY_KEY belongs to, then runs the web build with NEXT_PUBLIC_CONVEX_URL set to that deployment. A push therefore updates both the site and the backend.

vercel.json also turns off deployments for every branch except main.

A build from main overwrites whatever pnpm dev:convex pushed to the same Convex deployment from a local checkout.

After the first deploy, set the Convex deployment's SITE_URL to the site's URL (see Environment variables).

Docs

This site is apps/docs, a separate Next.js app, deployed as the second Vercel project settlr-docs from the same repository with Root Directory apps/docs. It needs no environment variables, and like the web app its vercel.json only deploys main.

The web app links to the docs through DOCS_URL in apps/web/src/lib/site.ts. Set NEXT_PUBLIC_DOCS_URL on the web build if your docs live somewhere else.

Build it locally with:

pnpm --filter docs build

Health check

GET /api/health on the web app returns a JSON liveness response, for load balancers and platform health checks.

On this page