Vercel deployment guide and named Supabase env errors

zgbrenner adds a 222-line Vercel deployment walkthrough and tightens the Supabase client initialization to name the missing variable when the app fails to start. Both changes target someone self-hosting Gary without a DevOps background.

infrastructuresecurity

The new docs/VERCEL_DEPLOYMENT.md is honest about the architecture: Vercel hosts the Next.js frontend only. The Express backend needs LibreOffice installed and a persistent server process, so it has to live on Railway, Render, Fly.io, or a plain VM. The guide explains which env vars are NEXT_PUBLIC_* (browser-safe) vs. which must stay server-side, with explicit warnings not to mix them up.

On the code side, supabase.ts and auth.ts replace the generic "supabaseUrl is required" startup error with a message that names the specific missing variable. The change also accepts the standard NEXT_PUBLIC_SUPABASE_ANON_KEY name while falling back to the legacy NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY, so deployments using either convention work without changes. Runtime behavior is otherwise the same - missing config still throws.

A new frontend/.env.vercel.example separates public and private variables into clearly labeled sections. The .gitignore update adds an explicit exception so this file gets committed alongside the other example env files.

Worth noting: this commit predates the Clerk auth migration. The later Clerk PR substantially rewrites VERCEL_DEPLOYMENT.md and replaces these env examples, so treat this as a snapshot of the pre-Clerk state.

So what The named-error improvement in Supabase initialization is small and low-risk, worth pulling in if misconfigured-env debugging is a real pain point. The public/private env split in `.env.vercel.example` is a useful reference pattern for any Next.js + backend split deployment. The Vercel guide itself is Gary-specific but readable as a deployment reference.

View this fork on GitHub →

Spotted something wrong? Or know the PR text has fresher detail than the writeup above?

Commits in this thread

2 commits from zgbrenner/gary, oldest first. Source extracted verbatim from the harvested git log.

SHA Subject Author Date

80791bc7 Merge pull request #4 from foolish-bandit/claude/gary-us-simplification-AjDDT Zack Brenner 2026-05-19 ↗ GitHub

0b6ee888 docs: add Vercel deployment path and clarify Supabase env errors Claude 2026-05-19 ↗ GitHub

SHA	Subject	Author	Date
`80791bc7`	Merge pull request #4 from foolish-bandit/claude/gary-us-simplification-AjDDT	Zack Brenner	2026-05-19	↗ GitHub
`0b6ee888`	docs: add Vercel deployment path and clarify Supabase env errors	Claude	2026-05-19	↗ GitHub
commit body Prepare Gary for a simple one-person Vercel deployment. Documentation and a clearer missing-env error - no product features, no Clerk, no database migration, no Cloudflare changes. - Add docs/VERCEL_DEPLOYMENT.md: plain-English guide covering what Vercel hosts (the Next.js frontend only), what Supabase handles, why the Express backend stays separate (needs LibreOffice and a long-running server), required public vs private environment variables, GitHub import steps, project settings (Root Directory = frontend, default build/output), preview deployments, custom domains, troubleshooting, and a "Future Clerk login" note. - Add frontend/.env.vercel.example: public NEXT_PUBLIC_* values separated from server-side secrets, with explicit warnings never to put provider / Supabase service-role / database / JWT / Clerk secrets in NEXT_PUBLIC_* variables. Includes a clearly-labeled future-only Clerk section. - supabase.ts and auth.ts: replace the cryptic "supabaseUrl is required" failure with a clear message naming the missing variable (NEXT_PUBLIC_SUPABASE_URL / NEXT_PUBLIC_SUPABASE_ANON_KEY) and where to set it. Also accept the standard NEXT_PUBLIC_SUPABASE_ANON_KEY name while still falling back to the legacy NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY, so existing deployments keep working. Runtime safety is unchanged - missing config still throws. - README: add a brief "Deploying Gary on Vercel" section and link the new guide; docs index links it too. - .gitignore: allow .env.vercel.example to be committed.

commit body

Prepare Gary for a simple one-person Vercel deployment. Documentation
and a clearer missing-env error - no product features, no Clerk, no
database migration, no Cloudflare changes.

- Add docs/VERCEL_DEPLOYMENT.md: plain-English guide covering what
  Vercel hosts (the Next.js frontend only), what Supabase handles,
  why the Express backend stays separate (needs LibreOffice and a
  long-running server), required public vs private environment
  variables, GitHub import steps, project settings (Root Directory =
  frontend, default build/output), preview deployments, custom
  domains, troubleshooting, and a "Future Clerk login" note.
- Add frontend/.env.vercel.example: public NEXT_PUBLIC_* values
  separated from server-side secrets, with explicit warnings never to
  put provider / Supabase service-role / database / JWT / Clerk
  secrets in NEXT_PUBLIC_* variables. Includes a clearly-labeled
  future-only Clerk section.
- supabase.ts and auth.ts: replace the cryptic "supabaseUrl is
  required" failure with a clear message naming the missing variable
  (NEXT_PUBLIC_SUPABASE_URL / NEXT_PUBLIC_SUPABASE_ANON_KEY) and
  where to set it. Also accept the standard
  NEXT_PUBLIC_SUPABASE_ANON_KEY name while still falling back to the
  legacy NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY, so existing
  deployments keep working. Runtime safety is unchanged - missing
  config still throws.
- README: add a brief "Deploying Gary on Vercel" section and link the
  new guide; docs index links it too.
- .gitignore: allow .env.vercel.example to be committed.

Capture this thread into my fork

Download a single Markdown prompt that tells Claude how to port every commit above into your working tree — adapting paths and structure to match your repo. Run it via claude -p < capture-thread-535.md from inside the repo you want the changes in.

⬇ Download capture-thread-535.md