Installation

Install Better Auth and configure it in your project step by step.

1. Install the package

   Add Better Auth to your project:

   npm

   npm install better-auth
   

   If you’re using a separate client and server setup, install Better Auth in both parts of your project.

2. Set environment variables

   Create a .env file in the root of your project and add the following:

   Secret key

   A secret value used for encryption and hashing. It must be at least 32 characters and generated with high entropy. You can run openssl rand -base64 32 to generate one.

   .env

   BETTER_AUTH_SECRET=
   

   Need to rotate your secret later? Use BETTER_AUTH_SECRETS (plural) to roll over to a new secret without invalidating existing sessions. See the secrets option for details.

   Base URL

   .env

   BETTER_AUTH_URL=http://localhost:3000
   
3. Create your auth instance

   Create a file named auth.ts in one of the following locations:

   • Project root
   • lib/ folder
   • utils/ folder

   You can also nest any of these under src/, app/, or server/ (e.g. src/lib/auth.ts).

   Import Better Auth and export your auth instance. The variable must be named auth or use a default export.

   auth.ts

   import { betterAuth } from "better-auth";
   
   export const auth = betterAuth({
     // configuration goes here
   });
   
4. Configure your database

   Better Auth requires a database to store user data. You can connect directly or use an ORM adapter.

   You can also run Better Auth in stateless mode by omitting the database option. See Stateless Session Management for details. Note that most plugins require a database.

   Direct database connection

   SQLite

   auth.ts

   import { betterAuth } from "better-auth";
   import Database from "better-sqlite3";
   
   export const auth = betterAuth({
     database: new Database("./sqlite.db"),
   });
   

   PostgreSQL

   auth.ts

   import { betterAuth } from "better-auth";
   import { Pool } from "pg";
   
   export const auth = betterAuth({
     database: new Pool({
       // connection options
     }),
   });
   

   MySQL

   auth.ts

   import { betterAuth } from "better-auth";
   import { createPool } from "mysql2/promise";
   
   export const auth = betterAuth({
     database: createPool({
       // connection options
     }),
   });
   

   ORM adapters

   Drizzle

   auth.ts

   import { betterAuth } from "better-auth";
   import { drizzleAdapter } from "better-auth/adapters/drizzle";
   import { db } from "@/db"; // your Drizzle instance
   
   export const auth = betterAuth({
     database: drizzleAdapter(db, {
       provider: "pg", // or "mysql", "sqlite"
     }),
   });
   

   Prisma

   auth.ts

   import { betterAuth } from "better-auth";
   import { prismaAdapter } from "better-auth/adapters/prisma";
   import { PrismaClient } from "@/generated/prisma/client";
   
   const prisma = new PrismaClient();
   
   export const auth = betterAuth({
     database: prismaAdapter(prisma, {
       provider: "sqlite", // or "mysql", "postgresql"
     }),
   });
   

   MongoDB

   auth.ts

   import { betterAuth } from "better-auth";
   import { mongodbAdapter } from "better-auth/adapters/mongodb";
   import { client } from "@/db"; // your MongoDB client
   
   export const auth = betterAuth({
     database: mongodbAdapter(client),
   });
   

   If your database is not listed above, see other supported databases or check the full list of ORM adapters.

5. Create database tables

   Better Auth includes a CLI to manage the schema required by the library.

   • Generate — creates an ORM schema or SQL migration file:

     npx auth@latest generate
     

   • Migrate — creates the required tables directly in the database (available only for the built-in Kysely adapter):

     npx auth@latest migrate
     

   If you prefer to create the schema manually, see the core schema in the database documentation.

6. Configure authentication methods

   Configure the authentication methods you want to support. Better Auth has built-in support for email/password and social providers.

   auth.ts

   import { betterAuth } from "better-auth";
   
   export const auth = betterAuth({
     emailAndPassword: {
       enabled: true,
     },
     socialProviders: {
       github: {
         clientId: process.env.GITHUB_CLIENT_ID as string,
         clientSecret: process.env.GITHUB_CLIENT_SECRET as string,
       },
     },
   });
   

   You can add more authentication methods — including passkeys, magic links, and username — through plugins.

