Better Auth
Use this skill for self-hosted TypeScript authentication with Better Auth (better-auth@1.6.25): server instance, client SDK, plugins, adapters, framework mounts, and security.
Workflow
- Inspect the local surface:
- Core:
better-auth(snapshot 1.6.25). CLI:bunx auth@latest(packageauth@1.6.25) — not stale@better-auth/cli@1.4.x. - Env:
BETTER_AUTH_SECRET(≥32),BETTER_AUTH_URL/baseURL,trustedOrigins. - Database: Kysely/pool vs Drizzle/Prisma/Mongo adapter; secondary storage (Redis).
- Plugins: server + matching client plugins; schema generated after changes.
- Mount:
/api/auth/*(defaultbasePath) viaauth.handler/ framework helper.
- Core:
- For day-to-day setup, follow usage-guide.md first.
- Refresh docs when versions drift. Start from source-map.md.
- Route deeper detail:
- Plugins & scoped packages: plugins-ecosystem.md.
- Schema, adapters, CLI: adapters-schema.md.
- Framework mounts & clients: frameworks-client.md.
- Security, sessions, patterns: security-patterns.md.
- Align every installed
@better-auth/*at 1.6.x with core (except separate lines:utils,infra,agent-auth, betacimd). Prefer scoped adapters when optimizing (better-auth/minimal). - Verify with session smoke (
auth.api.getSession), sign-in/out, plugin schema migrate, and production secret/origins checks.
Core Judgment
- Cookie DB sessions by default — not JWT. Use
jwt/bearer/ API keys only when cookies aren’t enough. - Singleton
authinlib/auth.ts(named export helps CLI discovery). Separateauth-client.ts. - Server:
auth.api.*with real request headers. Client:createAuthClient+ framework entry (better-auth/react, …). - Most features are plugins: register server + client, then
bunx auth@latest generate(ORM) ormigrate(Kysely). - Passkey / API key / SSO / SCIM / OAuth-provider / Stripe / Expo are scoped packages — don’t invent old
better-auth/pluginsimport paths for those. - Prefer
@better-auth/oauth-providerover legacy built-inoidcProvider. - Never treat middleware cookie presence as auth — validate session. Don’t disable CSRF/origin checks to “fix” CORS.
- Rate limit is off/weak in dev; memory storage fails on multi-instance — use Redis/DB in prod.
- Prefer
bun/bunxin command examples.
Verification
Prefer repository-owned commands. Cover the relevant subset:
bun pm ls better-authand matching@better-auth/*versions.bunx auth@latest info/secretas needed; schemagenerate/migrateafter plugin changes.- Smoke: mount handler,
getSession, email or social sign-in, sign-out. - Plugins: client methods resolve; org/2FA/passkey flows if enabled.
- Prod:
baseURL, secret length,trustedOrigins, HTTPS cookies, rate-limit storage. - Security: roles/
additionalFieldswithinput: false; notestUtilsin prod config.
Report which checks ran, which did not, and version assumptions that remain.