better-auth

Files (47)

• AGENTS.md
• SKILL.md
• _template.md · assets/templates/
• metadata.json
• _sections.md · references/
• auth-client-sign-in-helpers.md · references/
• auth-infer-additional-fields.md · references/
• auth-magic-link-setup.md · references/
• auth-oauth-env-vars.md · references/
• auth-oauth-redirect-uri.md · references/
• auth-require-email-verification.md · references/
• db-adapter-selection.md · references/
• db-additional-fields.md · references/
• db-connection-pooling.md · references/
• db-database-hooks.md · references/
• db-plugin-schema-customization.md · references/
• db-schema-generate.md · references/
• migrate-force-allow-id.md · references/
• migrate-nextauth-schema-mapping.md · references/
• migrate-oauth-account-mapping.md · references/
• migrate-parallel-cutover.md · references/
• plugins-admin-impersonation.md · references/
• plugins-jwt-when-to-use.md · references/
• plugins-next-cookies-last.md · references/
• plugins-organization-active-context.md · references/
• plugins-pair-client-server.md · references/
• plugins-shared-access-control.md · references/
• plugins-two-factor-issuer.md · references/
• route-mount-catchall.md · references/
• route-no-body-consumers.md · references/
• route-runtime-selection.md · references/
• security-min-password-length.md · references/
• security-password-hash-interop.md · references/
• security-rate-limit.md · references/
• security-revoke-on-password-reset.md · references/
• security-trusted-origins-strict.md · references/
• session-cookie-attributes.md · references/
• session-cookie-cache.md · references/
• session-cross-subdomain.md · references/
• session-customsession-fields.md · references/
• session-expiry-tuning.md · references/
• session-server-vs-client.md · references/
• setup-base-url.md · references/
• setup-client-base-url.md · references/
• setup-secret.md · references/
• setup-singleton.md · references/
• setup-trusted-origins.md · references/

SKILL.md (first lines)

# Better Auth Best Practices

Implementation and migration guide for [Better Auth](https://www.better-auth.com), 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`](references/setup-secret.md) — Set a strong `BETTER_AUTH_SECRET` per environment
- [`setup-base-url`](references/setup-base-url.md) — Configure an explicit `baseURL` per environment
- [`setup-client-base-url`](references/setup-client-base-url.md) — Match the client `baseURL` to the server
- [`setup-singleton`](references/setup-singleton.md) — Export a single auth instance from a server-only module
- [`setup-trusted-origins`](references/setup-trusted-origins.md) — Configure `trustedOrigins` for all non-baseURL callers

### 2. Database Adapters & Schema (CRITICAL)

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

### 3. API Route Handlers (CRITICAL)

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

### 4. Session & Cookies (HIGH)

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

### 5. Auth Methods & Providers (HIGH)

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

### 6. Security & Hardening (HIGH)

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

### 7. Plugins & Extensions (MEDIUM)

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

### 8. Migration from Other Auth (MEDIUM)

- [`migrate-parallel-cutover`](references/migrate-parallel-cutover.md) — Run Better Auth alongside legacy auth during cutover
- [`migrate-oauth-account-mapping`](references/migrate-oauth-account-mapping.md) — Map legacy OAuth identities to `account` rows
- [`migrate-force-allow-id`](references/migrate-force-allow-id.md) — Use `forceAllowId` to preserve existing user IDs
- [`migrate-nextauth-schema-mapping`](references/migrate-nextauth-schema-mapping.md) — 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](references/_sections.md) | Category definitions ordered by impact |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for adding new rules |
| [metadata.json](metadata.json) | Version, references, and discipline metadata |

From pproenca/dot-skills, MIT.

More from pproenca/dot-skills