better-auth-nextjs

---
name: better-auth-nextjs
description: Use when wiring email/password, OAuth, 2FA, or passkeys into a Next.js App Router project with Better Auth — covers auth.ts, route handler, client, and session helpers.
source: https://github.com/better-auth/better-auth
generated: 2026-05-17T04:18:12.785Z
category: library
audience: engineers
---

## When to use

- Adding email/password sign-up and sign-in to a Next.js App Router app
- Wiring GitHub or Google OAuth via authClient.signIn.social
- Enabling two-factor authentication with the twoFactor plugin
- Adding passkeys or magic links to an existing Better Auth setup
- Reading the current session on the server with auth.api.getSession
- Migrating from NextAuth/Clerk to a TypeScript-native auth framework

## Key concepts

### betterAuth() server instance

The auth server is created by calling betterAuth({...}) with a database adapter, emailAndPassword config, and socialProviders. It's typically exported from a single auth.ts module and consumed by the route handler, server components, and server actions.

### Next.js route handler

Better Auth mounts onto a catch-all route at /api/auth/[...all]/route.ts using toNextJsHandler(auth), which exports GET and POST. All client SDK calls hit this endpoint, so it must exist before sign-in/sign-up works.

### createAuthClient

The React client is created with createAuthClient from better-auth/react and exposes signIn, signUp, signOut, and the useSession hook. Plugins on the server must have matching client plugins (e.g. twoFactorClient, passkeyClient) registered here.

### Session handling

useSession() returns { data, isPending, error, refetch } on the client. On the server, auth.api.getSession({ headers: await headers() }) reads the cookie-backed session — both must validate against the server, never trust middleware cookie presence alone.

### Plugin system

Features like twoFactor(), passkey(), magicLink(), and organization() are plugins added to the plugins array on betterAuth(). Each plugin contributes endpoints, schema, and client methods, letting you opt into advanced auth (2FA, SSO, OIDC) without forking the framework.

### nextCookies() plugin

Required when calling auth functions from server actions — it ensures cookies set by Better Auth are propagated through Next.js's server action cookie handling so sessions persist after redirect.

## API reference

```
toNextJsHandler(auth) — app/api/auth/[...all]/route.ts
```

Mount the Better Auth server onto a Next.js catch-all route so all client SDK requests resolve.

```
import { auth } from "@/lib/auth";
import { toNextJsHandler } from "better-auth/next-js";

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

```
createAuthClient(config) — lib/auth-client.ts
```

Create the React client used by components to call sign-in, sign-up, and useSession.

```
import { createAuthClient } from "better-auth/react"

export const authClient = createAuthClient({
    //you can pass client configuration here
})
```

```
authClient.signUp.email({ email, password, name, image, callbackURL })
```

Register a new user with email/password and optionally redirect to a callback URL after success.

```
const { data, error } = await authClient.signUp.email({
    email,
    password,
    name,
    image,
    callbackURL: "/dashboard"
}, {
    onRequest: (ctx) => { /*show loading*/ },
    onSuccess: (ctx) => { /*redirect*/ },
    onError: (ctx) => { alert(ctx.error.message); }
});
```

```
authClient.signIn.social({ provider, callbackURL })
```

Start an OAuth flow with a configured provider such as github or google.

```
await authClient.signIn.social({
    provider: "github",
    callbackURL: "/dashboard",
    errorCallbackURL: "/error",
    newUserCallbackURL: "/welcome",
    disableRedirect: true
});
```

```
auth.api.getSession({ headers })
```

Server-side session retrieval inside server components, route handlers, and server actions.

```
const session = await auth.api.getSession({
    headers: await headers()
})
```

```
twoFactor() / twoFactorClient() plugin
```

Add TOTP-based two-factor authentication on server and client.

```
// server
import { twoFactor } from "better-auth/plugins";
export const auth = betterAuth({
    plugins: [ twoFactor() ]
});

// client
import { twoFactorClient } from "better-auth/client/plugins";
const authClient = createAuthClient({
    plugins: [ twoFactorClient({ twoFactorPage: "/two-factor" }) ]
});
```

## Gotchas

- Server actions that set cookies require the nextCookies() plugin — without it the session won't persist through a redirect
- Middleware cookie checks are an optimization only; you must still validate the session on the server for any protected action or page
- Next.js 16 renames middleware to proxy — rename middleware.ts to proxy.ts and run `npx @next/codemod@canary middleware-to-proxy .`
- Server and client plugin lists must match — adding twoFactor() on the server without twoFactorClient() on the client breaks the flow
- auth.api.getSession requires `await headers()` because Next.js App Router headers() is async in current versions
- The catch-all route must live at /api/auth/[...all]/route.ts exactly — any other path will silently 404 client SDK calls

---
Generated by SkillMake from https://github.com/better-auth/better-auth on 2026-05-17T04:18:12.785Z.
Verify against source before relying on details.

File: ~/.claude/skills/better-auth-nextjs/SKILL.md