Better Auth

better-auth-starter

zpg6's better-auth-cloudflare OpenNext example — open-source authentication with better-auth: anonymous, email-and-password and (once keys are stored) GitHub and Google sign-in, every session enriched with Cloudflare's geolocation and kept in Workers KV, the users in a Cloudflare D1 database, files a signed-in user uploads in R2 — running on Cloudflare Workers + Static Assets through @opennextjs/cloudflare.

The example and its wrapper, better-auth-cloudflare, are kept as they are and pinned to exact versions (better-auth-cloudflare@0.4.1, better-auth@1.7.3, @better-auth/drizzle-adapter@1.7.3); the wrapper has one maintainer, so an upgrade is a deliberate change. The database, the namespace and the bucket are provisioned by Terraform through Orun, the schema applied by migrations, and the whole is packaged as an Orun baseline: one command takes a new product from nothing to live on stage and prod, in its own repository, under its own name — in ONE landing. The session secret is generated in each environment's database, so the site signs users in with nothing typed; GitHub and Google sign-in appear when their keys are stored. What the baseline adds is everything needed to make a copy of it somebody else's, built the way cirrus-baseline is. The design, the milestones and the as-built status are in specs/epics/better-auth-starter. MIT, © 2025 Zach Grimaldi (apps/web/LICENSE).

Instantiating a product

git clone --depth 1 --branch <baseline-tag> https://github.com/sourceplane/better-auth-starter
cd better-auth-starter
orun new --blueprint repo-blueprint.yaml --out ~/sites/acme-accounts --run-hooks --resume \
  --set reponame=acme-accounts --set productname="Acme Accounts" \
  --set githuborg=acme-inc --set subdomain=<workers-dev-subdomain>

Or, once the platform's registry lists it, from the Orun console (Baselines → better-auth-starter → Build). Two phases: 01-product creates the repository and lands the whole product as ONE pull request — intent, CI, tooling, the D1, KV and R2 roots, the migrations, the site and its tests — and one convergence, per environment, applies the database, the namespace and the bucket, then the migrations, then deploys the site bound to them; 02-docs records the live deployment from probed facts. BOOTSTRAP.md is the operator guide; docs/phases/ has a page per phase.

The new repository receives the product only — the app, its D1, KV and R2 roots, its migrations and their runner, its tests, its CI, its tooling, a README of its own and its operating contract — renamed throughout to the product's name, repository, Cloudflare Worker, database, namespace and bucket names. None of this repository's machinery ships.

What is here (the product)

Getting started

pnpm install
pnpm run wire:fixture   # render apps/web/wrangler.jsonc from the offline fixture
pnpm typecheck
pnpm lint
pnpm test
pnpm build              # next build + opennextjs-cloudflare build → apps/web/.open-next

pnpm --filter @app/web db:migrate:local   # better-auth's tables and the auth secret in wrangler's local D1
pnpm --filter @app/web dev                # http://localhost:3000 — the local D1, KV and R2 through wrangler's platform proxy
pnpm --filter @app/web preview            # wrangler dev over the built Worker, same local bindings

Deploying

The Orun pipeline (.github/workflows/ci.yml) plans nothing while intent.yaml names the placeholder workspace ws_CHANGE_ME. Link the repository to an Orun Cloud workspace (orun cloud link), set execution.state.workspace to it, connect Cloudflare in the workspace, and every merge to main then applies the D1 database, the KV namespace and the R2 bucket, migrates the database and deploys better-auth-starter-web-stage, then -prod, each smoke-tested on /api/health. A pull request verifies the same lanes and deploys nothing. A manual run of ci.yml (Run workflow on main, or Orunbase's Deploy button) redeploys the components it names.

The deploy needs nothing typed: the auth secret is generated in each environment's database by the migrations, and the sign-in page works with no provider. R2 must be enabled on the Cloudflare account once (the dashboard asks for a payment method even on the free tier); until it is, the R2 root's apply fails.

Custom domain

The Worker answers on workers.dev from its first deploy. To serve it on a domain of your own, attach the domain to the Worker in Cloudflare (Workers & Pages → the Worker → Settings → Domains & Routes) and replace better-auth-starter.example.com in intent.yaml's BASE_DOMAIN. better-auth takes the origin each request arrives on, so sign-in works on the new domain without changing a line; set BETTER_AUTH_URL only to pin one origin (an OAuth app's callback URL must match it).

Sign-in providers

Anonymous and email-and-password sign-in work with nothing configured. GitHub or Google sign-in appears once a provider's client id and secret are both set — GITHUB_CLIENT_ID + GITHUB_CLIENT_SECRET, GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET — in apps/web/.dev.vars locally. The OAuth app's callback URL is <origin>/api/auth/callback/<provider>. No mail sender is configured, so email addresses are not verified.

How it maps to the example's Cloudflare setup

How the data reaches the Worker

infra/terraform/cloudflare-d1 ──apply──► WIRING_CLOUDFLARE_D1 ─┬─► infra/db-migrate  apply: packages/db's runner → POST …/d1/database/<id>/query
infra/terraform/cloudflare-kv ──apply──► WIRING_CLOUDFLARE_KV ─┤        (better-auth's tables, the generated auth secret)
infra/terraform/cloudflare-r2 ──apply──► WIRING_CLOUDFLARE_R2 ─┴─► apps/web  build: tooling/wire/live.mjs → wrangler.jsonc with the ids
                                                                          (dev, verify-only, renders the fixture) → next build → OpenNext → deploy

Each reader declares an enforced dependsOn on what it reads on a push to main (advisory on a pull request), so one convergence per environment runs the three roots, then the migrations, then the Worker. wrangler.jsonc is committed as the fixture render of wrangler.template.jsonc, because the deploy lane's verify-app-structure step checks the config exists before it builds.

CI