Vercel is the most direct path to production for a ChaiBuilder site: native Next.js support, built-in ISR, and automatic deploys from Git. The starter works on Vercel without code changes.

Starting from scratch? You don't need a local project to get on Vercel - the Quickstart's one-click path deploys the starter first and finishes setup in the browser through the built-in /setup wizard. This page covers deploying a project you set up locally, and doubles as the environment reference for the wizard's paste-and-redeploy step.

1. Prepare production services

Before the first deploy, have these ready:

• A remote database. Vercel functions are ephemeral - a local SQLite file will not work. Use Turso (libSQL) or a Postgres provider (Neon, Supabase, or Vercel's Postgres integration). See Database Setup.
• Object storage. Uploads need an S3-compatible bucket - see Storage Configuration.

Use your provider's pooled connection string. Serverless creates many short-lived instances; connect Postgres through Neon's pooled endpoint or Supabase's transaction pooler (port 6543). ChaiBuilder detects poolers and sizes its connection pool down automatically.

2. Import the project

1. Push your project to a Git repository (GitHub, GitLab, Bitbucket).
2. In Vercel, Add New Project and import the repository.
3. Vercel detects Next.js automatically - the default build settings are correct. If asked, the install command is pnpm install and the build command is pnpm run build.

3. Set environment variables

In the project's Settings → Environment Variables, add the production values:

DATABASE_URL=postgresql://…        # pooled connection string
PAYLOAD_SECRET=…                   # long random secret
CHAIBUILDER_APP_KEY=…              # from your generated .env or the /setup wizard output
CHAIBUILDER_LICENSE_KEY=…          # optional during trial

# Object storage
BUCKET_NAME=…
AWS_ACCESS_KEY_ID=…
AWS_SECRET_ACCESS_KEY=…
S3_REGION=…                        # defaults to "auto" when unset
S3_ENDPOINT=…                      # omit on AWS S3

You can omit SITE_URL on Vercel - the platform's VERCEL_PROJECT_PRODUCTION_URL is used to build the site's base URL automatically. The full variable reference is in Environment & License.

4. Deploy

Trigger the first deploy. Then verify:

• The site loads on the deployment URL, and the builder and admin panel are reachable.
• Sign in with your admin account and publish a page - confirm the change is visible without a redeploy (that's ISR revalidation working).
• Upload an image in the media manager and confirm it renders - that's your object storage wired correctly.

Every push to your production branch now deploys automatically; preview branches get preview deployments with their own URLs.

How the rendering model maps to Vercel

• Pages are built on first visit and cached at Vercel's edge (SSG + ISR).
• Publishing a page invalidates exactly that page's cache entries - no full rebuild, no redeploy. Details in Caching & Revalidation.
• A new deployment resets the ISR cache; pages rebuild lazily on first visit after each deploy.

Notes and limits

• Build memory - the starter's build script already raises the Node heap size; Vercel's standard build containers handle it. If a build is killed, check the build logs for out-of-memory and consider enabling larger build resources on your plan.
• Function duration - normal page renders are fast, but first-visit builds of very heavy pages plus AI-assisted operations benefit from a higher function timeout (available on paid plans).
• Custom domain - add your domain in Vercel's domain settings. If you set SITE_URL, keep it in sync with the primary domain, since licensing validates against your domain.

Related

• Hosting Overview - compare targets.
• Database Setup - pooled connections in depth.
• Caching & Revalidation - the publish-to-live pipeline.