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 
how to use better-auth
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use better-auth on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add better-auth
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill better-authcopy
The skills CLI fetches better-auth from GitHub repository giuseppe-trisciuoglio/developer-kit and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/better-auth
Reload or restart Cursor to activate better-auth. Access the skill through slash commands (e.g., /better-auth) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?