betterauth

Files (1)

• SKILL.md

SKILL.md (first lines)

# betterauth

BetterAuth integration patterns — setup, session management, OAuth providers, middleware protection, and security best practices for authentication in TypeScript/Next.js applications.

## Instructions

Apply these practices when integrating BetterAuth into your application:

### Setup & Configuration

Create a single authoritative auth instance and export typed helpers from it:

```ts
// lib/auth.ts
import { betterAuth } from 'better-auth';
import { prismaAdapter } from 'better-auth/adapters/prisma';
import { db } from './db';

export const auth = betterAuth({
  database: prismaAdapter(db, { provider: 'postgresql' }),
  emailAndPassword: { enabled: true },
  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    },
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    },
  },
  session: {
    expiresIn: 60 * 60 * 24 * 7,        // 7 days
    updateAge: 60 * 60 * 24,             // refresh session if older than 1 day
    cookieCache: { enabled: true, maxAge: 60 * 5 }, // 5-minute client cache
  },
  trustedOrigins: [process.env.NEXT_PUBLIC_APP_URL!],
});

// Export typed client helpers
export type Session = typeof auth.$Infer.Session;
```

### API Route Handler

Mount the BetterAuth catch-all handler at `app/api/auth/[...all]/route.ts`:

```ts
// app/api/auth/[...all]/route.ts
import { auth } from '@/lib/auth';
import { toNextJsHandler } from 'better-auth/next-js';

export const { GET, POST } = toNextJsHandler(auth);
```

### Client-Side Auth Client

Create a single client instance to use across Client Components:

```ts
// lib/auth-client.ts
import { createAuthClient } from 'better-auth/react';

export const authClient = createAuthClient({
  baseURL: process.env.NEXT_PUBLIC_APP_URL!,
});

export const { signIn, signOut, signUp, useSession } = authClient;
```

### Session Access

**Server Component:**
```ts
import { auth } from '@/lib/auth';
import { headers } from 'next/headers';

export async function getServerSession() {
  const session = await auth.api.getSession({ headers: await headers() });
  return session;
}
```

**Client Component:**
```tsx
'use client';
import { useSession } from '@/lib/auth-client';

export function UserAvatar() {
  const { data: session, isPending } = useSession();
  if (isPending) return <Skeleton />;
  if (!session) return null;
  return <img src={session.user.image ?? ''} alt={session.user.name} />;
}
```

### Route Protection

Protect routes at the middleware layer to avoid unnecessary page renders for unauthenticated users:

```ts
// middleware.ts
import { NextRequest, NextResponse } from 'next/server';
import { auth } from '@/lib/auth';

const PROTECTED = ['/dashboard', '/settings', '/api/protected'];

export async function middleware(req: NextRequest) {
  const isProtected = PROTECTED.some(path => req.nextUrl.pathname.startsWith(path));
  if (!isProtected) return NextResponse.next();

  const session = await auth.api.getSession({ headers: req.headers });
  if (!session) {
    const loginUrl = new URL('/login', req.url);
    loginUrl.searchParams.set('callbackUrl', req.nextUrl.pathname);
    return NextResponse.redirect(loginUrl);
  }

  return NextResponse.next();

From Satcomx00-x00/skills-db, MIT.

More from Satcomx00-x00/skills-db