# Migrate To Better Auth

> 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.

- Skill: `rockclaver/migrate-to-better-auth` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add rockclaver/migrate-to-better-auth`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rockclaver/migrate-to-better-auth/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: rockclaver (https://skillmd.com/u/rockclaver)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rockclaver/migrate-to-better-auth

---


# Migrate to Better-Auth

Migrate to [better-auth](https://better-auth.com) 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](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

```bash
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](REFERENCE.md) — schema mappings, ORM snippets, env vars.
- `better-auth/skills` — setup (`npx skills add better-auth/skills`).