Basic Usage
This guide covers the essential authentication flows: creating accounts, signing in, managing sessions, and protecting routes.
Create the Auth Client
On the client side, create an auth client that communicates with your API:
import { createAuthClient } from "better-auth/react";
export const authClient = createAuthClient({
baseURL: "http://localhost:3000",
});
export const { signIn, signUp, signOut, useSession } = authClient;Sign Up
Create a new user with email and password:
import { signUp } from "@/lib/auth-client";
async function handleSignUp() {
const { data, error } = await signUp.email({
email: "user@example.com",
password: "securepassword123",
name: "John Doe",
});
if (error) {
console.error("Sign up failed:", error.message);
return;
}
console.log("User created:", data.user);
}Sign In
Email & Password
import { signIn } from "@/lib/auth-client";
async function handleSignIn() {
const { data, error } = await signIn.email({
email: "user@example.com",
password: "securepassword123",
});
if (error) {
console.error("Sign in failed:", error.message);
return;
}
// User is now signed in
console.log("Session:", data.session);
}Social Sign-In
import { signIn } from "@/lib/auth-client";
// Google
await signIn.social({ provider: "google" });
// GitHub
await signIn.social({ provider: "github" });Session Management
Get Current Session
Use the useSession hook in React components:
import { useSession } from "@/lib/auth-client";
function Profile() {
const { data: session, isPending } = useSession();
if (isPending) return <div>Loading...</div>;
if (!session) return <div>Not signed in</div>;
return (
<div>
<h1>Welcome, {session.user.name}</h1>
<p>{session.user.email}</p>
</div>
);
}Sign Out
import { signOut } from "@/lib/auth-client";
async function handleSignOut() {
await signOut();
// User is now signed out
}Protecting Routes
Server-Side (Next.js)
import { auth } from "@/auth";
import { headers } from "next/headers";
export async function getServerSession() {
const session = await auth.api.getSession({
headers: await headers(),
});
return session;
}Use it in a server component:
import { getServerSession } from "@/lib/session";
import { redirect } from "next/navigation";
export default async function DashboardPage() {
const session = await getServerSession();
if (!session) {
redirect("/sign-in");
}
return <Dashboard user={session.user} />;
}Client-Side Guard
"use client";
import { useSession } from "@/lib/auth-client";
import { useRouter } from "next/navigation";
import { useEffect } from "react";
export function AuthGuard({ children }: { children: React.ReactNode }) {
const { data: session, isPending } = useSession();
const router = useRouter();
useEffect(() => {
if (!isPending && !session) {
router.push("/sign-in");
}
}, [session, isPending, router]);
if (isPending) return <div>Loading...</div>;
if (!session) return null;
return <>{children}</>;
}Quick Reference
| Action | Method |
|---|---|
| Sign up | signUp.email({ email, password, name }) |
| Sign in (email) | signIn.email({ email, password }) |
| Sign in (social) | signIn.social({ provider }) |
| Get session | useSession() hook |
| Sign out | signOut() |
| Server session | auth.api.getSession({ headers }) |
Next Steps
- Learn about Session Management in depth
- Set up Social Sign-on providers
- Add Two Factor Authentication for extra security