7. Mount the route handler

   Set up a route handler on your server to handle auth API requests. By default, Better Auth handles requests at /api/auth/*.

   Better Auth supports any backend framework that uses standard Request and Response objects, and provides helper functions for popular frameworks.

   Next.js (App Router)

   app/api/auth/[...all]/route.ts

   import { auth } from "@/lib/auth";
   import { toNextJsHandler } from "better-auth/next-js";
   
   export const { POST, GET } = toNextJsHandler(auth);
   

   Next.js (Pages Router)

   pages/api/auth/[...all].ts

   import { auth } from "@/lib/auth";
   import { toNodeHandler } from "better-auth/node";
   
   // Disallow body parsing — Better Auth handles it manually
   export const config = { api: { bodyParser: false } };
   export default toNodeHandler(auth.handler);
   

   Nuxt

   server/api/auth/[...all].ts

   import { auth } from "~/utils/auth";
   
   export default defineEventHandler((event) => {
     return auth.handler(toWebRequest(event));
   });
   

   SvelteKit

   hooks.server.ts

   import { auth } from "$lib/auth";
   import { svelteKitHandler } from "better-auth/svelte-kit";
   import { building } from "$app/environment";
   
   export async function handle({ event, resolve }) {
     return svelteKitHandler({ event, resolve, auth, building });
   }
   

   Hono

   src/index.ts

   import { Hono } from "hono";
   import { auth } from "./auth";
   import { serve } from "@hono/node-server";
   
   const app = new Hono();
   
   app.on(["POST", "GET"], "/api/auth/*", (c) => auth.handler(c.req.raw));
   
   serve(app);
   

   Express

   server.ts

   import express from "express";
   import { toNodeHandler } from "better-auth/node";
   import { auth } from "./auth";
   
   const app = express();
   const port = 8000;
   
   app.all("/api/auth/*", toNodeHandler(auth));
   
   // Mount express json middleware after Better Auth handler
   app.use(express.json());
   
   app.listen(port, () => {
     console.log(`Better Auth app listening on port ${port}`);
   });
   

   Express v5 changed wildcard route syntax. Use /{*any} instead of /* for Express v5 compatibility:

   app.all('/api/auth/{*any}', toNodeHandler(auth));
   

   Expo

   app/api/auth/[...all]+api.ts

   import { auth } from "@/lib/server/auth";
   
   const handler = auth.handler;
   export { handler as GET, handler as POST };
   
8. Create the client instance

   The client SDK lets you interact with the auth server from your frontend. Import createAuthClient from the package for your framework.

   If your auth server runs on a different domain than your client, pass the full base URL. If they share the same domain, you can omit baseURL.

   React

   lib/auth-client.ts

   import { createAuthClient } from "better-auth/react";
   
   export const authClient = createAuthClient({
     baseURL: "http://localhost:3000", // optional if same domain
   });
   

   Vue

   lib/auth-client.ts

   import { createAuthClient } from "better-auth/vue";
   
   export const authClient = createAuthClient({
     baseURL: "http://localhost:3000", // optional if same domain
   });
   

   Svelte

   lib/auth-client.ts

   import { createAuthClient } from "better-auth/svelte";
   
   export const authClient = createAuthClient({
     baseURL: "http://localhost:3000", // optional if same domain
   });
   

   Solid

   lib/auth-client.ts

   import { createAuthClient } from "better-auth/solid";
   
   export const authClient = createAuthClient({
     baseURL: "http://localhost:3000", // optional if same domain
   });
   

   Vanilla

   lib/auth-client.ts

   import { createAuthClient } from "better-auth/client";
   
   export const authClient = createAuthClient({
     baseURL: "http://localhost:3000", // optional if same domain
   });
   

   You can also export specific methods directly:

   lib/auth-client.ts

   export const { signIn, signUp, useSession } = createAuthClient();
   
9. Done

   You’re ready to use Better Auth in your application. Continue to basic usage to learn how to sign users in, manage sessions, and more.