Migrate to Better-Auth
Migrate to better-auth one phase at a time.
Workflow
1. Audit
Auth library, methods, schema, ORM, seed files.
2. Select features
Auth methods: email/password, OAuth (which providers?), magic link, passkeys, phone/OTP, anonymous
Plugins: 2FA, organization/multi-tenant, admin roles, API keys, SSO/OIDC, JWT, HIBP breach detection
Session: database-backed (default) | Redis-backed
3. Plan
Map fields first (REFERENCE.md); run /refactor-codebase with the mapping, config, seed. Phases:
- Install & scaffold —
better-auth, schema, env vars
- Schema migration — alter DB tables
- Server config —
auth.ts
- Route handlers —
auth.handler
- Client —
authClient hooks
- Seed data — update fixtures
- Cleanup — remove old library
4. Seed data
Rename columns, coerce emailVerified to boolean, add createdAt/updatedAt/accountId/providerId.
5. Verify
npx tsc --noEmit && npm test
curl -X POST http://localhost:3000/api/auth/sign-in/email \
-H "Content-Type: application/json" -d '{"email":"test@example.com","password":"password"}'
Guardrails
- Keep the old library until phases verify; never silently cast
emailVerified to boolean.
- Flag missing OAuth env vars.
- No auth tests? Add a Phase 0 smoke test.
References
- REFERENCE.md — schema mappings, ORM snippets, env vars.
better-auth/skills — setup (npx skills add better-auth/skills).
1---2name: migrate-to-better-auth3description: Migrates NextAuth, Passport, Lucia, Clerk, custom JWT, or session auth to better-auth, detecting setup and rewriting config/routes/seed. Use when switching to better-auth or replacing NextAuth, Lucia, Passport, Clerk, or custom auth.4---56# Migrate to Better-Auth78Migrate to [better-auth](https://better-auth.com) one phase at a time.910## Workflow1112### 1. Audit13Auth library, methods, schema, ORM, seed files.1415### 2. Select features1617```18Auth methods: email/password, OAuth (which providers?), magic link, passkeys, phone/OTP, anonymous19Plugins: 2FA, organization/multi-tenant, admin roles, API keys, SSO/OIDC, JWT, HIBP breach detection20Session: database-backed (default) | Redis-backed21```2223### 3. Plan24Map fields first ([REFERENCE.md](REFERENCE.md)); run `/refactor-codebase` with the mapping, config, seed. Phases:251. Install & scaffold — `better-auth`, schema, env vars262. Schema migration — alter DB tables273. Server config — `auth.ts`284. Route handlers — `auth.handler`295. Client — `authClient` hooks306. Seed data — update fixtures317. Cleanup — remove old library3233### 4. Seed data34Rename columns, coerce `emailVerified` to boolean, add `createdAt`/`updatedAt`/`accountId`/`providerId`.3536### 5. Verify3738```bash39npx tsc --noEmit && npm test40curl -X POST http://localhost:3000/api/auth/sign-in/email \41 -H "Content-Type: application/json" -d '{"email":"test@example.com","password":"password"}'42```4344## Guardrails4546- Keep the old library until phases verify; never silently cast `emailVerified` to boolean.47- Flag missing OAuth env vars.48- No auth tests? Add a Phase 0 smoke test.4950## References5152- [REFERENCE.md](REFERENCE.md) — schema mappings, ORM snippets, env vars.53- `better-auth/skills` — setup (`npx skills add better-auth/skills`).
rockclaver