better-auth-overview-and-setup

Better Auth Overview And Setup

Use this skill for first-time Better Auth setup and top-level architecture choices.

Scope

• installing better-auth
• configuring BETTER_AUTH_SECRET and BETTER_AUTH_URL
• mounting the auth handler in the target framework
• creating the auth client
• choosing between email/password, social auth, or plugins
• deciding when a task belongs to sessions, OAuth, Next.js, or plugin-specific work

Default path

1. Install better-auth in the server boundary and client boundary if they are separate.
2. Configure a high-entropy BETTER_AUTH_SECRET and the correct app base URL.
3. Create the server auth instance with betterAuth(...).
4. Mount the handler at the framework's auth route.
5. Create the client with createAuthClient(...) and the right baseURL or basePath.
6. Turn on only the auth methods the app actually needs.
7. If the task introduces plugins, plan for both server plugin wiring and client plugin wiring.

When to deviate

• Customize the auth route only if the host framework or an existing app convention truly requires it.
• Move to the Next.js skill when the work is mostly route protection or App Router integration.
• Move to the social or plugin skills when the task introduces providers, organizations, SSO, or plugin-specific contracts.
• Treat dynamic base URL handling as required when previews, multi-domain setups, or changing origins are in play.

Guardrails

• Keep secrets server-only.
• Do not guess the deployed base URL when previews or custom domains are involved.
• Keep the auth route stable unless there is a strong reason to customize it.
• Treat Better Auth as the auth boundary for sessions and provider callbacks instead of hand-rolling adjacent routes.
• Use the official client package for the target environment (client, react, etc.) when hooks or reactive helpers are needed.

Common Routing Cues

• Better Auth installation, betterAuth, createAuthClient, BETTER_AUTH_SECRET, BETTER_AUTH_URL, auth route setup, base URL, base path, auth handler