{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "paths": {
      "better-auth": ["./src/lib/better-auth/source/index.ts"],
      "better-auth/*": ["./src/lib/better-auth/source/*"]
    }
  }
}

3. Set required environment variables:

BETTER_AUTH_SECRET=your-32-char-secret-minimum
BETTER_AUTH_URL=https://your-app.com
DATABASE_URL=postgresql://user:pass@host/db

4. Wire the auth handler into your server (see examples below).

5. For Prisma adapter, run npx prisma generate after schema changes.

Public API

betterAuth

import { betterAuth } from "better-auth";

function betterAuth(config: BetterAuthConfig): BetterAuthInstance

The main factory function. Call once at startup with your database adapter, secret, and plugin list. The returned instance exposes a handler for HTTP and a api object for server-side calls.

APIError

import { APIError } from "better-auth";

class APIError extends Error {
  constructor(status: number, message?: string, headers?: Headers)
}

Throw this inside custom plugins or route handlers to return structured HTTP error responses. Better Auth's handler catches it and serializes it correctly.

createAdapterFactory

import { createAdapterFactory } from "better-auth/adapters";

function createAdapterFactory(
  config: AdapterFactoryConfig
): AdapterFactory

Use this to build a custom database adapter when none of the built-ins fit. It accepts model/field name transformers and a query executor. Prefer the built-in adapters unless you have a non-standard data layer.

getCurrentAdapter

import { getCurrentAdapter } from "better-auth";

function getCurrentAdapter(context: AuthContext): Adapter

Retrieves the active adapter from the current request context. Useful inside plugin hooks when you need raw database access during request handling.

Working examples

Scenario - Basic Express setup with memory adapter

A minimal local development setup using the in-memory adapter, no external database required.

import express from "express";
import { betterAuth } from "better-auth";
import { memoryAdapter } from "better-auth/adapters/memory-adapter";

const auth = betterAuth({
  secret: process.env.BETTER_AUTH_SECRET!,
  baseURL: process.env.BETTER_AUTH_URL ?? "http://localhost:3000",
  database: memoryAdapter(),
  emailAndPassword: {
    enabled: true,
  },
});

const app = express();
app.use(express.json());

// Mount all auth routes under /api/auth
app.all("/api/auth/*", async (req, res) => {
  const response = await auth.handler(req);
  res.status(response.status);
  response.headers.forEach((value, key) => res.setHeader(key, value));
  res.send(await response.text());
});

app.listen(3000, () => console.log("Listening on :3000"));

Scenario - OAuth2 social login with Drizzle adapter

Production setup wiring a PostgreSQL Drizzle adapter with a GitHub social provider.

import { betterAuth } from "better-auth";
import { drizzleAdapter } from "better-auth/adapters/drizzle-adapter";
import { db } from "./db"; // your Drizzle db instance
import * as schema from "./db/schema";

export const auth = betterAuth({
  secret: process.env.BETTER_AUTH_SECRET!,
  baseURL: process.env.BETTER_AUTH_URL!,
  database: drizzleAdapter(db, {
    provider: "pg",
    schema,
  }),
  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    },
  },
});

export type Auth = typeof auth;

Scenario - Custom adapter factory for an unsupported ORM

When you use a data layer not covered by a built-in adapter.

import { createAdapterFactory } from "better-auth/adapters";

const myAdapter = createAdapterFactory({
  adapterId: "my-custom-orm",
  adapterName: "My Custom ORM Adapter",
  createAdapter(config, options) {
    return {
      async findOne({ model, where }) {
        // translate to your ORM query
        return myOrm[model].findFirst({ where });
      },
      async findMany({ model, where, limit, offset }) {
        return myOrm[model].findMany({ where, take: limit, skip: offset });
      },
      async create({ model, data }) {
        return myOrm[model].create({ data });
      },
      async update({ model, where, update }) {
        return myOrm[model].update({ where, data: update });
      },
      async delete({ model, where }) {
        return myOrm[model].delete({ where });
      },
      async count({ model, where }) {
        return myOrm[model].count({ where });
      },
    };
  },
});

import { betterAuth } from "better-auth";

export const auth = betterAuth({
  secret: process.env.BETTER_AUTH_SECRET!,
  baseURL: process.env.BETTER_AUTH_URL!,
  database: myAdapter({}),
});

