[RFC] 145 - Unify auth to better-auth

[tjx666]

Unify to BetterAuth

Background

• Clerk server-side API has high latency, causing slow data loading experience for users
• Limited customization flexibility. For example, when implementing referral features, we need to support users entering invitation codes during registration, but Clerk's built-in registration component cannot meet this requirement
• next-auth (auth.js) has been acquired by better-auth

Goal

Unify to use better-auth as the authentication system across LobeChat open-source and cloud deployments.

Current Status

• next-auth currently only supports SSO login, does not support email/password login

---

Phase 1: BetterAuth Support in Open-Source (lobechat)

Add better-auth as an authentication option, with backward compatibility for next-auth environment variables.

1.1 BetterAuth Infrastructure

• Implement sign in/sign up components
  • Configure email verification in better-auth
  • Implement sign-up page with email/username/password
  • Implement email verification notice page
  • Add i18n translations (zh-CN, en-US)
  • Add SMTP configuration to .env.example
  • Delete Clerk sign-up/login pages
• Support email, GitHub, Google, Apple login (email ✅, OAuth pending)

1.2 NextAuth Compatibility

• Ensure better-auth can reuse next-auth environment variables (e.g., AUTH_SECRET, OAuth client configs)
• Adapt OIDC provider to work with better-auth
• Adapt auth logic in tRPC and route handlers
• Update documentation for better-auth deployment

---

Phase 2: Clerk Migration in Cloud (lobechat-cloud)

Migrate Clerk to better-auth in the cloud repository, then open-source the migration tools.

2.1 Cloud Migration

• Migrate Clerk user data to BetterAuth
• Validate migration in production environment

2.2 Cleanup Clerk Dependencies

• Remove Clerk code from cloud repository
• Clean up Clerk-related dependencies and environment variables

2.3 Open-Source Migration Tools

• Open-source Clerk → BetterAuth migration script
• Publish Clerk migration documentation

---

Phase 3: NextAuth Migration Script in Open-Source (lobechat)

Provide migration path for existing next-auth users.

3.1 Migration Script

• Implement NextAuth → BetterAuth migration script
• Handle user data, sessions, and OAuth accounts migration

3.2 Documentation & Cleanup

• Publish NextAuth migration documentation
• Remove NextAuth code after migration period
• Clean up dependencies and environment variables

[cy948]

注册流程： better-auth 似乎用的是 signup -> signin ？ 这样的话， 还需要对之前 next-auth 用的 login ui 进行改动。
用户中心： next-auth 有一个 Profile page 允许用户检查他们的头像和绑定的 SSO ，也需要做迁移。

[tjx666]

注册流程: 是的，这次会支持邮箱密码注册登入， 会直接改造 signin/signup 页面
用户中心：这个前面页面应该不需要改动，可以直接复用，better-auth 收购了 next-auth，next-auth 支持的 sso， better-auth 应该都支持，到时候会提供一个迁移脚本和文档