better-auth（Better Auth 认证）

Better Auth Integration Guide

Overview

Better Auth is a type-safe authentication framework for TypeScript supporting multiple providers, 2FA, SSO, organizations, and passkeys. This skill covers integration patterns for NestJS backend with Drizzle ORM + PostgreSQL and Next.js App Router frontend.

When to Use

• Setting up Better Auth with NestJS backend
• Integrating Next.js App Router frontend
• Configuring Drizzle ORM schema with PostgreSQL
• Implementing social login (GitHub, Google, Facebook, Microsoft)
• Adding MFA/2FA with TOTP, passkey passwordless auth, or magic links
• Managing trusted devices and backup codes for account recovery
• Building multi-tenant apps with organizations or SSO
• Creating protected routes with session management

Quick Start

Installation

# Backend (NestJS)
npm install better-auth @auth/drizzle-adapter drizzle-orm pg
npm install -D drizzle-kit

# Frontend (Next.js)
npm install better-auth

4-Phase Setup

1. Database: Install Drizzle, configure schema, run migrations
2. Backend: Create Better Auth instance with NestJS module
3. Frontend: Configure auth client, create pages, add middleware
4. Plugins: Add 2FA, passkey, organizations as needed

See references/nestjs-setup.md for complete backend setup, references/plugins.md for plugin configuration.

Instructions

Phase 1: Database Setup

1. Install dependencies npm install drizzle-orm pg @auth/drizzle-adapter better-auth npm install -D drizzle-kit
2. Create Drizzle config (drizzle.config.ts) import {defineConfig} from 'drizzle-kit'; export default defineConfig({schema: './src/auth/schema.ts', out: './drizzle', dialect: 'postgresql', dbCredentials: {url: process.env.DATABASE_URL!},});
3. Generate and run migrations npx drizzle-kit generate npx drizzle-kit migrate Checkpoint: Verify tables created: psql $DATABASE_URL -c "\dt" should show user, account, session, verification_token tables.

Phase 2: Backend Setup (NestJS)

1. Create database module - Set up Drizzle connection service
2. Configure Better Auth instance // src/auth/auth.instance.ts import {betterAuth} from 'better-auth'; import {drizzleAdapter} from '@auth/drizzle-adapter'; import * as schema from './schema'; export const auth = betterAuth({database: drizzleAdapter(schema, {provider: 'postgresql'}), emailAndPassword: {enabled: true}, socialProviders: {github: {clientId: process.env.AUTH_GITHUB_CLIENT_ID!, clientSecret: process.env.AUTH_GITHUB_CLIENT_SECRET!,}}});
3. Create auth controller @Controller('auth') export class AuthController {@All('*') async handleAuth(@Req() req: Request, @Res() res: Response) {return auth.handler(req);}} Checkpoint: Test endpoint GET /auth/get-session returns {session: null} when unauthenticated (no error).

Phase 3: Frontend Setup (Next.js)

1. Configure auth client (lib/auth.ts) import {createAuthClient} from 'better-auth/client'; export const authClient = createAuthClient({baseURL: process.env.NEXT_PUBLIC_APP_URL!});
2. Add middleware (middleware.ts) import {auth} from '@/lib/auth'; export default auth((req) => {if (!req.auth && req.nextUrl.pathname.startsWith('/dashboard')) {return Response.redirect(new URL('/sign-in', req.nextUrl.origin));}}); export const config = {matcher: ['/dashboard/:path*']};
3. Create sign-in page with form or social buttons Checkpoint: Navigating to /dashboard when logged out should redirect to /sign-in.

Phase 4: Advanced Features

Add plugins from references/plugins.md:

• 2FA: twoFactor({issuer: 'AppName', otpOptions: {sendOTP}})
• Passkey: passkey({rpID: 'domain.com', rpName: 'App'})
• Organizations: organization({avatar: {enabled: true}})
• Magic Link: magicLink({sendMagicLink})
• SSO: sso({saml: {enabled: true}}) Checkpoint: After adding plugins, re-run migrations and verify new tables exist.

Examples

Example 1: Server Component with Session

