Awesome-omni-skill Better Auth Best Practices

Best practices for building Better Auth integrations. Use when implementing authentication, authorization, session management, OAuth providers, or any Better Auth integration.

When designing an authentication integration, always prefer Better Auth's Documentation.

You should always default to the latest version of Better Auth unless the user specifies otherwise.

Better Auth is a TypeScript-first authentication framework that provides a secure, flexible, and developer-friendly approach to authentication. It supports multiple methods including email/password, OAuth providers, magic links, and passwordless authentication.

Core Principles

1. Packaging

Most imports come from the npm package

better-auth

better-auth/plugins

better-auth/adapters/*

@better-auth/stripe

2. Environment Variables

Better Auth requires two environment variables:

• BETTER_AUTH_SECRET

  : A high-entropy secret used for encryption and hashing (at least 32 characters).

• BETTER_AUTH_URL

  : The base URL for the server where Better Auth is mounted.

3. Auth Config

Initialize Better Auth by calling

betterAuth

const auth

auth.ts

./

./lib

./utils

src

4. Database

The database connection is the most important part of the auth config. If no database is provided, Better Auth uses the in-memory adapter (non-persistent). Built-in adapters support database clients like

pg

mysql2

better-sqlite3

bun:sqlite

drizzleAdapter

prismaAdapter

mongodbAdapter

5. CLI

Use the Better Auth CLI to manage schema:

• npx @better-auth/cli@latest migrate

  applies schema directly for the built-in Kysely adapter.

• npx @better-auth/cli@latest generate

  generates schema for Prisma/Drizzle (apply with your ORM).
• The CLI supports

  --config

  to point to a non-default

  auth.ts

  location.

6. Authentication Methods

Configure methods in the auth config. Core methods include

emailAndPassword

socialProviders

emailAndPassword: { enabled: true }

socialProviders

genericOAuth

username

phoneNumber

emailOtp

magicLink

passkey

anonymous

7. Handler

All HTTP requests are handled by

auth.handler

8. Client

Better Auth provides clients to interact with the auth server. Client files are typically named

auth-client.ts

React example client:

import { createAuthClient } from 'better-auth/react';
export const authClient = createAuthClient({
  /** The base URL of the server (optional if you're using the same domain) */
  baseURL: 'http://localhost:3000',
});

Other than React, there are clients for vanilla JS, Vue, Svelte, and Solid. See https://www.better-auth.com/docs/concepts/client

9. Type Safety

Better Auth is built with TypeScript and provides full type safety. Infer types with

auth.$Infer

10. Session

Sessions are stored in the database unless you provide

secondaryStorage

11. Auth Options

Review https://github.com/better-auth/better-auth/blob/main/packages/core/src/types/init-options.ts for the full configuration surface. Key skill areas include:

• Rate limiting: Configure

  rateLimit

  defaults, per-path

  customRules

  , and storage (

  memory

  ,

  database

  ,

  secondary-storage

  , or

  customStorage

  ).
• Advanced security: Use

  advanced.useSecureCookies

  , and be cautious with

  advanced.disableCSRFCheck

  or

  advanced.disableOriginCheck

  (these reduce protections).
• Trusted origins: Prefer dynamic

  trustedOrigins

  when running behind proxies or multiple hostnames.
• Cookie strategy: Customize cookie names/attributes, prefixes, and cross-subdomain settings via

  advanced.cookies

  ,

  advanced.cookiePrefix

  , and

  advanced.crossSubDomainCookies

  .
• Session tuning: Adjust

  session.expiresIn

  ,

  session.updateAge

  ,

  session.cookieCache

  , and

  session.freshAge

  based on UX/security needs.
• Account linking: Configure

  account.accountLinking

  carefully, especially

  allowDifferentEmails

  and

  allowUnlinkingAll

  .
• Email flows: Use

  emailVerification

  hooks and

  emailAndPassword.sendResetPassword

  to implement secure verification and recovery.
• Data model mapping: Map fields and add metadata via

  user.fields

  ,

  session.fields

  ,

  account.fields

  , and

  verification.fields

  .
• Database hooks: Use

  databaseHooks

  to enforce policies or auditing on user/session/account/verification lifecycle events.
• Error handling: Centralize response behavior with

  onAPIError

  and customize the default error page if needed.
• Telemetry: Control data collection with

  telemetry.enabled

  and

  telemetry.debug

  .
