Better Auth Skill Skill

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/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 |

Agent Skills: Better Auth Skill

Install this agent skill to your local

Skill Files