Installation

Install the Package

Let's start by adding Better Auth to your project:

npm install better-auth

Set Environment Variables

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

1. Secret Key

Random value used by the library for encryption and generating hashes. You can generate one using the button below or you can use something like openssl.

BETTER_AUTH_SECRET=

2. Set Base URL

BETTER_AUTH_URL=http://localhost:3000 #Base URL of your app

Create A Better Auth Instance

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

• Project root
• lib/ folder
• utils/ folder

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

And in this file, import Better Auth and create your auth instance. Make sure to export the auth instance with the variable name auth or as a default export.

import { betterAuth } from "better-auth";
 
export const auth = betterAuth({
    //...
})

Configure Database

Better Auth requires a database to store user data. You can easily configure Better Auth to use SQLite, PostgreSQL, or MySQL, with Kysely handling queries and migrations for these databases.

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

You can also provide any Kysely dialect or a Kysely instance to the database option.

Example with LibsqlDialect:

import { betterAuth } from "better-auth";
import { LibsqlDialect } from "@libsql/kysely-libsql";
 
const dialect = new LibsqlDialect({
    url: process.env.TURSO_DATABASE_URL || "",
    authToken: process.env.TURSO_AUTH_TOKEN || "",
})
 
export const auth = betterAuth({
  database: {
    dialect,
    type: "sqlite"
  }
});

Adapters

If you prefer to use an ORM or if your database is not supported by Kysely, you can use one of the built-in adapters.

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

Create Database Tables

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

• Generate: This command generates an ORM schema or SQL migration file.

npx @better-auth/cli generate

• Migrate: This command creates the required tables directly in the database. (Available only for the built-in Kysely adapter)

npx @better-auth/cli migrate

see the CLI documentation for more information.

Authentication Methods

Configure the authentication methods you want to use. Better Auth comes with built-in support for email/password, and social sign-on providers.

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

Mount Handler

To handle api requests, you need to set up a route handler on your server.

Create a new file or route in your framework's designated catch-all route handler. This route should handle requests for the path /api/auth/* (unless you've configured a different base path).

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

Create Client Instance

The client-side library helps you interact with the auth server. Better Auth comes with a client for all the popular web frameworks, including vanilla JavaScript.

1. Import createAuthClient from the package for your framework (e.g., "better-auth/react" for React).
2. Call the function to create your client.
3. Pass the base url of your auth server. (If the auth server is running on the same domain as your client, you can skip this step.)

import { createAuthClient } from "better-auth/react"
export const authClient = createAuthClient({
    baseURL: "http://localhost:3000" // the base url of your auth server
})

export const { signIn, signUp, useSession } = createAuthClient()

🎉 That's it!

That's it! You're now ready to use better-auth in your application. Continue to basic usage to learn how to use the auth instance to sign in users.