back
loading skill details...
Implement authentication and authorization with Better Auth - a framework-agnostic TypeScript authentication framework. Features include email/password…
Better Auth Skill
Better Auth is comprehensive, framework-agnostic authentication/authorization framework for TypeScript with built-in email/password, social OAuth, and powerful plugin ecosystem for advanced features.
When to Use
Implementing auth in TypeScript/JavaScript applications
Adding email/password or social OAuth authentication
Setting up 2FA, passkeys, magic links, advanced auth features
Building multi-tenant apps with organization support
Managing sessions and user lifecycle
Working with any framework (Next.js, Nuxt, SvelteKit, Remix, Astro, Hono, Express, etc.)
Quick Start
Installation
npm install better-auth
# or pnpm/yarn/bun add better-auth
Environment Setup
Create .env:
BETTER_AUTH_SECRET=<generated-secret-32-chars-min>
BETTER_AUTH_URL=http://localhost:3000
Basic Server Setup
Create auth.ts (root, lib/, utils/, or under src/app/server/):
import { betterAuth } from "better-auth";
export const auth = betterAuth({
database: {
// See references/database-integration.md
},
emailAndPassword: {
enabled: true,
autoSignIn: true
},
socialProviders: {
github: {
clientId: process.env.GITHUB_CLIENT_ID!,
clientSecret: process.env.GITHUB_CLIENT_SECRET!,
}
}
});
Database Schema
npx @better-auth/cli generate # Generate schema/migrations
npx @better-auth/cli migrate # Apply migrations (Kysely only)
Mount API Handler
Next.js App Router:
// app/api/auth/[...all]/route.ts
import { auth } from "@/lib/auth";
import { toNextJsHandler } from "better-auth/next-js";
export const { POST, GET } = toNextJsHandler(auth);
Other frameworks: See references/email-password-auth.md#framework-setup
Client Setup
Create auth-client.ts:
import { createAuthClient } from "better-auth/client";
export const authClient = createAuthClient({
baseURL: process.env.NEXT_PUBLIC_BETTER_AUTH_URL || "http://localhost:3000"
});
Basic Usage
// Sign up
await authClient.signUp.email({
email: "user@example.com",
password: "secure123",
name: "John Doe"
});
// Sign in
await authClient.signIn.email({
email: "user@example.com",
password: "secure123"
});
// OAuth
await authClient.signIn.social({ provider: "github" });
// Session
const { data: session } = authClient.useSession(); // React/Vue/Svelte
const { data: session } = await authClient.getSession(); // Vanilla JS
Feature Selection Matrix
Feature
Plugin Required
Use Case
Reference
Email/Password
No (built-in)
Basic auth
email-password-auth.md
OAuth (GitHub, Google, etc.)
No (built-in)
Social login
oauth-providers.md
Email Verification
No (built-in)
Verify email addresses
email-password-auth.md
Password Reset
No (built-in)
Forgot password flow
email-password-auth.md
Two-Factor Auth (2FA/TOTP)
Yes (twoFactor)
Enhanced security
advanced-features.md
Passkeys/WebAuthn
Yes (passkey)
Passwordless auth
advanced-features.md
Magic Link
Yes (magicLink)
Email-based login
advanced-features.md
Username Auth
Yes (username)
Username login
email-password-auth.md
Organizations/Multi-tenant
Yes (organization)
Team/org features
advanced-features.md
Rate Limiting
No (built-in)
Prevent abuse
advanced-features.md
Session Management
No (built-in)
User sessions
advanced-features.md
Auth Method Selection Guide
Choose Email/Password when:
Building standard web app with traditional auth
Need full control over user credentials
Targeting users who prefer email-based accounts
Choose OAuth when:
Want quick signup with minimal friction
Users already have social accounts
Need access to social profile data
Choose Passkeys when:
Want passwordless experience
Targeting modern browsers/devices
Security is top priority
Choose Magic Link when:
Want passwordless without WebAuthn complexity
Targeting email-first users
Need temporary access links
Combine Multiple Methods when:
Want flexibility for different user preferences
Building enterprise apps with various auth requirements
Need progressive enhancement (start simple, add more options)
Core Architecture
Better Auth uses client-server architecture:
Server (better-auth): Handles auth logic, database ops, API routes
Client (better-auth/client): Provides hooks/methods for frontend
Plugins: Extend both server/client functionality
Implementation Checklist
Install better-auth package
Set environment variables (SECRET, URL)
Create auth server instance with database config
Run schema migration (npx @better-auth/cli generate)
Mount API handler in framework
Create client instance
Implement sign-up/sign-in UI
Add session management to components
Set up protected routes/middleware
Add plugins as needed (regenerate schema after)
Test complete auth flow
Configure email sending (verification/reset)
Enable rate limiting for production
Set up error handling
Reference Documentation
Core Authentication
Email/Password Authentication - Email/password setup, verification, password reset, username auth
OAuth Providers - Social login setup, provider configuration, token management
Database Integration - Database adapters, schema setup, migrations
Advanced Features
Advanced Features - 2FA/MFA, passkeys, magic links, organizations, rate limiting, session management
Scripts
scripts/better_auth_init.py - Initialize Better Auth configuration with interactive setup
Resources
Docs: https://www.better-auth.com/docs
GitHub: https://github.com/better-auth/better-auth
Plugins: https://www.better-auth.com/docs/plugins
Examples: https://www.better-auth.com/docs/examplesdon't have the plugin yet? install it then click "run inline in claude" again.