migrate-to-better-auth

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:

1. Install & scaffold — better-auth, schema, env vars
2. Schema migration — alter DB tables
3. Server config — auth.ts
4. Route handlers — auth.handler
5. Client — authClient hooks
6. Seed data — update fixtures
7. 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).