Agent-Skills.md

Agent Skills: Better Auth - Complete Authentication

Complete Better Auth - 40+ OAuth providers, 20+ plugins, all adapters, all frameworks. Use when implementing authentication, login, OAuth, 2FA, magic links, SSO, Stripe, SCIM, or session management.

UncategorizedID: fusengine/agents/better-auth

Repository

fusengine/agents
fusengineLicense: MIT
7

Install this agent skill to your local

pnpm dlx add-skill https://github.com/fusengine/agents/tree/HEAD/plugins/nextjs-expert/skills/better-auth

Skill Files

Browse the full folder contents for better-auth.

Download Skill

Loading file tree…

plugins/nextjs-expert/skills/better-auth/SKILL.md

Skill Metadata

Name
better-auth
Description
Use when implementing Next.js authentication with Better Auth — OAuth, 2FA, magic links, SSO, Stripe billing, or session management.
<objective> Implements Better Auth, a TypeScript-first authentication library, in a Next.js 16 App Router project: server config, client (`createAuthClient`), session management, and the `app/api/auth/[...all]/route.ts` handler, plus `proxy.ts` for route protection (replacing middleware).

Covers the full surface — 40+ OAuth providers (Google, GitHub, Discord, Apple, Microsoft, and more), 20+ plugins (2FA, magic links, passkeys, organizations/multi-tenant, enterprise SSO/SAML, SCIM provisioning, Stripe/Polar billing, JWT/Bearer, API keys), and database adapters (Prisma, Drizzle, MongoDB, raw SQL). Also covers migration paths from Auth.js, Clerk, Auth0, Supabase, and WorkOS. While Better Auth itself is framework-agnostic, this skill's architecture guidance (proxy.ts, App Router API route) is Next.js-specific — for Prisma schema/query details see prisma-7. </objective>

Better Auth - Complete Authentication

TypeScript-first authentication library with 40+ OAuth providers and 20+ plugins.

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:

  1. fuse-ai-pilot:explore-codebase - Analyze existing auth setup and patterns
  2. fuse-ai-pilot:research-expert - Verify latest Better Auth docs via Context7/Exa
  3. mcp__context7__query-docs - Check providers/plugins availability

After implementation, run fuse-ai-pilot:sniper for validation.

Overview

When to Use

  • Implementing authentication in TypeScript/JavaScript applications
  • Need OAuth providers (Google, GitHub, Discord, Apple, Microsoft, etc.)
  • Adding 2FA, magic links, passkeys, or phone authentication
  • Enterprise SSO with SAML, SCIM provisioning, or organizations
  • Integrating payments with Stripe or Polar subscriptions
  • Web3 authentication with Sign-In with Ethereum (SIWE)
  • Migrating from Auth.js, Clerk, Auth0, Supabase, or WorkOS

Why Better Auth

| Feature | Benefit | |---------|---------| | Framework agnostic | Next.js, SvelteKit, Nuxt, Remix, Astro, Expo, NestJS | | Plugin architecture | Add only the features you need (20+ plugins) | | Full TypeScript | End-to-end type safety, inference included | | Self-hosted | Your data stays on your infrastructure | | Database flexible | Prisma, Drizzle, MongoDB, PostgreSQL, MySQL, SQLite | | Enterprise ready | SSO, SCIM, organizations, audit logs |

Version Notes (current stable: 1.7.x)

| Since | Change | |-------|--------| | 1.5 | Standalone CLI npx auth@latest (generate, migrate, secret, init, check…) replaces @better-auth/cli; OAuth 2.1 Provider (@better-auth/oauth-provider) | | 1.6 | session.freshAge computed from createdAt; oidcProvider deprecated | | 1.7 | oidcProvider removed; generic OAuth providers use signIn.social (no genericOAuthClient); DB joins via advanced.database.joins; accounts keyed on (issuer, accountId); twoFactor.enable returns a method-discriminated response; MCP → @better-auth/mcp; SCIM decoupled from organization |

After upgrading to 1.7, regenerate the schema (npx auth@latest generate) and follow the official 1.7 upgrade guide.

Coverage

OAuth Providers (40+)

Google, GitHub, Discord, Apple, Microsoft, Slack, Spotify, Twitter/X, Facebook, LinkedIn, GitLab, Bitbucket, Dropbox, Twitch, Reddit, TikTok, and 25+ more documented in providers/.

Plugins (20+)

| Plugin | Purpose | |--------|---------| | 2FA | TOTP authenticator, backup codes | | Magic Link | Passwordless email login | | Passkey | WebAuthn biometric authentication | | Organization | Multi-tenant, roles, invitations | | SSO | Enterprise SAML/OIDC single sign-on | | SCIM | Directory sync, user provisioning | | Stripe | Subscription billing integration | | API Key | Machine-to-machine authentication | | JWT/Bearer | Token-based API authentication |

Database Adapters

Prisma, Drizzle, MongoDB, raw SQL (PostgreSQL, MySQL, SQLite), and community adapters.

SOLID Architecture (Next.js 16)

Components organized in modules/auth/ following separation of concerns:

  • Services: betterAuth configuration and initialization
  • Hooks: createAuthClient for client-side auth state
  • API Route: app/api/auth/[...all]/route.ts handler
  • Proxy: proxy.ts for route protection (replaces middleware)

Reference Guide

| Need | Reference | |------|-----------| | Initial setup | installation.md, server-config.md | | Client usage | client.md, session.md | | OAuth providers | providers/overview.md, individual provider docs | | Add plugins | plugins/overview.md, individual plugin docs | | Database setup | adapters/prisma.md, adapters/drizzle.md | | Enterprise SSO | plugins/sso.md, guides/saml-okta.md | | Payments | plugins/stripe.md, plugins/polar.md | | Migration | guides/clerk-migration.md, other migration guides | | Complete examples | examples/ for full implementations |

Best Practices

  1. Plugins on demand - Only add plugins you actually need
  2. Type-safe client - Use generated types from server config
  3. Session caching - Enable session caching for performance
  4. Rate limiting - Configure rate limits for auth endpoints
  5. Secure cookies - Use secure, httpOnly, sameSite cookies
  6. Database indexes - Add indexes on user lookup fields

Concepts

Core concepts explained in concepts/:

  • Sessions - Token management, refresh, revocation
  • Database - Schema design, migrations, adapters
  • Plugins - Extension system, composition
  • OAuth - Provider configuration, callbacks
  • Security - CSRF, rate limiting, password hashing
  • Cookies - Session storage, cross-domain