better-auth

• 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.)

Installation

```bash

npm install better-auth

# or pnpm/yarn/bun add better-auth

```

Environment Setup

Create .env:

```env

BETTER_AUTH_SECRET=

BETTER_AUTH_URL=http://localhost:3000

```

Basic Server Setup

Create auth.ts (root, lib/, utils/, or under src/app/server/):

```ts

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

```bash

npx @better-auth/cli generate # Generate schema/migrations

npx @better-auth/cli migrate # Apply migrations (Kysely only)

```

Mount API Handler

Next.js App Router:

```ts

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

```ts

import { createAuthClient } from "better-auth/client";

export const authClient = createAuthClient({

baseURL: process.env.NEXT_PUBLIC_BETTER_AUTH_URL || "http://localhost:3000"

});

```

Basic Usage

```ts

// 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 | Plugin Required | Use Case | Reference |

|---------|----------------|----------|-----------|

| Email/Password | No (built-in) | Basic auth | [email-password-auth.md](./references/email-password-auth.md) |

| OAuth (GitHub, Google, etc.) | No (built-in) | Social login | [oauth-providers.md](./references/oauth-providers.md) |

| Email Verification | No (built-in) | Verify email addresses | [email-password-auth.md](./references/email-password-auth.md#email-verification) |

| Password Reset | No (built-in) | Forgot password flow | [email-password-auth.md](./references/email-password-auth.md#password-reset) |

| Two-Factor Auth (2FA/TOTP) | Yes (twoFactor) | Enhanced security | [advanced-features.md](./references/advanced-features.md#two-factor-authentication) |

| Passkeys/WebAuthn | Yes (passkey) | Passwordless auth | [advanced-features.md](./references/advanced-features.md#passkeys-webauthn) |

| Magic Link | Yes (magicLink) | Email-based login | [advanced-features.md](./references/advanced-features.md#magic-link) |

| Username Auth | Yes (username) | Username login | [email-password-auth.md](./references/email-password-auth.md#username-authentication) |

| Organizations/Multi-tenant | Yes (organization) | Team/org features | [advanced-features.md](./references/advanced-features.md#organizations) |

| Rate Limiting | No (built-in) | Prevent abuse | [advanced-features.md](./references/advanced-features.md#rate-limiting) |

| Session Management | No (built-in) | User sessions | [advanced-features.md](./references/advanced-features.md#session-management) |

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)

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

• [ ] 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

Core Authentication

• [Email/Password Authentication](./references/email-password-auth.md) - Email/password setup, verification, password reset, username auth
• [OAuth Providers](./references/oauth-providers.md) - Social login setup, provider configuration, token management
• [Database Integration](./references/database-integration.md) - Database adapters, schema setup, migrations

Advanced Features

• [Advanced Features](./references/advanced-features.md) - 2FA/MFA, passkeys, magic links, organizations, rate limiting, session management

• scripts/better_auth_init.py - Initialize Better Auth configuration with interactive setup

• 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