Use Better Auth

Prerequisites

Before writing code, verify better-auth is in the project's lockfile (bun.lock, package-lock.json, pnpm-lock.yaml, yarn.lock, or package.json). If not installed, install with the project's package manager:

bun add better-auth    # or: pnpm add better-auth / npm i better-auth / yarn add better-auth

Verify the ask CLI is available (which ask). It is the primary tool for reading the exact version installed in this project. If ask is not installed, fall back to node_modules/better-auth/ and the official site https://better-auth.com/docs.

Critical: Do Not Trust Internal Knowledge

Everything known about better-auth from training data is suspect. The library's public API, plugin surface, framework adapters, and DB-adapter shapes shift between minor versions. Ship code against the current source, not memory.

When working with better-auth:

1. Resolve the installed version against the local checkout with ask
2. Verify plugin names, adapter imports, and option shapes before generating code
3. Run typecheck after changes to surface silent breakage early
4. Never invent plugin names, adapter import paths, or function signatures — enumerate them first
5. Surface deprecations or conflicts to the user rather than silently picking one pattern

If documentation cannot be found to support an answer, state that explicitly.

Finding Documentation

Resolve the source checkout once; reuse the path across reads:

SRC=$(ask src better-auth)           # checkout root
DOCS=$(ask docs better-auth | head -n1)  # candidate docs dir

Read the README and docs content

cat "$DOCS/README.md"
ls "$SRC/docs/content/docs"
cat "$SRC/docs/content/docs/installation.mdx"
cat "$SRC/docs/content/docs/basic-usage.mdx"

Enumerate plugins (authoritative list)

ls "$SRC/packages/better-auth/src/plugins"

Enumerate framework integrations

ls "$SRC/packages/better-auth/src/integrations"
ls "$SRC/docs/content/docs/integrations"

Note: the source-level integrations/ directory only contains helper functions (Next.js cookies, SvelteKit handler, Node handler, etc.). Most frameworks (Hono, Astro, Express, Nuxt) mount the generic auth.handler directly — check references/adapters.md for the per-framework pattern.

Enumerate DB adapters

ls "$SRC/packages/better-auth/src/adapters"
ls "$SRC/packages" | grep adapter

Enumerate social providers

ls "$SRC/packages/core/src/social-providers"

Grep for exported API

rg "^export " "$SRC/packages/better-auth/src/index.ts"
rg "^export " "$SRC/packages/better-auth/src/client/index.ts"
rg "^export (const|function) createAuthClient" "$SRC/packages/better-auth/src/client/"

Fallback when ask is unavailable

SRC=./node_modules/better-auth
ls $SRC/dist
rg "betterAuth\\(" $SRC/dist

Use the official site https://better-auth.com/docs only to cross-reference — it tracks main, not the installed version.

Environment Variables

Two env vars are resolved inside create-context.ts and utils/url.ts:

• BETTER_AUTH_SECRET — required. At least 32 chars, high entropy. Generate with openssl rand -base64 32 or npx auth secret. Also accepts AUTH_SECRET. For secret rotation without invalidating sessions, use BETTER_AUTH_SECRETS (plural, comma-separated).
• BETTER_AUTH_URL — base URL of the app (e.g. http://localhost:3000). Public variants honored on clients: NEXT_PUBLIC_BETTER_AUTH_URL, PUBLIC_BETTER_AUTH_URL, NUXT_PUBLIC_BETTER_AUTH_URL.

Missing or misconfigured values are the single most common source of runtime errors — see references/common-errors.md.

Server Setup (Canonical Pattern)

Create auth.ts (project root, lib/, utils/, or a src//app//server/-nested equivalent) and export a named or default auth:

import { betterAuth } from "better-auth";

export const auth = betterAuth({
  database: /* DB adapter or Kysely dialect — see references/databases.md */,
  emailAndPassword: {
    enabled: true,
  },
  socialProviders: {
    // github: { clientId: env.GITHUB_CLIENT_ID, clientSecret: env.GITHUB_CLIENT_SECRET },
  },
  plugins: [
    // see references/plugins.md
  ],
});

The default export betterAuth lives in packages/better-auth/src/auth/full.ts and ships the full Kysely runtime. For environments where Kysely is not desired, import from better-auth/minimal and pass a custom adapter (e.g. drizzleAdapter) via database.

Client Setup (Canonical Pattern)

Pick the framework-specific import path. Each one re-exports createAuthClient from packages/better-auth/src/client/<framework>/index.ts:

import { createAuthClient } from "better-auth/react";   // React
import { createAuthClient } from "better-auth/vue";     // Vue / Nuxt
import { createAuthClient } from "better-auth/svelte";  // Svelte / SvelteKit
import { createAuthClient } from "better-auth/solid";   // Solid / Solid Start
import { createAuthClient } from "better-auth/client";  // vanilla (framework-agnostic)

export const authClient = createAuthClient({
  baseURL: process.env.NEXT_PUBLIC_BETTER_AUTH_URL, // or equivalent per framework
  plugins: [
    // mirror any server-side plugins that expose a client plugin
  ],
});

Export the methods the app actually uses (signIn, signUp, signOut, useSession) from the client module rather than re-importing the whole authClient in every component.

Picking the Framework Adapter

Full wiring, cookie handling, and CORS gotchas per framework: references/adapters.md.

Picking Plugins

Server plugins live under packages/better-auth/src/plugins/. Enumerate them before writing imports. Common picks:

Full matrix with decision notes: references/plugins.md.

Picking the DB Adapter

After adding a plugin or changing the schema, regenerate:

npx auth generate     # dumps schema changes
npx auth migrate      # applies them (Kysely built-in only)

Full init snippets and the schema-extension pattern: references/databases.md.

When Typecheck or Runtime Fails

Before searching source code, grep references/common-errors.md for the failing symptom (missing secret, redirect loop, CORS, session not persisted, schema drift, edge-runtime incompatibility). Most runtime failures fall into one of six known categories with a canonical fix.

If the symptom is not listed, resolve the source and grep the error string:

rg -n "error string fragment" "$SRC/packages/better-auth/src"

References

• references/adapters.md — framework-by-framework wiring (Next.js, Nuxt, SvelteKit, Hono, Astro, Express, Bun, TanStack Start, Solid Start)
• references/plugins.md — every built-in plugin with when-to-use, server import, client import
• references/databases.md — Prisma / Drizzle / Kysely / Mongo init, schema generation, model extension
• references/common-errors.md — six concrete error → cause → fix entries