Input: Display user data in a Next.js Server Component.

// app/dashboard/page.tsx
import { auth } from '@/lib/auth';
import { redirect } from 'next/navigation';

export default async function DashboardPage() {
  const session = await auth();

  if (!session) {
    redirect('/sign-in');
  }

  return (
    <div>
      <h1>Welcome, {session.user.name}</h1>
      <p>Email: {session.user.email}</p>
    </div>
  );
}

Output: Renders user info for authenticated users; redirects unauthenticated to sign-in.

Example 2: 2FA TOTP Verification with Trusted Device

Input: User has 2FA enabled and wants to sign in, marking device as trusted.

// Server: Configure 2FA with OTP sending
export const auth = betterAuth({
  plugins: [
    twoFactor({
      issuer: 'MyApp',
      otpOptions: {
        async sendOTP({ user, otp }, ctx) {
          await sendEmail({
            to: user.email,
            subject: 'Your verification code',
            body: `Code: ${otp}`
          });
        }
      }
    })
  ]
});

// Client: Verify TOTP and trust device
const verify2FA = async (code: string) => {
  const { data } = await authClient.twoFactor.verifyTotp({
    code,
    trustDevice: true  // Device trusted for 30 days
  });

  if (data) {
    router.push('/dashboard');
  }
};

Output: User authenticated; device trusted for 30 days without 2FA prompt.

Example 3: Passkey Registration and Login

Input: Enable passkey (WebAuthn) authentication for passwordless login.

// Server
import { passkey } from '@better-auth/passkey';
export const auth = betterAuth({
  plugins: [
    passkey({
      rpID: 'example.com',
      rpName: 'My App',
    })
  ]
});

// Client: Register passkey
const registerPasskey = async () => {
  const { data } = await authClient.passkey.register({
    name: 'My Device'
  });
};

// Client: Sign in with autofill
const signInWithPasskey = async () => {
  await authClient.signIn.passkey({
    autoFill: true,  // Browser suggests passkey
  });
};

Output: Users can register and authenticate with biometrics, PIN, or security keys.

For more examples (backup codes, organizations, magic link, conditional UI), see references/plugins.md and references/passkey.md.

Best Practices

1. Environment Variables: Store all secrets in .env, add to .gitignore
2. Secret Generation: Use openssl rand -base64 32 for BETTER_AUTH_SECRET
3. HTTPS Required: OAuth callbacks need HTTPS (use ngrok for local testing)
4. Session Expiration: Configure based on security requirements (7 days default)
5. Database Indexing: Add indexes on email, userId for performance
6. Error Handling: Return generic errors without exposing sensitive details
7. Rate Limiting: Add to auth endpoints to prevent brute force attacks
8. Type Safety: Use npx better-auth typegen for full TypeScript coverage

Constraints and Warnings

Security Notes

• Never commit secrets: Add .env to .gitignore; never commit OAuth secrets or DB credentials
• Validate redirect URLs: Always validate OAuth redirect URLs to prevent open redirects
• Hash passwords: Better Auth handles password hashing automatically; never implement custom hashing
• Session storage: For production, use Redis or another scalable session store
• HTTPS Only: Always use HTTPS for authentication in production
• Email Verification: Always implement email verification for password-based auth

Known Limitations

• Better Auth requires Node.js 18+ for Next.js App Router support
• Some OAuth providers require specific redirect URL formats
• Passkeys require HTTPS and compatible browsers
• Organization features require additional database tables

Resources

Documentation

• Better Auth - Official documentation
• Drizzle ORM - Database ORM
• NestJS - Backend framework
• Next.js - Frontend framework

Reference Implementations

• references/nestjs-setup.md - Complete NestJS backend setup
• references/nextjs-setup.md - Complete Next.js frontend setup
• references/plugins.md - Plugin configuration (2FA, passkey, organizations, SSO, magic link)
• references/mfa-2fa.md - Detailed MFA/2FA guide
• references/passkey.md - Detailed passkey implementation
• references/schema.md - Drizzle schema reference
• references/social-providers.md - Social provider configuration