• Experimental flags: Keep

  experimental.joins

  off unless the adapter supports it and the docs recommend it.

Plugin Architecture

Plugins follow a consistent structure with these key properties:

id

endpoints

createAuthEndpoint

schema

hooks.before

hooks.after

init

onRequest

onResponse

$ERROR_CODES

rateLimit

When building custom plugins, use

createAuthEndpoint

createAuthMiddleware

@better-auth/core/api

sessionMiddleware

better-auth/api

Example Plugin Structure

import type { BetterAuthPlugin } from '@better-auth/core';
import { createAuthEndpoint, createAuthMiddleware } from '@better-auth/core/api';
import { sessionMiddleware } from 'better-auth/api';
import { z } from 'zod';

export const myPlugin = (options?: MyPluginOptions) => {
  return {
    id: 'my-plugin',
    endpoints: {
      myEndpoint: createAuthEndpoint(
        '/my-plugin/action',
        {
          method: 'POST',
          body: z.object({ data: z.string() }),
          use: [sessionMiddleware], // Require authentication
        },
        async (ctx) => {
          const user = ctx.context.session.user;
          // Implementation
          return { success: true };
        },
      ),
    },
    schema: {
      myTable: {
        fields: {
          userId: { type: 'string', references: { model: 'user', field: 'id' } },
          data: { type: 'string' },
        },
      },
    },
    $ERROR_CODES: {
      MY_ERROR: 'My custom error message',
    },
  } satisfies BetterAuthPlugin;
};

Client-Server Type Inference

Use

auth.$Infer

$InferServerPlugin

// Server plugin exports
export const myPlugin = () =>
  ({
    id: 'my-plugin',
    $ERROR_CODES: MY_ERROR_CODES,
    // ...
  }) satisfies BetterAuthPlugin;

// Client plugin
export const myPluginClient = () =>
  ({
    $InferServerPlugin: {} as ReturnType<typeof myPlugin>,
    getActions: ($fetch) => ({
      myAction: async () => {
        return $fetch('/my-plugin/action', { method: 'POST' });
      },
    }),
  }) satisfies BetterAuthClientPlugin;

Social Providers

Built-in Providers

apple

atlassian

cognito

discord

dropbox

facebook

figma

github

gitlab

google

huggingface

kakao

kick

line

linear

linkedin

microsoft

naver

notion

paybin

paypal

polar

reddit

roblox

salesforce

slack

spotify

tiktok

twitch

twitter

vercel

vk

zoom

Generic OAuth

For providers not in this list, use the

genericOAuth

import { betterAuth } from 'better-auth';
import { genericOAuth } from 'better-auth/plugins';

const auth = betterAuth({
  // Built-in providers
  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    },
  },
  // Generic OAuth for other providers
  plugins: [
    genericOAuth({
      config: [
        {
          providerId: 'custom-provider',
          clientId: process.env.CUSTOM_CLIENT_ID!,
          clientSecret: process.env.CUSTOM_CLIENT_SECRET!,
          authorizationUrl: 'https://provider.com/oauth/authorize',
          tokenUrl: 'https://provider.com/oauth/token',
          userInfoUrl: 'https://provider.com/api/user',
        },
      ],
    }),
  ],
});

Scoped Packages

Some plugins live in separate packages:

@better-auth/stripe

@better-auth/expo

@better-auth/passkey

@better-auth/sso

@better-auth/scim

Framework Integrations

Next.js

import { toNextJsHandler } from 'better-auth/integrations/next-js';
import { auth } from './auth';

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

For Server Components cookie handling, add

nextCookies()

import { nextCookies } from 'better-auth/integrations/next-js';

const auth = betterAuth({
  plugins: [nextCookies()],
});

Other Frameworks

• SvelteKit: Use

  svelteKitHandler()

• SolidStart: Use

  solidStartHandler()

• TanStack Start: Use

  tanstackStartHandler()

• Node/Express: Mount

  auth.handler

  directly as middleware

Testing

For unit tests, use

getTestInstance()

better-auth/test-utils

import { getTestInstance } from 'better-auth/test-utils';
import { describe, it, expect } from 'vitest';

describe('my auth tests', () => {
  it('should authenticate user', async () => {
    const { client, signInWithTestUser } = await getTestInstance({
      plugins: [myPlugin()],
    });

    const { headers, user } = await signInWithTestUser();

    const result = await client.myPlugin.action({
      fetchOptions: { headers },
    });

    expect(result.data).toBeDefined();
  });
});

