better-auth

Better Auth Best Practices

Implementation and migration guide for Better Auth, the framework-agnostic TypeScript authentication and authorization library. This skill contains 42 rules organized by impact across 8 categories, derived from the official documentation and migration guides.

When to Apply

Reference these guidelines when:

• Setting up a fresh Better Auth instance (config, adapter, route handler, client)
• Wiring framework-specific integrations (Next.js App/Pages Router, SvelteKit, Hono, Express, Nuxt, Astro)
• Configuring sessions, cookies, and security (rate limit, trusted origins, password hashing)
• Adding plugins: 2FA, organization, admin, magicLink, JWT, passkey, multi-session
• Migrating from another auth library (NextAuth/Auth.js, Clerk, Auth0, Supabase Auth)
• Debugging "session is null" / "redirect_uri_mismatch" / 403 CSRF errors
• Reviewing PRs that touch lib/auth.ts, auth-client.ts, or /api/auth/ route handlers

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Setup & Configuration	CRITICAL	setup-
2	Database Adapters & Schema	CRITICAL	db-
3	API Route Handlers	CRITICAL	route-
4	Session & Cookies	HIGH	session-
5	Auth Methods & Providers	HIGH	auth-
6	Security & Hardening	HIGH	security-
7	Plugins & Extensions	MEDIUM	plugins-
8	Migration from Other Auth	MEDIUM	migrate-

Quick Reference

1. Setup & Configuration (CRITICAL)

• setup-secret — Set a strong BETTER_AUTH_SECRET per environment
• setup-base-url — Configure an explicit baseURL per environment
• setup-client-base-url — Match the client baseURL to the server
• setup-singleton — Export a single auth instance from a server-only module
• setup-trusted-origins — Configure trustedOrigins for all non-baseURL callers

2. Database Adapters & Schema (CRITICAL)

• db-adapter-selection — Pick the adapter that matches your ORM
• db-schema-generate — Run auth generate then ORM migrate before every deploy
• db-additional-fields — Extend the user schema via additionalFields
• db-plugin-schema-customization — Rename plugin tables via the schema option
• db-database-hooks — Use databaseHooks for cross-cutting logic
• db-connection-pooling — Share one pooled DB client with the rest of your app

3. API Route Handlers (CRITICAL)

• route-mount-catchall — Mount the catch-all handler at /api/auth/[...all]
• route-runtime-selection — Use the Node.js runtime for middleware that calls auth.api
• route-no-body-consumers — Mount auth before any body-parsing middleware

4. Session & Cookies (HIGH)

• session-server-vs-client — Use auth.api.getSession on server, authClient.useSession on client
• session-expiry-tuning — Configure expiresIn and updateAge together
• session-cookie-cache — Enable cookieCache to cut session DB lookups
• session-cookie-attributes — Set sameSite, secure, partitioned for cross-site flows
• session-cross-subdomain — Enable crossSubDomainCookies for multi-subdomain apps
• session-customsession-fields — Use customSession to add computed fields

5. Auth Methods & Providers (HIGH)

• auth-require-email-verification — Enable requireEmailVerification with sendVerificationEmail
• auth-oauth-redirect-uri — Match OAuth redirectURI exactly with the provider console
• auth-oauth-env-vars — Load OAuth credentials from environment, never inline
• auth-magic-link-setup — Implement sendMagicLink before enabling the magicLink plugin
• auth-client-sign-in-helpers — Use authClient.signIn.social with callbackURL
• auth-infer-additional-fields — Add inferAdditionalFields to the client for type sync

6. Security & Hardening (HIGH)

• security-rate-limit — Enable rateLimit with persistent storage in production
• security-password-hash-interop — Override hash function when migrating from bcrypt/argon2
• security-revoke-on-password-reset — Enable revokeSessionsOnPasswordReset
• security-min-password-length — Set minPasswordLength to at least 10
• security-trusted-origins-strict — Never wildcard trustedOrigins

7. Plugins & Extensions (MEDIUM)

• plugins-next-cookies-last — Place nextCookies() as the LAST plugin in Next.js
• plugins-two-factor-issuer — Set appName as the 2FA issuer
• plugins-shared-access-control — Define ac + roles once, share server/client
• plugins-pair-client-server — Pair every server plugin with its client counterpart
• plugins-organization-active-context — Set active organization on session
• plugins-jwt-when-to-use — Use the jwt plugin only for external service consumers
• plugins-admin-impersonation — Use admin plugin's impersonate method for support access

8. Migration from Other Auth (MEDIUM)

• migrate-parallel-cutover — Run Better Auth alongside legacy auth during cutover
• migrate-oauth-account-mapping — Map legacy OAuth identities to account rows
• migrate-force-allow-id — Use forceAllowId to preserve existing user IDs
• migrate-nextauth-schema-mapping — Map NextAuth v5 columns field-by-field

How to Use

For a fresh implementation, read in priority order: start with all setup- rules, then db-, then route- — these CRITICAL categories must be correct or nothing else works. After the foundation, pick the rules that match your scope: session- for cookie/expiry tuning, auth- for provider configuration, security- for production hardening.

For a migration from another auth library, read migrate-parallel-cutover first (strategy), then security-password-hash-interop (preserve user passwords), then migrate-oauth-account-mapping and migrate-nextauth-schema-mapping (data layout).

Read individual reference files for detailed explanations, incorrect vs. correct code examples, and links to the canonical Better Auth documentation.

Reference Files

File	Description
references/_sections.md	Category definitions ordered by impact
assets/templates/_template.md	Template for adding new rules
metadata.json	Version, references, and discipline metadata