Better Auth conventions

One server instance

• Create a single export const auth = betterAuth({ … }) in lib/auth.ts. It's the source of truth for sessions, providers, and plugins.
• The auth instance is server-only — never import it into client components or ship it to the browser.

Configuration & secrets

• Read secrets from the environment: BETTER_AUTH_SECRET, BETTER_AUTH_URL. Never hardcode them.
• Enable auth methods explicitly (emailAndPassword, socialProviders.*), and keep provider client IDs/secrets in env.

Database

• Use a database adapter that matches your stack (drizzleAdapter, prismaAdapter, …).
• Generate the auth schema with npx @better-auth/cli generate, then apply it through your own migration tool. Don't hand-edit the generated auth tables.

Mounting & client

• Mount the handler once. In Next App Router: app/api/auth/[...all]/route.ts exporting toNextJsHandler(auth).
• Build the client with createAuthClient() from better-auth/react. For each server-side plugin, add its client counterpart so types and calls line up.
• nextCookies() must be the last plugin in the array so cookies are set from server actions.

Sessions

• On the server, read the session with auth.api.getSession({ headers: await headers() }). Pass the request headers — don't parse cookies manually.
• On the client, use the auth client's useSession() / getSession().

Extending

• Add capabilities (twoFactor, passkey, organization, magicLink, admin, …) through official plugins instead of bespoke auth code.

Anti-patterns

• ❌ Importing the server auth instance into client code.
• ❌ Hardcoded secrets instead of BETTER_AUTH_SECRET / env.
• ❌ Reading/parsing the session cookie by hand instead of auth.api.getSession.
• ❌ nextCookies() placed anywhere but last.
• ❌ Hand-writing auth tables instead of the CLI-generated schema.