@daveyplate/better-auth-tanstack

Tanstack Query hooks for Better Auth session & JWT token.

More to come soon... (e.g. useListAccounts, SWR port)

Prerequisites

First, you need to install and integrate Better Auth & Tanstack Query.

Installation

npm install @daveyplate/better-auth-tanstack

For the useSession hook to refresh on sign in, sign out, and sign up without email verification, you must manually call refetch, queryClient.invalidateQueries() for ["session"], or queryClient.clear() in the onSuccess callback of each of those functions or after awaiting and checking for an error.

If you are using Next.js App Router with protected middleware routes, router.refresh() is required as well to clear the router cache.

@daveyplate/better-auth-ui The AuthCard accepts an onSessionChange prop which is a great place to refetch for all of the auth functions, where it shows onSessionChange={() => router.refresh()} in the App Router example.

Setting up the AuthQueryProvider

First, you need to set up the AuthQueryProvider in your application. This provider will supply the necessary context for the hooks to function.

import { AuthQueryProvider } from "@daveyplate/better-auth-tanstack"

export default function Layout({
  children,
}: {
  children: React.ReactNode
}) {
    return (
        <AuthQueryProvider>
            {children}
        </AuthQueryProvider>
    )
}

AuthQueryProvider Props

The AuthQueryProvider component accepts the following props. The default staleTime for sessions is 30 seconds and for JWT tokens is 10 minutes.

Creating use-auth-hooks.ts

Create a file named use-auth-hooks.ts and set up the hooks using createAuthHooks function. This function takes the authClient instance and returns the hooks with full type safety and inference from your authClient.

import { createAuthClient } from "better-auth/react"
import { createAuthHooks } from "@daveyplate/better-auth-tanstack"
import { authClient } from "@/lib/auth-client"

export const { useSession, useToken } = createAuthHooks(authClient)

Using the Hooks

useSession

The useSession hook is used to fetch the session.

Props

Example

import { useSession } from "@/hooks/use-auth-hooks"

function MyComponent() {
    const { data: sessionData, session, user, isPending, refetch } = useSession()

    if (isPending) return <div>Loading...</div>

    return <div>Welcome, {user?.email}</div>
}

useToken

The useToken hook is used to fetch the JWT token if better-auth JWT plugin is enabled.

Props

Example

import { useToken } from "@/hooks/use-auth-hooks"

function MyComponent() {
    const { token, isPending } = useToken()

    if (isPending) return <div>Loading...</div>

    return <div>JWT: {token}</div>
}

Server-Side Prefetch - Advanced Usage

If you want to use a hybrid prefetching strategy, this is totally supported.

Tanstack Query - Advanced Server Rendering

SSR prefetchSession

The prefetchSession function is used in the server to prefetch session data and store it in the query client.

Props

RSC Example

import { prefetchSession } from "@daveyplate/better-auth-tanstack/server"
import { HydrationBoundary, QueryClient, dehydrate } from "@tanstack/react-query"
import { headers } from "next/headers"

import { betterAuth } from "better-auth"
import { auth } from "@/lib/auth"

export default async function Page() {
    const queryClient = new QueryClient()

    const { data, session, user } = await prefetchSession(
        auth, queryClient, await headers()
    )

    return (
        <HydrationBoundary state={dehydrate(queryClient)}>
            <ClientPage />
        </HydrationBoundary>
    )
}

License

This project is licensed under the MIT License. See the LICENSE file for details.