epic: Migrate auth from Stack Auth to Better Auth + Cloudflare deployment

[paccloud]

Overview

Migrate Fish Cost Calculator from Vercel + Stack Auth to Cloudflare Pages/Workers + Better Auth, keeping Neon PostgreSQL as the database. This consolidates the current dual auth system (custom JWT + Stack Auth OAuth) into a single Better Auth implementation that runs natively in Cloudflare Workers.

Why

• Stack Auth is tied to the Vercel/Neon integration panel — not portable
• Neon Auth has moved to Better Auth under the hood — natural migration path
• Better Auth runs natively in CF Workers (no external API calls for auth verification)
• Consolidates dual auth (JWT + OAuth) into one system
• $0/month on Neon free tier (60K MAU) + Cloudflare free tier (100K req/day)

Current State

• Auth: Dual system — custom JWT (password) + Stack Auth (Google/GitHub OAuth)
• Database: Neon PostgreSQL via @neondatabase/serverless
• Hosting: Vercel (serverless functions + static frontend)
• Integrations: 2x Neon + 1x Clerk (unused) on Vercel

Current Auth Files

File	Role
api/_lib/auth.js	requireAuth() middleware, JWT verify, Stack Auth fallback
api/_lib/neon-auth.js	Stack Auth session verification (calls api.stack-auth.com)
api/login.js	Password login → JWT token
api/register.js	Password registration → bcrypt hash
app/src/context/AuthContext.jsx	Frontend auth state, JWT + Stack Auth session checks
app/src/config/neonAuth.js	StackClientApp configuration
app/src/App.jsx	StackProvider wrapper, /handler/* OAuth callback route

Protected Endpoints (8)

save-calc, saved-calcs, user-data/index, user-data/[id], contributor, export, upload-data

Database Tables

• users — id, username, password (bcrypt), email, neon_auth_id, auth_provider, avatar_url, role
• calculations — user_id FK
• user_data — user_id FK
• contributors — user_id FK

Target State

• Auth: Better Auth (self-hosted in CF Worker) — email/password + Google/GitHub OAuth
• Database: Neon PostgreSQL via Cloudflare Hyperdrive
• Hosting: Cloudflare Pages (frontend) + Workers (API)
• Auth data: Stored in Neon (neon_auth schema or custom tables)

Phases

Phase 0: Cleanup (pre-migration)

• Remove unused Clerk integration from Vercel
• Remove stale Neon integration (12/19/24) from Vercel
• Fix Stack Auth trusted domains (immediate fix for current redirect error)
• Document current env vars and their sources

Phase 1: Better Auth Setup

• Install better-auth package
• Configure Better Auth with Neon PostgreSQL connection
• Set up auth schema (migrations or auto-create)
• Configure providers: email/password, Google OAuth, GitHub OAuth
• Test auth flows locally

Phase 2: Backend Migration

• Replace api/_lib/neon-auth.js with Better Auth session verification
• Replace api/_lib/auth.js requireAuth() to use Better Auth
• Replace api/login.js with Better Auth sign-in
• Replace api/register.js with Better Auth sign-up
• Migrate existing users table → Better Auth user schema
• Preserve user_id foreign keys (calculations, user_data, contributors)
• Update all 8 protected endpoints

Phase 3: Frontend Migration

• Replace StackProvider with Better Auth React provider in App.jsx
• Replace app/src/config/neonAuth.js with Better Auth client config
• Rewrite AuthContext.jsx to use Better Auth sessions
• Update Login component (OAuth buttons + password form)
• Remove /handler/* Stack Auth callback route
• Add Better Auth callback route
• Test cross-device login persistence

Phase 4: Cloudflare Deployment

• Set up Cloudflare Pages project (frontend)
• Set up Cloudflare Workers for API endpoints
• Configure Hyperdrive connection to Neon PostgreSQL
• Set up environment variables / secrets in CF dashboard
• Configure wrangler.toml with nodejs_compat flag
• Set up custom domain / DNS
• Test full auth flow on CF

Phase 5: Cutover & Cleanup

• Verify all auth flows work on Cloudflare
• Migrate DNS to Cloudflare (if using custom domain)
• Remove Vercel deployment
• Remove Stack Auth env vars
• Remove @stackframe/react dependency
• Delete old auth files (neon-auth.js, neonAuth.js)
• Update CLAUDE.md and documentation
• Update env examples

User Data Migration

Existing users need to maintain access:

• Password users: Bcrypt hashes may need re-import into Better Auth's user table (or keep custom table with adapter)
• OAuth users: neon_auth_id maps to Stack Auth IDs — Better Auth will assign new IDs on first OAuth login. Email-based linking preserves account continuity.
• Saved data: calculations, user_data, contributors tables use user_id FK — must map old IDs to new Better Auth user IDs

Risk Mitigation

• Better Auth supports custom database adapters — can point at existing users table structure
• Email-based identity linking means OAuth users reconnect automatically on first login
• Can run both auth systems in parallel during transition (current requireAuth() already supports fallback pattern)
• Neon database is platform-agnostic — no data migration needed

References

• Better Auth docs
• Better Auth on Cloudflare Workers
• Neon + Cloudflare Hyperdrive
• Neon Auth (Better Auth)
• Related: fix: Stack Auth redirect URL not whitelisted — auth integration audit needed #14 (redirect URL not whitelisted)

Labels

epic, auth, cloudflare, migration

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

The project currently runs on Vercel with a dual auth system: custom JWT (password) in api/_lib/auth.js + Stack Auth OAuth via api/_lib/neon-auth.js. The frontend uses @stackframe/react (StackProvider, StackHandler, stackClientApp) in app/src/App.jsx and app/src/config/neonAuth.js. The database layer (api/_lib/db.js) uses @neondatabase/serverless with a Pool, and the schema (scripts/neon-schema.sql) has a users table with neon_auth_id, email, avatar_url, and auth_provider columns already in place. better-auth is not yet installed in either package.json.

Approach

Migrate in five sequential phases matching the epic: cleanup → Better Auth setup → backend migration → frontend migration → Cloudflare deployment. Each phase is self-contained and reversible. The existing requireAuth() fallback pattern makes it safe to run both systems in parallel during transition.

---

Phase 0 — Pre-migration Cleanup

1. Remove Clerk integration from the Vercel dashboard (no code changes needed — it was never wired into the codebase).
2. Remove the stale Neon integration (12/19/24) from the Vercel dashboard.
3. Fix Stack Auth trusted domains in the Stack Auth dashboard to unblock the current redirect error (issue fix: Stack Auth redirect URL not whitelisted — auth integration audit needed #14).
4. Document all current env vars from app/.env.example and server/.env.example into a single migration reference doc so nothing is lost during cutover.

---

Phase 1 — Better Auth Setup

1.1 Install dependencies

• Add better-auth to the root package.json (alongside existing @neondatabase/serverless, bcrypt, jsonwebtoken).
• Add better-auth/react (or the Better Auth React client package) to app/package.json alongside existing React 19 deps.

1.2 Create the Better Auth server instance

• Create api/_lib/better-auth.js as the single source of truth for the Better Auth instance.
• Configure it with:
  • Database adapter: point at the existing Neon DATABASE_URL using @neondatabase/serverless (the same Pool already used in api/_lib/db.js).
  • Email/password plugin — maps to the existing username/password flow.
  • Social providers: Google OAuth and GitHub OAuth (replacing Stack Auth's OAuth).
  • BETTER_AUTH_SECRET env var (replaces JWT_SECRET for session signing).
  • BETTER_AUTH_URL env var pointing to the deployed API base URL.
• Better Auth will auto-create its own session/account tables (user, session, account, verification) in Neon on first run. These live alongside the existing users table during the transition.

1.3 Add the Better Auth catch-all API route

• Create api/auth/[...all].js (Vercel serverless function) that forwards all GET/POST requests to the Better Auth handler. This exposes /api/auth/* endpoints (sign-in, sign-up, callback, sign-out, session).

1.4 Add new env vars

Update app/.env.example and root .env.example to include:

• BETTER_AUTH_SECRET
• BETTER_AUTH_URL
• GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET
• GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET

Remove Stack Auth vars (VITE_STACK_PROJECT_ID, VITE_STACK_PUBLISHABLE_CLIENT_KEY, STACK_SECRET_SERVER_KEY) once migration is complete.

---

Phase 2 — Backend Migration

2.1 Replace api/_lib/neon-auth.js

• Rewrite api/_lib/neon-auth.js (or delete it and update the import in api/_lib/auth.js) so that the Stack Auth verifyNeonAuthSession call is replaced by a Better Auth session lookup using the Better Auth server instance from api/_lib/better-auth.js.
• Better Auth provides a auth.api.getSession({ headers }) method that reads the session cookie/token from the request headers — use this instead of the external fetch to api.stack-auth.com.

2.2 Rewrite api/_lib/auth.js

• Remove the verifyToken (JWT) path and the verifyNeonAuthSession fallback.
• Replace verifyUser with a single call to auth.api.getSession({ headers: req.headers }) from the Better Auth instance.
• requireAuth wrapper stays structurally identical — it still sets req.user and calls the handler — only the internal verification changes.
• Map the Better Auth session user (session.user.id, session.user.email, session.user.name) to the shape the rest of the API expects ({ id, username, email }).

2.3 Replace api/login.js

• Remove the bcrypt + JWT sign flow.
• Delegate to Better Auth's built-in email/password sign-in endpoint (/api/auth/sign-in/email). The api/login.js file can either be deleted (if the frontend calls /api/auth/* directly) or kept as a thin proxy for backward compatibility during transition.

2.4 Replace api/register.js

• Same pattern as login — delegate to Better Auth's sign-up endpoint (/api/auth/sign-up/email). Better Auth handles bcrypt hashing internally.

2.5 User data migration

• Existing password users have bcrypt hashes in the users.password column. Better Auth stores credentials in its own account table. Write a one-time migration script (scripts/migrate-users-to-better-auth.sql or a Node script) that:
  1. Inserts each existing users row into Better Auth's user table (preserving email).
  2. Inserts a corresponding row into Better Auth's account table with providerId = 'credential' and the existing bcrypt hash as the password field — Better Auth's credential provider is bcrypt-compatible.
  3. Records the mapping of old users.id → new Better Auth user.id for FK updates.
• Update calculations.user_id, user_data.user_id, and contributors.user_id FKs to reference the new Better Auth user IDs using the mapping table.
• OAuth users: on first login via Google/GitHub, Better Auth will match by email and create an account record linked to the existing user record — no manual migration needed.

2.6 Verify all 8 protected endpoints still work

The following files use requireAuth and req.user.id — no changes needed to their business logic, only the auth middleware underneath changes:

• api/save-calc.js
• api/saved-calcs.js
• api/contributor.js
• api/export.js
• api/upload-data.js
• api/user-data/index.js (and [id].js)

---

Phase 3 — Frontend Migration

3.1 Replace app/src/config/neonAuth.js

• Delete the StackClientApp configuration.
• Create app/src/config/betterAuth.js that initializes the Better Auth browser client (e.g., createAuthClient({ baseURL: import.meta.env.VITE_API_URL })) using the Better Auth React/client package.
• Export authClient from this file (replaces stackClientApp).

3.2 Rewrite app/src/context/AuthContext.jsx

• Remove all stackClientApp references.
• Replace the checkSession effect with a call to authClient.getSession() (Better Auth client method).
• Replace signInWithOAuth(provider) with authClient.signIn.social({ provider, callbackURL: '/' }).
• Replace login(username, password) with authClient.signIn.email({ email, password }) — note: the current form uses username not email; since Better Auth's email/password plugin uses email as the identifier, you'll need to decide whether to keep username-based login (requires a custom adapter or storing username separately) or migrate to email-based login. The simplest path is to use email as the login field going forward and display username from the user's name field.
• Replace register(username, password) with authClient.signUp.email({ email, password, name: username }).
• Replace logout() with authClient.signOut().
• The token / localStorage pattern is removed — Better Auth uses HTTP-only cookies for sessions.

3.3 Update app/src/App.jsx

• Remove StackProvider, StackTheme, StackHandler imports and the @stackframe/react dependency.
• Remove the /handler/* route (StackHandlerRoutes component).
• Add a /api/auth/callback route if needed for OAuth redirects (Better Auth handles this server-side via the [...all].js handler, so no client-side route is typically needed).
• Remove @vercel/analytics import if migrating away from Vercel, or keep it until Phase 5.
• The AuthProvider wrapper and Router structure remain unchanged.

3.4 Update app/src/components/Login.jsx

• The UI (Google/GitHub buttons + username/password form) stays the same.
• Wire OAuth buttons to authClient.signIn.social({ provider: 'google' | 'github', callbackURL: '/' }) via the updated signInWithOAuth in AuthContext.
• Update the form label from "Username" to "Email" if switching to email-based auth, or keep username if using a custom Better Auth plugin.

3.5 Remove @stackframe/react from app/package.json

---

Phase 4 — Cloudflare Deployment

4.1 Cloudflare Pages (frontend)

• Create a Cloudflare Pages project pointing at the GitHub repo.
• Set build command: cd app && npm install && npm run build, output directory: app/dist.
• Configure _redirects or _routes.json in app/public/ for SPA fallback (replaces the vercel.json rewrite rule).

4.2 Cloudflare Workers (API)

• The existing api/*.js files use the Vercel serverless function signature ((req, res)). For Cloudflare Workers, these need to be adapted to the Workers fetch handler or wrapped using a compatibility layer (e.g., Hono, which Better Auth officially supports on CF Workers).
• Create a single worker/index.js entry point using Hono as the router (check if Hono is already a dependency — it is not currently, so add it to the worker package). Mount all API routes and the Better Auth handler under /api/*.
• Better Auth's Cloudflare Workers integration is documented at the referenced Hono example — use toWebHandler(auth) or the Hono plugin.

4.3 Cloudflare Hyperdrive

• Create a Hyperdrive configuration in the CF dashboard pointing at the Neon PostgreSQL connection string.
• Update api/_lib/db.js (or the worker equivalent) to use the Hyperdrive binding (env.HYPERDRIVE.connectionString) instead of the raw DATABASE_URL. The @neondatabase/serverless driver is compatible with Hyperdrive.

4.4 wrangler.toml

• Create wrangler.toml at the repo root (or in a worker/ subdirectory) with:
  • compatibility_flags = ["nodejs_compat"] (required for bcrypt, crypto, etc.)
  • [[hyperdrive]] binding pointing at the Hyperdrive ID.
  • [vars] for non-secret env vars.
  • Secrets (BETTER_AUTH_SECRET, GOOGLE_CLIENT_SECRET, GITHUB_CLIENT_SECRET) set via wrangler secret put.

4.5 Update VITE_API_URL

• In Cloudflare Pages environment variables, set VITE_API_URL to the Worker URL (e.g., https://api.your-domain.workers.dev).

---

Phase 5 — Cutover & Cleanup

1. Verify all auth flows (email/password sign-in, Google OAuth, GitHub OAuth, session persistence, logout) on the Cloudflare deployment.
2. Migrate DNS to Cloudflare if using a custom domain.
3. Remove the Vercel deployment.
4. Delete api/_lib/neon-auth.js and app/src/config/neonAuth.js.
5. Remove @stackframe/react from app/package.json and @vercel/analytics if no longer needed.
6. Remove Stack Auth env vars from all .env.example files.
7. Update CLAUDE.md to reflect the new architecture (Cloudflare Pages + Workers + Better Auth + Hono) and update DEPLOYMENT.md with Cloudflare-specific instructions.
8. Update vercel.json → delete it (or keep for reference).

---

Migration Flow Summary

sequenceDiagram
    participant Dev as Developer
    participant BA as Better Auth (api/_lib/better-auth.js)
    participant DB as Neon PostgreSQL
    participant FE as Frontend (AuthContext)

    Note over Dev,DB: Phase 1 - Setup
    Dev->>BA: Create Better Auth instance (email+OAuth)
    BA->>DB: Auto-create session/account/user tables

    Note over Dev,DB: Phase 2 - Backend
    Dev->>BA: Replace neon-auth.js → auth.api.getSession()
    Dev->>DB: Run user migration script (users → BA user+account tables)

    Note over FE,BA: Phase 3 - Frontend
    FE->>BA: Replace StackClientApp → authClient (Better Auth)
    FE->>BA: signIn.email() / signIn.social() / signOut()

    Note over Dev,DB: Phase 4 - Cloudflare
    Dev->>BA: Wrap in Hono router → CF Worker
    BA->>DB: Connect via Hyperdrive binding

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The project currently runs on Vercel with a dual auth system: custom JWT (password) in `api/_lib/auth.js` + Stack Auth OAuth via `api/_lib/neon-auth.js`. The frontend uses `@stackframe/react` (`StackProvider`, `StackHandler`, `stackClientApp`) in `app/src/App.jsx` and `app/src/config/neonAuth.js`. The database layer (`api/_lib/db.js`) uses `@neondatabase/serverless` with a `Pool`, and the schema (`scripts/neon-schema.sql`) has a `users` table with `neon_auth_id`, `email`, `avatar_url`, and `auth_provider` columns already in place. `better-auth` is **not yet installed** in either `package.json`.

## Approach

Migrate in five sequential phases matching the epic: cleanup → Better Auth setup → backend migration → frontend migration → Cloudflare deployment. Each phase is self-contained and reversible. The existing `requireAuth()` fallback pattern makes it safe to run both systems in parallel during transition.

---

## Phase 0 — Pre-migration Cleanup

1. **Remove Clerk integration** from the Vercel dashboard (no code changes needed — it was never wired into the codebase).
2. **Remove the stale Neon integration** (12/19/24) from the Vercel dashboard.
3. **Fix Stack Auth trusted domains** in the Stack Auth dashboard to unblock the current redirect error (issue #14).
4. **Document all current env vars** from `app/.env.example` and `server/.env.example` into a single migration reference doc so nothing is lost during cutover.

---

## Phase 1 — Better Auth Setup

### 1.1 Install dependencies

- Add `better-auth` to the root `package.json` (alongside existing `@neondatabase/serverless`, `bcrypt`, `jsonwebtoken`).
- Add `better-auth/react` (or the Better Auth React client package) to `app/package.json` alongside existing React 19 deps.

### 1.2 Create the Better Auth server instance

- Create `api/_lib/better-auth.js` as the single source of truth for the Better Auth instance.
- Configure it with:
  - **Database adapter:** point at the existing Neon `DATABASE_URL` using `@neondatabase/serverless` (the same `Pool` already used in `api/_lib/db.js`).
  - **Email/password plugin** — maps to the existing `username`/`password` flow.
  - **Social providers:** Google OAuth and GitHub OAuth (replacing Stack Auth's OAuth).
  - **`BETTER_AUTH_SECRET`** env var (replaces `JWT_SECRET` for session signing).
  - **`BETTER_AUTH_URL`** env var pointing to the deployed API base URL.
- Better Auth will auto-create its own session/account tables (`user`, `session`, `account`, `verification`) in Neon on first run. These live alongside the existing `users` table during the transition.

### 1.3 Add the Better Auth catch-all API route

- Create `api/auth/[...all].js` (Vercel serverless function) that forwards all `GET`/`POST` requests to the Better Auth handler. This exposes `/api/auth/*` endpoints (sign-in, sign-up, callback, sign-out, session).

### 1.4 Add new env vars

Update `app/.env.example` and root `.env.example` to include:
- `BETTER_AUTH_SECRET`
- `BETTER_AUTH_URL`
- `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET`
- `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET`

Remove Stack Auth vars (`VITE_STACK_PROJECT_ID`, `VITE_STACK_PUBLISHABLE_CLIENT_KEY`, `STACK_SECRET_SERVER_KEY`) once migration is complete.

---

## Phase 2 — Backend Migration

### 2.1 Replace `api/_lib/neon-auth.js`

- Rewrite `api/_lib/neon-auth.js` (or delete it and update the import in `api/_lib/auth.js`) so that the Stack Auth `verifyNeonAuthSession` call is replaced by a Better Auth session lookup using the Better Auth server instance from `api/_lib/better-auth.js`.
- Better Auth provides a `auth.api.getSession({ headers })` method that reads the session cookie/token from the request headers — use this instead of the external `fetch` to `api.stack-auth.com`.

### 2.2 Rewrite `api/_lib/auth.js`

- Remove the `verifyToken` (JWT) path and the `verifyNeonAuthSession` fallback.
- Replace `verifyUser` with a single call to `auth.api.getSession({ headers: req.headers })` from the Better Auth instance.
- `requireAuth` wrapper stays structurally identical — it still sets `req.user` and calls the handler — only the internal verification changes.
- Map the Better Auth session user (`session.user.id`, `session.user.email`, `session.user.name`) to the shape the rest of the API expects (`{ id, username, email }`).

### 2.3 Replace `api/login.js`

- Remove the bcrypt + JWT sign flow.
- Delegate to Better Auth's built-in email/password sign-in endpoint (`/api/auth/sign-in/email`). The `api/login.js` file can either be deleted (if the frontend calls `/api/auth/*` directly) or kept as a thin proxy for backward compatibility during transition.

### 2.4 Replace `api/register.js`

- Same pattern as login — delegate to Better Auth's sign-up endpoint (`/api/auth/sign-up/email`). Better Auth handles bcrypt hashing internally.

### 2.5 User data migration

- Existing password users have bcrypt hashes in the `users.password` column. Better Auth stores credentials in its own `account` table. Write a one-time migration script (`scripts/migrate-users-to-better-auth.sql` or a Node script) that:
  1. Inserts each existing `users` row into Better Auth's `user` table (preserving `email`).
  2. Inserts a corresponding row into Better Auth's `account` table with `providerId = 'credential'` and the existing bcrypt hash as the password field — Better Auth's credential provider is bcrypt-compatible.
  3. Records the mapping of old `users.id` → new Better Auth `user.id` for FK updates.
- Update `calculations.user_id`, `user_data.user_id`, and `contributors.user_id` FKs to reference the new Better Auth user IDs using the mapping table.
- OAuth users: on first login via Google/GitHub, Better Auth will match by email and create an `account` record linked to the existing `user` record — no manual migration needed.

### 2.6 Verify all 8 protected endpoints still work

The following files use `requireAuth` and `req.user.id` — no changes needed to their business logic, only the auth middleware underneath changes:
- `api/save-calc.js`
- `api/saved-calcs.js`
- `api/contributor.js`
- `api/export.js`
- `api/upload-data.js`
- `api/user-data/index.js` (and `[id].js`)

---

## Phase 3 — Frontend Migration

### 3.1 Replace `app/src/config/neonAuth.js`

- Delete the `StackClientApp` configuration.
- Create `app/src/config/betterAuth.js` that initializes the Better Auth browser client (e.g., `createAuthClient({ baseURL: import.meta.env.VITE_API_URL })`) using the Better Auth React/client package.
- Export `authClient` from this file (replaces `stackClientApp`).

### 3.2 Rewrite `app/src/context/AuthContext.jsx`

- Remove all `stackClientApp` references.
- Replace the `checkSession` effect with a call to `authClient.getSession()` (Better Auth client method).
- Replace `signInWithOAuth(provider)` with `authClient.signIn.social({ provider, callbackURL: '/' })`.
- Replace `login(username, password)` with `authClient.signIn.email({ email, password })` — note: the current form uses `username` not `email`; since Better Auth's email/password plugin uses email as the identifier, you'll need to decide whether to keep username-based login (requires a custom adapter or storing username separately) or migrate to email-based login. The simplest path is to use email as the login field going forward and display `username` from the user's `name` field.
- Replace `register(username, password)` with `authClient.signUp.email({ email, password, name: username })`.
- Replace `logout()` with `authClient.signOut()`.
- The `token` / `localStorage` pattern is removed — Better Auth uses HTTP-only cookies for sessions.

### 3.3 Update `app/src/App.jsx`

- Remove `StackProvider`, `StackTheme`, `StackHandler` imports and the `@stackframe/react` dependency.
- Remove the `/handler/*` route (`StackHandlerRoutes` component).
- Add a `/api/auth/callback` route if needed for OAuth redirects (Better Auth handles this server-side via the `[...all].js` handler, so no client-side route is typically needed).
- Remove `@vercel/analytics` import if migrating away from Vercel, or keep it until Phase 5.
- The `AuthProvider` wrapper and `Router` structure remain unchanged.

### 3.4 Update `app/src/components/Login.jsx`

- The UI (Google/GitHub buttons + username/password form) stays the same.
- Wire OAuth buttons to `authClient.signIn.social({ provider: 'google' | 'github', callbackURL: '/' })` via the updated `signInWithOAuth` in `AuthContext`.
- Update the form label from "Username" to "Email" if switching to email-based auth, or keep username if using a custom Better Auth plugin.

### 3.5 Remove `@stackframe/react` from `app/package.json`

---

## Phase 4 — Cloudflare Deployment

### 4.1 Cloudflare Pages (frontend)

- Create a Cloudflare Pages project pointing at the GitHub repo.
- Set build command: `cd app && npm install && npm run build`, output directory: `app/dist`.
- Configure `_redirects` or `_routes.json` in `app/public/` for SPA fallback (replaces the `vercel.json` rewrite rule).

### 4.2 Cloudflare Workers (API)

- The existing `api/*.js` files use the Vercel serverless function signature (`(req, res)`). For Cloudflare Workers, these need to be adapted to the Workers `fetch` handler or wrapped using a compatibility layer (e.g., Hono, which Better Auth officially supports on CF Workers).
- Create a single `worker/index.js` entry point using **Hono** as the router (check if Hono is already a dependency — it is not currently, so add it to the worker package). Mount all API routes and the Better Auth handler under `/api/*`.
- Better Auth's Cloudflare Workers integration is documented at the referenced Hono example — use `toWebHandler(auth)` or the Hono plugin.

### 4.3 Cloudflare Hyperdrive

- Create a Hyperdrive configuration in the CF dashboard pointing at the Neon PostgreSQL connection string.
- Update `api/_lib/db.js` (or the worker equivalent) to use the Hyperdrive binding (`env.HYPERDRIVE.connectionString`) instead of the raw `DATABASE_URL`. The `@neondatabase/serverless` driver is compatible with Hyperdrive.

### 4.4 `wrangler.toml`

- Create `wrangler.toml` at the repo root (or in a `worker/` subdirectory) with:
  - `compatibility_flags = ["nodejs_compat"]` (required for `bcrypt`, `crypto`, etc.)
  - `[[hyperdrive]]` binding pointing at the Hyperdrive ID.
  - `[vars]` for non-secret env vars.
  - Secrets (`BETTER_AUTH_SECRET`, `GOOGLE_CLIENT_SECRET`, `GITHUB_CLIENT_SECRET`) set via `wrangler secret put`.

### 4.5 Update `VITE_API_URL`

- In Cloudflare Pages environment variables, set `VITE_API_URL` to the Worker URL (e.g., `https://api.your-domain.workers.dev`).

---

## Phase 5 — Cutover & Cleanup

1. Verify all auth flows (email/password sign-in, Google OAuth, GitHub OAuth, session persistence, logout) on the Cloudflare deployment.
2. Migrate DNS to Cloudflare if using a custom domain.
3. Remove the Vercel deployment.
4. Delete `api/_lib/neon-auth.js` and `app/src/config/neonAuth.js`.
5. Remove `@stackframe/react` from `app/package.json` and `@vercel/analytics` if no longer needed.
6. Remove Stack Auth env vars from all `.env.example` files.
7. Update `CLAUDE.md` to reflect the new architecture (Cloudflare Pages + Workers + Better Auth + Hono) and update `DEPLOYMENT.md` with Cloudflare-specific instructions.
8. Update `vercel.json` → delete it (or keep for reference).

---

## Migration Flow Summary

```mermaid
sequenceDiagram
    participant Dev as Developer
    participant BA as Better Auth (api/_lib/better-auth.js)
    participant DB as Neon PostgreSQL
    participant FE as Frontend (AuthContext)

    Note over Dev,DB: Phase 1 - Setup
    Dev->>BA: Create Better Auth instance (email+OAuth)
    BA->>DB: Auto-create session/account/user tables

    Note over Dev,DB: Phase 2 - Backend
    Dev->>BA: Replace neon-auth.js → auth.api.getSession()
    Dev->>DB: Run user migration script (users → BA user+account tables)

    Note over FE,BA: Phase 3 - Frontend
    FE->>BA: Replace StackClientApp → authClient (Better Auth)
    FE->>BA: signIn.email() / signIn.social() / signOut()

    Note over Dev,DB: Phase 4 - Cloudflare
    Dev->>BA: Wrap in Hono router → CF Worker
    BA->>DB: Connect via Hyperdrive binding
```

---

Execution Information

Branch: main
Commit: 306f6ed

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.