better-auth

Better Auth - Complete Authentication

TypeScript-first authentication library with 40+ OAuth providers and 20+ plugins.

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

1. fuse-ai-pilot:explore-codebase - Analyze existing auth setup and patterns
2. fuse-ai-pilot:research-expert - Verify latest Better Auth docs via Context7/Exa
3. mcp__context7__query-docs - Check providers/plugins availability

After implementation, run fuse-ai-pilot:sniper for validation.

---

Overview

When to Use

• Implementing authentication in TypeScript/JavaScript applications
• Need OAuth providers (Google, GitHub, Discord, Apple, Microsoft, etc.)
• Adding 2FA, magic links, passkeys, or phone authentication
• Enterprise SSO with SAML, SCIM provisioning, or organizations
• Integrating payments with Stripe or Polar subscriptions
• Web3 authentication with Sign-In with Ethereum (SIWE)
• Migrating from Auth.js, Clerk, Auth0, Supabase, or WorkOS

Why Better Auth

Feature	Benefit
Framework agnostic	Next.js, SvelteKit, Nuxt, Remix, Astro, Expo, NestJS
Plugin architecture	Add only the features you need (20+ plugins)
Full TypeScript	End-to-end type safety, inference included
Self-hosted	Your data stays on your infrastructure
Database flexible	Prisma, Drizzle, MongoDB, PostgreSQL, MySQL, SQLite
Enterprise ready	SSO, SCIM, organizations, audit logs

---

Coverage

OAuth Providers (40+)

Google, GitHub, Discord, Apple, Microsoft, Slack, Spotify, Twitter/X, Facebook, LinkedIn, GitLab, Bitbucket, Dropbox, Twitch, Reddit, TikTok, and 25+ more documented in providers/.

Plugins (20+)

Plugin	Purpose
2FA	TOTP authenticator, backup codes
Magic Link	Passwordless email login
Passkey	WebAuthn biometric authentication
Organization	Multi-tenant, roles, invitations
SSO	Enterprise SAML/OIDC single sign-on
SCIM	Directory sync, user provisioning
Stripe	Subscription billing integration
API Key	Machine-to-machine authentication
JWT/Bearer	Token-based API authentication

Database Adapters

Prisma, Drizzle, MongoDB, raw SQL (PostgreSQL, MySQL, SQLite), and community adapters.

---

SOLID Architecture (Next.js 16)

Components organized in modules/auth/ following separation of concerns:

• Services: betterAuth configuration and initialization
• Hooks: createAuthClient for client-side auth state
• API Route: app/api/auth/[...all]/route.ts handler
• Proxy: proxy.ts for route protection (replaces middleware)

---

Reference Guide

Need	Reference
Initial setup	installation.md, server-config.md
Client usage	client.md, session.md
OAuth providers	providers/overview.md, individual provider docs
Add plugins	plugins/overview.md, individual plugin docs
Database setup	adapters/prisma.md, adapters/drizzle.md
Enterprise SSO	plugins/sso.md, guides/saml-okta.md
Payments	plugins/stripe.md, plugins/polar.md
Migration	guides/clerk-migration.md, other migration guides
Complete examples	examples/ for full implementations

---

Best Practices

1. Plugins on demand - Only add plugins you actually need
2. Type-safe client - Use generated types from server config
3. Session caching - Enable session caching for performance
4. Rate limiting - Configure rate limits for auth endpoints
5. Secure cookies - Use secure, httpOnly, sameSite cookies
6. Database indexes - Add indexes on user lookup fields

---

Concepts

Core concepts explained in concepts/:

• Sessions - Token management, refresh, revocation
• Database - Schema design, migrations, adapters
• Plugins - Extension system, composition
• OAuth - Provider configuration, callbacks
• Security - CSRF, rate limiting, password hashing
• Cookies - Session storage, cross-domain