bun

bun add better-auth


### Basic Setup

See [templates/auth-server.ts](templates/auth-server.ts) for a complete template.

```typescript
// lib/auth.ts
import { betterAuth } from "better-auth";

export const auth = betterAuth({
  database: yourDatabaseAdapter, // See ORM guides below
  emailAndPassword: { enabled: true },
});

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

export const authClient = createAuthClient({
  baseURL: process.env.NEXT_PUBLIC_APP_URL,
});

ORM Integration (Choose One)

IMPORTANT: Always use CLI to generate/migrate schema:

npx @better-auth/cli generate  # See current schema
npx @better-auth/cli migrate   # Create/update tables

ORM	Guide
Drizzle	reference/drizzle.md
Prisma	reference/prisma.md
Kysely	reference/kysely.md
MongoDB	reference/mongodb.md
Direct DB	Use `pg` Pool directly (see templates)

Next.js 16 Integration

API Route

// app/api/auth/[...all]/route.ts
import { auth } from "@/lib/auth";
import { toNextJsHandler } from "better-auth/next-js";

export const { GET, POST } = toNextJsHandler(auth.handler);

Proxy (Replaces Middleware)

In Next.js 16, middleware.ts → proxy.ts:

// proxy.ts
import { NextRequest, NextResponse } from "next/server";
import { auth } from "@/lib/auth";
import { headers } from "next/headers";

export async function proxy(request: NextRequest) {
  const session = await auth.api.getSession({
    headers: await headers(),
  });

  if (!session) {
    return NextResponse.redirect(new URL("/sign-in", request.url));
  }

  return NextResponse.next();
}

export const config = {
  matcher: ["/dashboard/:path*"],
};

Migration: npx @next/codemod@canary middleware-to-proxy .

Server Component

import { auth } from "@/lib/auth";
import { headers } from "next/headers";
import { redirect } from "next/navigation";

export default async function DashboardPage() {
  const session = await auth.api.getSession({
    headers: await headers(),
  });

  if (!session) redirect("/sign-in");

  return <h1>Welcome {session.user.name}</h1>;
}

Authentication Examples

Pattern	Guide
Email/Password	examples/email-password.md
Social OAuth	examples/social-oauth.md
Two-Factor (2FA)	examples/two-factor.md
Magic Link	examples/magic-link.md

Quick Examples

Sign In

const { data, error } = await authClient.signIn.email({
  email: "user@example.com",
  password: "password",
});

Social OAuth

await authClient.signIn.social({
  provider: "google",
  callbackURL: "/dashboard",
});

Sign Out

await authClient.signOut();

Get Session

const session = await authClient.getSession();

Plugins

import { twoFactor, magicLink, jwt, organization } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [
    twoFactor(),
    magicLink({ sendMagicLink: async ({ email, url }) => { /* send email */ } }),
    jwt(),
    organization(),
  ],
});

After adding plugins, always run:

npx @better-auth/cli migrate

Advanced Patterns

See reference/advanced-patterns.md for:

Stateless mode (no database)
Redis session storage
Custom user fields
Rate limiting
Organization hooks
SSO configuration
Multi-tenant setup

Templates

Template	Purpose
templates/auth-server.ts	Server configuration template
templates/auth-client.ts	Client configuration template

Environment Variables

DATABASE_URL=postgresql://user:pass@host:5432/db
NEXT_PUBLIC_APP_URL=http://localhost:3000
BETTER_AUTH_URL=http://localhost:3000
BETTER_AUTH_SECRET=your-secret

# OAuth (as needed)
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...

Error Handling

// Client
const { data, error } = await authClient.signIn.email({ email, password });
if (error) {
  console.error(error.message, error.status);
}

// Server
import { APIError } from "better-auth/api";
try {
  await auth.api.signInEmail({ body: { email, password } });
} catch (error) {
  if (error instanceof APIError) {
    console.log(error.message, error.status);
  }
}

Key Commands

# Generate schema
npx @better-auth/cli generate

# Migrate database
npx @better-auth/cli migrate

# Next.js 16 middleware migration
npx @next/codemod@canary middleware-to-proxy .

Version Info

Docs: https://www.better-auth.com/docs
Releases: https://github.com/better-auth/better-auth/releases

Always check latest docs before implementation - APIs may change between versions.

better-auth-ts

Better Auth TypeScript Skill

Quick Start

Installation