better-auth trained

mental model

An auth change joins identity proof, session storage, browser origins, database schema, and application authorization. Read the resolved better-auth version and its matching documentation before reusing guide examples. The official installation guide describes the core server/client setup and schema commands.

examples

Minimal documented SQLite server configuration, with the required secret and URL provided by environment. Install better-auth and better-sqlite3 in the owning package, then run its schema migration:

import { betterAuth } from "better-auth";
import Database from "better-sqlite3";

export const auth = betterAuth({
  database: new Database("database.sqlite"),
  emailAndPassword: { enabled: true },
});

This is documentation-backed syntax, not a local runtime integration test (installation, SQLite adapter).

best practices

Keep BETTER_AUTH_SECRET private, configure the public base URL and exact trusted origins, and retain default CSRF checks (security reference).
Use the documented CLI for the installed version: migrate applies schema directly with the built-in Kysely adapter; other adapters use generate and their own migration tool (CLI).
Verify the whole sign-in path: handler request, cookie, persisted session, server-side authorization, sign-out, and rejected origin.
Configure IP headers only for a trusted proxy chain. Untrusted forwarded values can weaken rate limiting (rate limit).

strengths

One library supplies email/password, social login, sessions, and plugins with framework-native handlers. A single auth instance can keep those contracts aligned.

weaknesses / pain points

Adapter schema and plugin versions move independently of application code. Browser cookies, callback URLs, and proxy headers are deployment-specific; a compile pass does not prove a login works.

gotchas

The security guide says a 10-second global rate-limit window; current official rate-limit docs say 60 seconds and 100 requests in production. Its option reference still lists 10 seconds, so read the installed version's implementation and set explicit policy where it matters (rate limit, options).
The best-practices guide says plugin imports must use dedicated paths; the official two-factor example uses better-auth/plugins. Follow the installed package exports (basic usage).
The create-auth guide requires a blanket planning confirmation; infer routine setup from project evidence and ask only for product choices that remain genuinely unresolved.
Use Better Auth's documented configuration and CLI; a parallel setup generator would obscure the installed package's contract.

known bugs

No version-specific defect is documented. Record defects with an upstream issue and a reproduced affected version.

troubleshooting

observed symptom	root cause	fix
the guides disagree on rate-limit defaults	snapshots of different documentation versions	inspect resolved version and configure policy explicitly
the guides disagree on plugin import paths	upstream and derived advice diverged	use package exports and version-matched official example

practiced cases

The conflicts in the gotchas section were verified against the official CLI, rate-limit, security, and plugin documentation for the current release. No app sign-in flow was run, so this guide remains unproven on a real project task.

sources

The feature guide, configuration, security, and scaffolding topics each carry their own primary documentation links.

Read the better-auth guide.