better-auth

name	better_auth
description	The ultimate authentication and authorization skill. Implement login, signin, signup, registration, OAuth, 2FA, MFA, passkeys, and user session management. Secure your application with RBAC and access control.

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: "[e-mail]",
  password: "secure123",
  name: "John Doe"
});

// Sign in
await authClient.signIn.email({
  email: "[e-mail]",
  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:

1. Server (better-auth): Handles auth logic, database ops, API routes
2. Client (better-auth/client): Provides hooks/methods for frontend
3. 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/examples

---

Better Auth v2.1.1 - Enhanced

🔄 Workflow

Kaynak: Better Auth Docs

Aşama 1: Setup & Config

• Install: Paketi kur ve .env (Source of Truth) ayarla.
• Client/Server: auth.ts (Server) ve auth-client.ts (Client) dosyalarını oluştur.
• Database: Şemayı oluştur ve migrate et.

Aşama 2: Method Implementation

• Strategy: Email/Pass, OAuth veya Magic Link seçimi.
• UI Integration: Frontend formlarını authClient metodlarına bağla.
• Protection: Middleware veya Hook ile sayfaları koru.

Aşama 3: Verification

• Flow Test: Sign-up -> Sign-in -> Session Check -> Sign-out.
• Error Handling: Yanlış şifre/email durumlarını test et.

Kontrol Noktaları

Aşama	Doğrulama
1	BETTER_AUTH_SECRET ve BETTER_AUTH_URL tanımlı
2	Veritabanında user ve session tabloları oluştu
3	Middleware korumalı sayfalara limitsiz erişimi engelliyor