mirror of
https://github.com/better-auth/better-auth.git
synced 2026-05-25 08:31:37 -05:00
379 lines
12 KiB
Plaintext
379 lines
12 KiB
Plaintext
---
|
||
title: Installtion
|
||
description: Learn how to configure Better Auth in your project.
|
||
---
|
||
|
||
<Steps>
|
||
|
||
<Step>
|
||
### Install the Package
|
||
|
||
Let's start by adding Better Auth to your project:
|
||
|
||
```package-install
|
||
better-auth
|
||
```
|
||
|
||
<Callout type="info">
|
||
If you're using a separate client and server setup, make sure to install Better Auth in both parts of your project. (currnelty better auth only supports web platforms more clients will be added soon)
|
||
</Callout>
|
||
</Step>
|
||
|
||
<Step>
|
||
### 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.
|
||
```txt title=".env"
|
||
BETTER_AUTH_SECRET=
|
||
```
|
||
<GenerateSecret/>
|
||
|
||
2. **Set Base URL (optional)**
|
||
|
||
```txt title=".env"
|
||
BETTER_AUTH_URL=http://localhost:3000 #Base URL of your app
|
||
```
|
||
</Step>
|
||
|
||
<Step>
|
||
### 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/` folder. (e.g. `src/lib/auth.ts`)
|
||
|
||
And in this file, import Better Auth and create your instance.
|
||
|
||
<Callout type="warn">
|
||
Make sure to export the auth instance with the variable name `auth` or as a `default` export.
|
||
</Callout>
|
||
|
||
```ts title="auth.ts"
|
||
import { betterAuth } from "better-auth"
|
||
|
||
export const auth = betterAuth({
|
||
//...
|
||
})
|
||
```
|
||
</Step>
|
||
|
||
<Step>
|
||
### Configure Database
|
||
|
||
Better Auth requires a database to store user data. By default, it uses [Kysely](https://kysely.dev/) for database connections and queries, with support for `postgresql`, `mysql`, and `sqlite` out of the box.
|
||
|
||
```ts title="auth.ts"
|
||
import { betterAuth } from "better-auth"
|
||
|
||
export const auth = betterAuth({
|
||
database: {
|
||
provider: "sqlite", // or "mysql", "postgresql"
|
||
url: "./db.sqlite", // path to your database or connection string
|
||
}
|
||
})
|
||
```
|
||
|
||
You can also use any dialect supported by Kysely in the database configuration.
|
||
|
||
**Example with LibsqlDialect:**
|
||
|
||
```ts title="auth.ts"
|
||
import { betterAuth } from "better-auth";
|
||
import { LibsqlDialect } from "@libsql/kysely-libsql";
|
||
|
||
export const auth = betterAuth({
|
||
database: new LibsqlDialect({
|
||
url: process.env.TURSO_DATABASE_URL || "",
|
||
authToken: process.env.TURSO_AUTH_TOKEN || "",
|
||
}),
|
||
});
|
||
```
|
||
|
||
**Adapters**
|
||
|
||
If your database isn’t supported by Kysely, you can use an adapter to connect. Simply import the adapter and pass it into the `database` option.
|
||
|
||
<Tabs items={["prisma", "drizzle", "mongodb"]}>
|
||
<Tab value="prisma">
|
||
```ts title="auth.ts"
|
||
import { betterAuth } from "better-auth";
|
||
import { prismaAdapter } from "better-auth/adapters";
|
||
import { PrismaClient } from "@prisma/client";
|
||
|
||
const prisma = new PrismaClient();
|
||
export const auth = betterAuth({
|
||
database: prismaAdapter(prisma, {
|
||
provider: "sqlite", // or "mysql", "postgresql", ...etc
|
||
}),
|
||
});
|
||
```
|
||
</Tab>
|
||
|
||
<Tab value="drizzle">
|
||
```ts title="auth.ts"
|
||
import { betterAuth } from "better-auth";
|
||
import { drizzleAdapter } from "better-auth/adapters";
|
||
import { db } from "@/db"; // your drizzle instance
|
||
|
||
export const auth = betterAuth({
|
||
database: drizzleAdapter(db, {
|
||
provider: "pg", // or "mysql", "sqlite"
|
||
})
|
||
});
|
||
```
|
||
</Tab>
|
||
|
||
<Tab value="mongodb">
|
||
```ts title="auth.ts"
|
||
import { betterAuth } from "better-auth";
|
||
import { monogdbAdapter } from "better-auth/adapters";
|
||
import { client } from "@/db"; // your mongodb client
|
||
|
||
export const auth = betterAuth({
|
||
database: monogdbAdapter(client)
|
||
});
|
||
```
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
</Step>
|
||
|
||
<Step>
|
||
### Create Database Tables
|
||
|
||
Better Auth includes a CLI tool to help manage your database tables. You can either migrate tables directly or generate an ORM schema or SQL migration file.
|
||
|
||
**Migrate**: Creates the necessary tables in your database.
|
||
|
||
```bash title="Terminal"
|
||
npx better-auth migrate
|
||
```
|
||
|
||
**Generate**: Generates the required ORM schema (e.g., Prisma, Drizzle) or an SQL migration file.
|
||
|
||
```bash title="Terminal"
|
||
npx better-auth generate
|
||
```
|
||
|
||
see the [CLI documentation](/docs/concepts/cli) for more information.
|
||
|
||
<Callout>
|
||
If you instead want to create the schema manually, you can find the core schema required in the [database section](/docs/concepts/database#core-schema).
|
||
</Callout>
|
||
</Step>
|
||
|
||
<Step>
|
||
### 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.
|
||
|
||
```ts title="auth.ts"
|
||
import { betterAuth } from "better-auth"
|
||
import { github } from "better-auth/social-providers"
|
||
|
||
export const auth = betterAuth({
|
||
database: {
|
||
provider: "sqlite",
|
||
url: "./db.sqlite",
|
||
},
|
||
emailAndPassword: { // [!code highlight]
|
||
enabled: true // [!code highlight]
|
||
},// [!code highlight]
|
||
socialProviders: { // [!code highlight]
|
||
github: { // [!code highlight]
|
||
clientId: process.env.GITHUB_CLIENT_ID, // [!code highlight]
|
||
clientSecret: process.env.GITHUB_CLIENT_SECRET, // [!code highlight]
|
||
} // [!code highlight]
|
||
}, // [!code highlight]
|
||
});
|
||
```
|
||
|
||
<Callout type="info">
|
||
You can use even more authentication methods like passkey, username, magic link and more through plugins.
|
||
</Callout>
|
||
</Step>
|
||
|
||
<Step>
|
||
### 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).
|
||
|
||
<Callout>
|
||
Better auth supports any backend framework with standard Request and Response objects and offers helper functions for popular frameworks.
|
||
</Callout>
|
||
|
||
<Tabs items={["next-js", "remix", "nuxt", "svelte-kit", "solid-start", "hono", "express"]} defaultValue="react">
|
||
<Tab value="next-js">
|
||
```ts title="/app/api/auth/[...all]/route.ts"
|
||
import { auth } from "@/lib/auth"; // path to your auth file
|
||
import { toNextJsHandler } from "better-auth/next-js";
|
||
|
||
export const { POST, GET } = toNextJsHandler(auth);
|
||
```
|
||
</Tab>
|
||
<Tab value="remix">
|
||
```ts title="/app/routes/api.auth.$.ts"
|
||
import { auth } from "@/lib/auth"; // path to your auth file
|
||
|
||
export async function loader({ request }) {
|
||
return auth.handler(request);
|
||
}
|
||
```
|
||
</Tab>
|
||
<Tab value="nuxt">
|
||
```ts title="/server/api/auth/[...all].ts"
|
||
import { auth } from "~/utils/auth"; // path to your auth file
|
||
|
||
export default defineEventHandler((event) => {
|
||
return auth.handler(toWebRequest(event));
|
||
});
|
||
```
|
||
</Tab>
|
||
<Tab value="svelte-kit">
|
||
```ts title="hooks.server.ts"
|
||
import { auth } from "$lib/auth"; // path to your auth file
|
||
import { svelteKitHandler } from "better-auth/svelte-kit";
|
||
|
||
export async function handle({ event, resolve }) {
|
||
return svelteKitHandler({ event, resolve, auth });
|
||
}
|
||
```
|
||
</Tab>
|
||
<Tab value="solid-start">
|
||
```ts title="/routes/api/auth/*all.ts"
|
||
import { auth } from "~/lib/auth"; // path to your auth file
|
||
import { toSolidStartHandler } from "better-auth/solid-start";
|
||
|
||
export const { GET, POST } = toSolidStartHandler(auth);
|
||
```
|
||
</Tab>
|
||
<Tab value="hono">
|
||
```ts title="src/index.ts"
|
||
import { Hono } from "hono";
|
||
import { auth } from "./auth"; // path to your auth file
|
||
import { serve } from "@hono/node-server";
|
||
import { cors } from "hono/cors";
|
||
|
||
const app = new Hono();
|
||
|
||
app.on(["POST", "GET"], "/api/auth/**", (c) => {
|
||
return auth.handler(c.req.raw);
|
||
});
|
||
|
||
serve(app);
|
||
```
|
||
</Tab>
|
||
|
||
<Tab value="express">
|
||
```ts title="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));
|
||
app.listen(port, () => {
|
||
console.log(`Better Auth app listening on port ${port}`);
|
||
});
|
||
```
|
||
This also works for any other node server framework like express, fastify, hapi, etc.
|
||
</Tab>
|
||
<Tab value="astro">
|
||
```ts title="/pages/api/auth/[...all].ts"
|
||
import type { APIRoute } from "astro";
|
||
import { auth } from "@/auth"; // path to your auth file
|
||
|
||
export const GET: APIRoute = async (ctx) => {
|
||
return auth.handler(ctx.request);
|
||
};
|
||
|
||
export const POST: APIRoute = async (ctx) => {
|
||
return auth.handler(ctx.request);
|
||
};
|
||
```
|
||
</Tab>
|
||
</Tabs>
|
||
</Step>
|
||
|
||
<Step>
|
||
### 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 inlcuding for 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.)
|
||
|
||
<Callout type="info">
|
||
If you're using a differnt base path other than `/api/auth` make sure to pass the whole url inlcuding the path. (e.g. `http://localhost:3000/custom-path/auth`)
|
||
</Callout>
|
||
|
||
<Tabs items={["react", "vue", "svelte", "solid",
|
||
"vanilla"]} defaultValue="react">
|
||
<Tab value="vanilla">
|
||
```ts title="lib/auth-client.ts"
|
||
import { createAuthClient } from "better-auth/client"
|
||
export const authClient = createAuthClient({
|
||
baseURL: "http://localhost:3000" // the base url of your auth server // [!code highlight]
|
||
})
|
||
```
|
||
</Tab>
|
||
<Tab value="react" title="lib/auth-client.ts">
|
||
```ts title="lib/auth-client.ts"
|
||
import { createAuthClient } from "better-auth/react"
|
||
export const client = createAuthClient({
|
||
baseURL: "http://localhost:3000" // the base url of your auth server // [!code highlight]
|
||
})
|
||
```
|
||
</Tab>
|
||
<Tab value="vue" title="lib/auth-client.ts">
|
||
```ts title="lib/auth-client.ts"
|
||
import { createAuthClient } from "better-auth/vue"
|
||
export const client = createAuthClient({
|
||
baseURL: "http://localhost:3000" // the base url of your auth server // [!code highlight]
|
||
})
|
||
```
|
||
</Tab>
|
||
<Tab value="svelte" title="lib/auth-client.ts">
|
||
```ts title="lib/auth-client.ts"
|
||
import { createAuthClient } from "better-auth/svelte"
|
||
export const client = createAuthClient({
|
||
baseURL: "http://localhost:3000" // the base url of your auth server // [!code highlight]
|
||
})
|
||
```
|
||
</Tab>
|
||
<Tab value="solid" title="lib/auth-client.ts">
|
||
```ts title="lib/auth-client.ts"
|
||
import { createAuthClient } from "better-auth/solid"
|
||
export const client = createAuthClient({
|
||
baseURL: "http://localhost:3000" // the base url of your auth server // [!code highlight]
|
||
})
|
||
```
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
<Callout type="info">
|
||
Tip: You can also export specific methods if you prefer:
|
||
</Callout>
|
||
```ts
|
||
export const { signIn, signUp, useSession } = createAuthClient()
|
||
```
|
||
</Step>
|
||
|
||
|
||
|
||
<Step>
|
||
### 🎉 That's it!
|
||
That's it! You're now ready to use better-auth in your application. Continue to [basic usage](/docs/basic-usage) to learn how to use the auth instance to sign in users.
|
||
</Step>
|
||
</Steps>
|