Vercel deployment guide and a clearer missing-env error for Supabase

`0b6ee888` is mostly documentation: a new `docs/VERCEL_DEPLOYMENT.md` (222 lines) covering how to deploy Gary's frontend on Vercel with the backend staying on a separate host. The single code change makes a missing Supabase URL fail with the variable name rather than a cryptic prerender crash.

infrastructuresecurity

The architectural constraint the guide documents is real. Gary's Express backend needs LibreOffice for DOC/DOCX conversion, handles long-running document processing, and requires a persistent process. Vercel's serverless execution model is a poor fit for all three. The documented path puts only the Next.js frontend/ on Vercel (Root Directory set to frontend/, build settings left at defaults) and runs the backend on Railway, Render, Fly.io, or a VM. The frontend finds the backend through NEXT_PUBLIC_API_BASE_URL.

The guide is specific about the public/private variable split. NEXT_PUBLIC_* variables are baked into the browser bundle at build time - they're browser-visible, not secrets. Service-role Supabase keys, provider API keys, the signing secret, and the encryption secret belong on the backend host only, not in Vercel. The guide covers what goes where for both the Vercel environment and the backend .env, and explains that changing a NEXT_PUBLIC_* value in Vercel requires a fresh build to take effect.

The code change is a one-line improvement to error clarity. A missing NEXT_PUBLIC_SUPABASE_URL previously caused an opaque prerender failure; it now names the missing variable and where to set it. The same change standardized on NEXT_PUBLIC_SUPABASE_ANON_KEY as the canonical variable name while accepting the legacy NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY as a fallback, so existing deployments don't break.

zgbrenner explicitly deferred Clerk auth (still using Supabase Auth at this commit), a Vercel config file (argued it adds nothing once the root directory is set), and a one-click backend deploy template. Those follow in subsequent PRs. If you're reading this commit in isolation, the Vercel deployment it describes is open to the internet without an auth gate - a concern zgbrenner noted in the PR.

So what Worth a look for the architecture writeup if you're planning a split frontend/backend deployment. The guidance on public vs. private env vars and why the backend can't run on Vercel is directly applicable to any Mike-derived fork with the same Express + LibreOffice stack. The improved missing-env error is a two-line fix worth stealing. Skip if you're already running a working deployment and don't need the documentation.

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

Commits in this thread

1 commit from zgbrenner/gary, oldest first. Source extracted verbatim from the harvested git log.

SHA	Subject	Author	Date
`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.

SHA

Subject

Author

Date

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.

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-570.md from inside the repo you want the changes in.