Client

Better Auth offers a client library compatible with popular frontend frameworks like React, Vue, Svelte, and more. This client library includes a set of functions for interacting with the Better Auth server. Each framework's client library is built on top of a core client library that is framework-agnostic, so that all methods and hooks are consistently available across all client libraries.

Installation

If you haven't already, install better-auth.

npm i better-auth

Create Client Instance

Import createAuthClient from the package for your framework (e.g., "better-auth/react" for React). Call the function to create your client. 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 client = createAuthClient({
    baseURL: "http://localhost:3000" // the base url of your auth server
})

Usage

Once you've created your client instance, you can use the client to interact with the Better Auth server. The client provides a set of functions by default and they can be extended with plugins.

Example: Sign In

import { createAuthClient } from "better-auth/client"
const client = createAuthClient()
 
await client.signIn.email({
    email: "[email protected]",
    password: "password1234"
})

Hooks

on top of normal methods, the client provides hooks to easily access differnt reactive data. Every hook is avaliable in the root object of the client and they all start with use.

Example: useSession

//make sure you're using the react client
import { createAuthClient } from "better-auth/react"
const { useSession } = createAuthClient() 
 
export function User(){
    const {
        data: session,
        isPending, //loading state
        error //error object 
    } = useSession()
    returns (
        //...
    )
}

Fetch Options

The client uses a libray called better fetch to make requests to the server.

Better fetch is a wrapper around the native fetch API that provides a more convenient way to make requests. It's created by the same team behind Better Auth and is designed to work seamlessly with it.

You can pass any defualt fetch options to the client by passing fetchOptions object to the createAuthClient.

import { createAuthClient } from "better-auth/client"
 
const client = createAuthClient({
    fetchOptions: {
        //any better-fetch options
    },
})

You can also pass fetch options to most of the client functions. Either as the second argument or as a property in the object.

await client.signIn.email({
    email: "[email protected]",
    password: "password1234",
}, {
    onSuccess(ctx){
            //      
    }
})
 
//or
 
await client.signIn.email({
    email: "[email protected]",
    password: "password1234",
    fetchOptions: {
        onSuccess(ctx){
            //      
        }
    },
})

Handling Errors

Most of the client functions return a response object with the following properties:

• data: The response data.
• error: The error object if there was an error.

the error object contains the following properties:

• message: The error message. (e.g., "Invalid email or password")
• status: The HTTP status code.
• statusText: The HTTP status text.

const { data, error } = await client.signIn.email({
    email: "[email protected]",
    password: "password1234"
})
if(error){
    //handle error
}

If the actions accepts a fetchOptions option, you can pass onError callback to handle errors.

 
await client.signIn.email({
    email: "[email protected]",
    password: "password1234",
}, {
    onError(ctx){
        //handle error
    }
})
 
//or
await client.signIn.email({
    email: "[email protected]",
    password: "password1234",
    fetchOptions: {
        onError(ctx){
            //handle error
        }
    }
})

Hooks like useSession also return an error object if there was an error fetching the session. On top of that, they also return a isPending property to indicate if the request is still pending.

const { data, error, isPending } = useSession()
if(error){
    //handle error
}

Plugins

You can extend the client with plugins to add more functionality. Plugins can add new functions to the client or modify existing ones.

Example: Magic Link Plugin

import { createAuthClient } from "better-auth/client"
import { magicLinkClient } from "better-auth/client/plugins"
 
const client = createAuthClient({
    plugins: [
        magicLinkClient()
    ]
})

once you've added the plugin, you can use the new functions provided by the plugin.

await client.signIn.magicLink({
    email: "[email protected]"
})