File walkthrough

• index.ts - Barrel export: re-exports betterAuth, all core types, APIError, adapter utilities, and third-party types from jose, zod, and better-call.
• state.ts - Holds global mutable state used across the auth lifecycle.
• version.ts - Exports the current package version string.
• adapters/ - Re-exports all database adapters; adapters/index.ts also exposes createAdapterFactory and deprecated aliases like createAdapter.
• api/ - All HTTP route definitions (sign-in, sign-up, sign-out, session, OAuth callback, password reset, email verification), middleware (origin check, authorization), and rate limiter.
• auth/ - betterAuth factory split into full.ts (all features), minimal.ts (tree-shaken), and base.ts (shared logic). Trusted origins validation is in trusted-origins.ts.
• client/ - Isomorphic client SDK. Framework-specific bindings live in subdirectories (react/, vue/, svelte/, solid/, lynx/). vanilla.ts is the framework-agnostic base.
• context/ - Utilities for constructing and reading the per-request auth context.
• cookies/ - Cookie parsing, signing, and serialization helpers.
• crypto/ - Wrappers over the Web Crypto API used for hashing, HMAC, and random bytes.
• db/ - Internal database query builder and schema inference utilities.
• integrations/ - Thin adapters for specific server frameworks.
• oauth2/ - OAuth2 authorization code flow implementation, PKCE, state generation.
• plugins/ - Built-in plugin implementations (2FA, magic link, passkey, etc.).
• social-providers/ - Provider-specific OAuth2 configurations for GitHub, Google, Discord, and others.
• test-utils/ - Test server factory and mock helpers for integration testing.
• types/ - Shared TypeScript interfaces for config, plugins, sessions, and users.
• utils/ - Miscellaneous helpers: URL, date, object, and string utilities.

Common pitfalls and fixes

• BETTER_AUTH_SECRET too short: The secret must be at least 32 characters; shorter values cause silent HMAC failures at runtime. Use openssl rand -base64 32 to generate one.
• Adapter schema mismatch: When using Drizzle or Prisma adapters, the schema table/column names must match what Better Auth expects. Use initGetModelName/initGetFieldName from createAdapterFactory to map custom names instead of renaming your schema.
• ESM/CJS interop with better-call: If your bundler sees dual-module errors, add better-call and better-auth to esmExternals or set "type": "module" in your package.json.
• OAuth callback URL not whitelisted: BETTER_AUTH_URL must match the authorized redirect URI registered with the provider exactly, including trailing slash.
• getCurrentAdapter called outside request context: This function reads from async local storage and returns undefined outside an active request handler. Only call it inside plugin hooks or middleware.
• Memory adapter not suitable for production: It holds all data in-process; use it only for tests and local development. Data is lost on restart.

Vibe-coding prompt template

I have a TypeScript Node.js project and I want to integrate Better Auth from the
source block located at `source/` (entry point: `source/index.ts`).
Please read `USAGE.md` in full before writing any code.

Tasks:
1. Install all dependencies listed in the "Required dependencies" section.
2. Create `src/auth.ts` that calls `betterAuth` with the appropriate adapter
   for my database (ask me which one if not specified).
3. Mount the auth HTTP handler on my existing server framework (ask me which
   framework I use if not specified).
4. Add the required environment variables to `.env.example`.
5. If I need social OAuth login, add at least one provider configuration.
6. Show me how to protect a route server-side using the session API.
7. Point out any tsconfig changes needed to resolve imports from `source/`.

Upstream package: `better-auth` / `@better-auth/core`
Documentation reference: `USAGE.md`
Source root: `source/`

Do not invent APIs. Only use exports visible in `source/index.ts`,
`source/adapters/index.ts`, and the symbols documented in `USAGE.md`.
Proceed step by step and ask clarifying questions before writing code.

License and credit

Better Auth is released under the MIT License. See source/LICENSE.md if present in the source block, or refer to the official repository. Upstream package: better-auth by the Better Auth maintainers.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

전체 설치 가이드와 연동 프롬프트는 구매 후 열람할 수 있습니다.

Better Auth: TypeScript Authentication Framework

Automation, Utilities & Developer Tools

무료