--- name: better-auth-bdf843e14e06 description: Implement authentication and authorization with Better Auth - a framework-agnostic TypeScript authentication framework. Features include email/password authentication with verification, OAuth providers (Google, GitHub, Discord, etc.), two-factor authentication (TOTP, SMS), passkeys/WebAuthn support, session management, role-based access control (RBAC), rate limiting, and database adapters. Use when adding authentication to applications, implementing OAuth flows, setting up 2FA/MFA, managing user sessions, configuring authorization rules, or building secure authentication systems for web applications. license: MIT version: 2.0.0 --- # Better Auth Skill Better Auth is comprehensive, framework-agnostic authentication/authorization framework for TypeScript with built-in email/password, social OAuth, and powerful plugin ecosystem for advanced features. ## When to Use - Implementing auth in TypeScript/JavaScript applications - Adding email/password or social OAuth authentication - Setting up 2FA, passkeys, magic links, advanced auth features - Building multi-tenant apps with organization support - Managing sessions and user lifecycle - Working with any framework (Next.js, Nuxt, SvelteKit, Remix, Astro, Hono, Express, etc.) ## Quick Start ### Installation ```bash npm install better-auth # or pnpm/yarn/bun add better-auth ``` ### Environment Setup Create `.env`: ```env BETTER_AUTH_SECRET= BETTER_AUTH_URL=http://localhost:3000 ``` ### Basic Server Setup Create `auth.ts` (root, lib/, utils/, or under src/app/server/): ```ts import { betterAuth } from "better-auth"; export const auth = betterAuth({ database: { // See references/database-integration.md }, emailAndPassword: { enabled: true, autoSignIn: true }, socialProviders: { github: { clientId: process.env.GITHUB_CLIENT_ID!, clientSecret: process.env.GITHUB_CLIENT_SECRET!, } } }); ``` ### Database Schema ```bash npx @better-auth/cli generate # Generate schema/migrations npx @better-auth/cli migrate # Apply migrations (Kysely only) ``` ### Mount API Handler **Next.js App Router:** ```ts // app/api/auth/[...all]/route.ts import { auth } from "@/lib/auth"; import { toNextJsHandler } from "better-auth/next-js"; export const { POST, GET } = toNextJsHandler(auth); ``` **Other frameworks:** See references/email-password-auth.md#framework-setup ### Client Setup Create `auth-client.ts`: ```ts import { createAuthClient } from "better-auth/client"; export const authClient = createAuthClient({ baseURL: process.env.NEXT_PUBLIC_BETTER_AUTH_URL || "http://localhost:3000" }); ``` ### Basic Usage ```ts // Sign up await authClient.signUp.email({ email: "user@example.com", password: "secure123", name: "John Doe" }); // Sign in await authClient.signIn.email({ email: "user@example.com", password: "secure123" }); // OAuth await authClient.signIn.social({ provider: "github" }); // Session const { data: session } = authClient.useSession(); // React/Vue/Svelte const { data: session } = await authClient.getSession(); // Vanilla JS ``` ## Feature Selection Matrix | Feature | Plugin Required | Use Case | Reference | |---------|----------------|----------|-----------| | Email/Password | No (built-in) | Basic auth | [email-password-auth.md](./references/email-password-auth.md) | | OAuth (GitHub, Google, etc.) | No (built-in) | Social login | [oauth-providers.md](./references/oauth-providers.md) | | Email Verification | No (built-in) | Verify email addresses | [email-password-auth.md](./references/email-password-auth.md#email-verification) | | Password Reset | No (built-in) | Forgot password flow | [email-password-auth.md](./references/email-password-auth.md#password-reset) | | Two-Factor Auth (2FA/TOTP) | Yes (`twoFactor`) | Enhanced security | [advanced-features.md](./references/advanced-features.md#two-factor-authentication) | | Passkeys/WebAuthn | Yes (`passkey`) | Passwordless auth | [advanced-features.md](./references/advanced-features.md#passkeys-webauthn) | | Magic Link | Yes (`magicLink`) | Email-based login | [advanced-features.md](./references/advanced-features.md#magic-link) | | Username Auth | Yes (`username`) | Username login | [email-password-auth.md](./references/email-password-auth.md#username-authentication) | | Organizations/Multi-tenant | Yes (`organization`) | Team/org features | [advanced-features.md](./references/advanced-features.md#organizations) | | Rate Limiting | No (built-in) | Prevent abuse | [advanced-features.md](./references/advanced-features.md#rate-limiting) | | Session Management | No (built-in) | User sessions | [advanced-features.md](./references/advanced-features.md#session-management) | ## Auth Method Selection Guide **Choose Email/Password when:** - Building standard web app with traditional auth - Need full control over user credentials - Targeting users who prefer email-based accounts **Choose OAuth when:** - Want quick signup with minimal friction - Users already have social accounts - Need access to social profile data **Choose Passkeys when:** - Want passwordless experience - Targeting modern browsers/devices - Security is top priority **Choose Magic Link when:** - Want passwordless without WebAuthn complexity - Targeting email-first users - Need temporary access links **Combine Multiple Methods when:** - Want flexibility for different user preferences - Building enterprise apps with various auth requirements - Need progressive enhancement (start simple, add more options) ## Core Architecture Better Auth uses client-server architecture: 1. **Server** (`better-auth`): Handles auth logic, database ops, API routes 2. **Client** (`better-auth/client`): Provides hooks/methods for frontend 3. **Plugins**: Extend both server/client functionality ## Implementation Checklist - [ ] Install `better-auth` package - [ ] Set environment variables (SECRET, URL) - [ ] Create auth server instance with database config - [ ] Run schema migration (`npx @better-auth/cli generate`) - [ ] Mount API handler in framework - [ ] Create client instance - [ ] Implement sign-up/sign-in UI - [ ] Add session management to components - [ ] Set up protected routes/middleware - [ ] Add plugins as needed (regenerate schema after) - [ ] Test complete auth flow - [ ] Configure email sending (verification/reset) - [ ] Enable rate limiting for production - [ ] Set up error handling ## Reference Documentation ### Core Authentication - [Email/Password Authentication](./references/email-password-auth.md) - Email/password setup, verification, password reset, username auth - [OAuth Providers](./references/oauth-providers.md) - Social login setup, provider configuration, token management - [Database Integration](./references/database-integration.md) - Database adapters, schema setup, migrations ### Advanced Features - [Advanced Features](./references/advanced-features.md) - 2FA/MFA, passkeys, magic links, organizations, rate limiting, session management ## Scripts - `scripts/better_auth_init.py` - Initialize Better Auth configuration with interactive setup ## Resources - Docs: https://www.better-auth.com/docs - GitHub: https://github.com/better-auth/better-auth - Plugins: https://www.better-auth.com/docs/plugins - Examples: https://www.better-auth.com/docs/examples --- Source attribution: ngxtm Original project: https://github.com/ngxtm/devkit/blob/9439f27ce3fa7fe53ff9278a1ee9a44bffa70eba/skills/better-auth/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2024 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: ngxtm Original project: https://github.com/ngxtm/devkit/blob/9439f27ce3fa7fe53ff9278a1ee9a44bffa70eba/skills/better-auth/SKILL.md Attribution basis: Source repository record Fields of work: Development & Engineering, Product Management Roles: Backend Developer, Full-Stack Developer, Growth Product Manager, Product Manager, Technical Product Manager Specialties: API, Backend, Cross Platform Tools: Better Auth Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 4bd40165f1cd808c982112403a87c7f90974ce3bb3119c778ae6faaad29f1b15