Deployment

Vercel auto-detects Next.js, and the shipped vercel.json files declare the workspace-aware build commands.

{
  "buildCommand": "cd ../.. && pnpm build --filter=@syntaxkit/web",
  "installCommand": "pnpm install",
  "framework": "nextjs"
}

Every Vercel preview deployment gets a unique URL (https://your-app-<hash>-<scope>.vercel.app), but an OAuth provider (GitHub, Google) only accepts the one callback URL registered in its console. So social sign-in works on production but fails on previews (and on any origin whose callback isn't registered).

The kit solves this with Better Auth's OAuth proxy (opt-in). When enabled, preview/dev deployments run their OAuth flow through your production origin — which owns the single registered callback URL — and production hands the authenticated profile back to the preview (encrypted, never touching production's database). One callback registration then works across unlimited previews.

Better Auth infers the current (preview) URL on its own from the request and VERCEL_URL, so you don't configure that. The only thing it can't infer is which origin is production — and in this kit that's simply your app base URL. So set NEXT_PUBLIC_APP_URL (or BETTER_AUTH_URL) to your production URL on every environment, including Preview — then add two vars on both the Production and Preview environments (Vercel scopes env vars per-environment):

Then register only the production callback with each provider, e.g. https://your-app.com/api/auth/callback/github. No per-preview registration is needed.

Email links follow the preview too

AUTH_TRUSTED_ORIGINS does double duty. Transactional auth emails (verification, password reset, email-change confirmation) also build their links from the app base URL — which you've pinned to production — so on a preview they would otherwise point at production (and the link's token, signed with that environment's BETTER_AUTH_SECRET, would fail to verify there). When the incoming request's origin is covered by AUTH_TRUSTED_ORIGINS, the kit builds these links against that origin instead, so the whole verify/reset flow stays on the deployment the user is actually using. A request origin that isn't in the allowlist falls back to the static base URL, so this can't be used to send a link to an untrusted host. No extra configuration — it reuses the same AUTH_TRUSTED_ORIGINS the proxy already needs.

Billing in this kit is fail-closed: once STRIPE_SECRET_KEY is set, a missing STRIPE_WEBHOOK_SECRET is a fatal config error (a partial billing config). That's the right behavior in steady state — it stops you from running live billing with unverifiable webhooks — but it creates a bootstrap problem on the very first deploy. You can't create the Stripe webhook endpoint (and get its whsec_… signing secret) until the app has a live URL, and a misconfigured deploy won't serve normal traffic to give you that URL. The naive first deploy therefore comes up serving the "Configuration error" page (listing Billing is partially configured. Missing: STRIPE_WEBHOOK_SECRET.) with /api/health returning 503 — so on Fly/Render the release is marked unhealthy and never goes live.

The official happy path is a two-phase first deploy: boot once with a placeholder secret to get the URL, then swap in the real secret.

STRIPE_WEBHOOK_SECRET="whsec_placeholder"

STRIPE_WEBHOOK_SECRET="whsec_…"  # the real value from the Stripe Dashboard

Two Fly apps, one per Next.js app, both built from the kit's Dockerfiles. The web app's release hook handles migrations automatically.

fly launch --copy-config --no-deploy

[deploy]
  release_command = '/bin/sh /release/scripts/deploy/migrate-database.sh'

fly launch --copy-config --no-deploy -c apps/docs/fly.toml

fly secrets set \
  DATABASE_URL="postgresql://..." \
  BETTER_AUTH_SECRET="$(openssl rand -base64 32)" \
  STRIPE_SECRET_KEY="sk_live_..." \
  STRIPE_WEBHOOK_SECRET="whsec_..." \
  GITHUB_CLIENT_ID="..." \
  GITHUB_CLIENT_SECRET="..." \
  --app syntaxkit-web

fly deploy                          # web app (uses ./fly.toml)
fly deploy -c apps/docs/fly.toml    # docs app

Render reads the kit's render.yaml blueprint at the repo root and provisions both services in one click. Migrations run as a preDeployCommand on every release.

The docker-compose.yml at the repo root defines three services: a one-shot migrator (in the tools profile), web, and docs. Buyers bring their own Postgres.

cp .env.docker.example .env
docker compose build
docker compose run --rm migrator
docker compose up -d

The migrator service uses the tools profile so it doesn't run with up; invoke it explicitly before each release. Web and docs both ship healthchecks (/api/healthz for web, / for docs), and web is configured with a 30-second stop_grace_period so Next.js after() callbacks can finish before SIGTERM.

Pre-built images on GHCR. .github/workflows/docker.yml publishes the same images to GHCR on every push to main and every semver tag:

• ghcr.io/<owner>/<repo>/web:latest (and :<sha>, :<branch>, :<version>)
• ghcr.io/<owner>/<repo>/docs:latest

Useful for Kubernetes, Coolify, Dokku, Nomad, or any other Docker host. Pull the image, set runtime env, and run migrations either by building the migrator stage (docker build --target migrator ...) or by invoking scripts/deploy/migrate-database.sh from a job container that has Prisma available.

The kit ships no netlify.toml, but Netlify, Railway, Heroku, Coolify, and other generic Next.js hosts run the kit cleanly using the same shape as Vercel:

• Build the workspace via pnpm build --filter=@syntaxkit/web (or --filter=@syntaxkit/docs), with pnpm install as the install command.
• Set the same build-time vs runtime env split documented above.
• Run migrations from CI before the deploy step. scripts/deploy/migrate-database.sh works on any Linux host with Node and the packages/database workspace available.

Each platform declares those settings its own way (Netlify uses netlify.toml, Railway uses dashboard config); refer to your host's Next.js setup guide for the exact syntax.

Generate with openssl rand -base64 32 and set the same value on every replica. Without a shared key, a server-action signature created by replica A can't be decrypted by replica B, and you'll see intermittent failures on form submissions that span multiple requests.

Set TRUST_PROXY_HEADERS=true and TRUSTED_PROXY_IP_HEADERS to the header your proxy sets. Better Auth uses these to read the real client IP so per-IP auth rate limits (brute-force/credential-stuffing defenses) key off the actual visitor, not the proxy. Fly does forward the client IP (via X-Forwarded-For / Fly-Client-IP), so proxy headers are needed there — the kit's fly.toml therefore defaults TRUST_PROXY_HEADERS=true. Render's blueprint sets it too. On self-hosted Docker Compose (or any other host) set both vars only when the app sits behind a trusted proxy you control. Tradeoff: these headers are client-spoofable, so trust them only behind a proxy that overwrites them — trusting them on a directly-exposed app lets a caller forge its IP and slip past the rate limits.

Only when Better Auth needs a different origin from NEXT_PUBLIC_APP_URL. Most deployments leave it unset and let Better Auth derive its base URL from the public app URL.