What

getTestInstance()

Provides

• In-memory SQLite database by default (or postgres/mysql/mongodb via config)
• Automatic migration execution
• Pre-configured client with custom fetch
• Test user (

  test@test.com

  /

  test123456

  )

• signInWithTestUser()

  for authenticated test flows
• Automatic cleanup via

  afterAll

Account Linking

Configure

account.accountLinking

enabled

trustedProviders

allowDifferentEmails

allowUnlinkingAll

Accounts are automatically linked when a user signs in with a different provider using the same verified email.

const auth = betterAuth({
  account: {
    accountLinking: {
      enabled: true,
      trustedProviders: ['google', 'github'], // These can link without email verification
      allowDifferentEmails: false, // Keep false for security
    },
  },
});

Session Cookie Strategies

session.cookieCache.strategy

"compact"

"full"

"jwt"

jwt

const auth = betterAuth({
  session: {
    cookieCache: {
      enabled: true,
      strategy: 'compact',
      maxAge: 60 * 5, // 5 minutes
    },
  },
});

Internal Adapter

Access database operations via

ctx.context.internalAdapter

• findUserByEmail()

  ,

  findUserById()

• createUser()

  ,

  updateUser()

  ,

  deleteUser()

• createSession()

  ,

  findSession()

  ,

  deleteSession()

• linkAccount()

  ,

  findOAuthUser()

• createVerification()

  ,

  findVerification()

These methods automatically apply

databaseHooks

Database Hooks

Use

databaseHooks

const auth = betterAuth({
  databaseHooks: {
    user: {
      create: {
        before: async (user, ctx) => {
          // Modify user before creation
          return { data: { ...user, customField: 'value' } };
        },
        after: async (user, ctx) => {
          // Audit log, send welcome email, etc.
          await sendWelcomeEmail(user.email);
        },
      },
    },
    session: {
      create: {
        after: async (session, ctx) => {
          // Track session creation
        },
      },
    },
  },
});

Error Handling

Use

APIError

better-call

import { APIError } from 'better-call';
import { BASE_ERROR_CODES } from '@better-auth/core/error';

// In an endpoint
throw new APIError('BAD_REQUEST', {
  message: BASE_ERROR_CODES.INVALID_PASSWORD,
});

// Custom error codes in plugins
export const MY_ERROR_CODES = {
  CUSTOM_ERROR: 'Custom error occurred',
  VALIDATION_FAILED: 'Validation failed',
} as const;

Error codes should be exported as

$ERROR_CODES

BASE_ERROR_CODES

@better-auth/core/error

Background Tasks

For edge runtimes (Vercel, Cloudflare Workers), configure

advanced.backgroundTasks.handler

waitUntil

// Vercel
import { waitUntil } from '@vercel/functions';

const auth = betterAuth({
  advanced: {
    backgroundTasks: {
      handler: waitUntil,
    },
  },
});

// Cloudflare Workers (with AsyncLocalStorage)
const auth = betterAuth({
  advanced: {
    backgroundTasks: {
      handler: (p) => execCtxStorage.getStore()?.waitUntil(p),
    },
  },
});

Secondary Storage

Use

secondaryStorage

import { betterAuth } from 'better-auth';
import { Redis } from 'ioredis';

const redis = new Redis();

const auth = betterAuth({
  secondaryStorage: {
    get: async (key) => {
      const value = await redis.get(key);
      return value ? JSON.parse(value) : null;
    },
    set: async (key, value, ttl) => {
      if (ttl) {
        await redis.setex(key, ttl, JSON.stringify(value));
      } else {
        await redis.set(key, JSON.stringify(value));
      }
    },
    delete: async (key) => {
      await redis.del(key);
    },
  },
});

IP Address Handling

Configure IP address extraction for rate limiting and session tracking:

const auth = betterAuth({
  advanced: {
    ipAddress: {
      ipAddressHeaders: ['x-real-ip', 'x-forwarded-for', 'cf-connecting-ip'],
      disableIpTracking: false, // Only disable if absolutely necessary
    },
  },
});

Resources

• Better Auth Documentation
• GitHub Repository
• Examples
• Init Options Reference

Always consult the official documentation for the most up-to-date best practices and API changes.