better-auth

Implements Better Auth, a TypeScript-first authentication library, in a Next.js 16 App Router project: server config, client (`createAuthClient`), session management, and the `app/api/auth/[...all]/route.ts` handler, plus `proxy.ts` for route protection (replacing middleware).

Covers the full surface — 40+ OAuth providers (Google, GitHub, Discord, Apple, Microsoft, and more), 20+ plugins (2FA, magic links, passkeys, organizations/multi-tenant, enterprise SSO/SAML, SCIM provisioning, Stripe/Polar billing, JWT/Bearer, API keys), and database adapters (Prisma, Drizzle, MongoDB, raw SQL). Also covers migration paths from Auth.js, Clerk, Auth0, Supabase, and WorkOS. While Better Auth itself is framework-agnostic, this skill's architecture guidance (proxy.ts, App Router API route) is Next.js-specific — for Prisma schema/query details see prisma-7.

Better Auth - Complete Authentication

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

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:

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

Version Notes (current stable: 1.7.x)

Since	Change
1.5	Standalone CLI npx auth@latest (generate, migrate, secret, init, check…) replaces @better-auth/cli; OAuth 2.1 Provider (@better-auth/oauth-provider)
1.6	session.freshAge computed from createdAt; oidcProvider deprecated
1.7	oidcProvider removed; generic OAuth providers use signIn.social (no genericOAuthClient); DB joins via advanced.database.joins; accounts keyed on (issuer, accountId); twoFactor.enable returns a method-discriminated response; MCP → @better-auth/mcp; SCIM decoupled from organization

After upgrading to 1.7, regenerate the schema (npx auth@latest generate) and follow the official 1.7 upgrade guide.

---

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