Better Auth React Query

A TanStack Query client wrapper for Better Auth.

A TanStack Query client wrapper for Better Auth. This package transforms your Better Auth client into a TanStack Query-compatible client with full TypeScript support.

Installation

npm install better-auth-react-query
# or
yarn add better-auth-react-query
# or
pnpm add better-auth-react-query

Requirements

@tanstack/react-query >= 5.0.0
better-auth >= 1.4.0

Usage

Setup

First, create a query client from your Better Auth client:

import { createAuthQueryClient } from 'better-auth-react-query'
import { createAuthClient } from 'better-auth/react'

const authClient = createAuthClient()
const auth = createAuthQueryClient(authClient)

Queries

Methods starting with get or list are automatically treated as queries. Use queryOptions() to get TanStack Query compatible options:

import { useQuery } from '@tanstack/react-query'

function Profile() {
  const { data: session } = useQuery(auth.getSession.queryOptions())

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

For queries that require input parameters:

const { data: user } = useQuery(
  auth.admin.getUser.queryOptions({ query: { id: '123' } }),
)

Passing query options:

const { data: user } = useQuery(
  auth.admin.getUser.queryOptions(
    { query: { id: '123' } },
    {
      staleTime: 100,
    },
  ),
)

Query Keys

You can access query keys directly for cache invalidation:

import { useQueryClient } from '@tanstack/react-query'

const queryClient = useQueryClient()

// Invalidate the session query
queryClient.invalidateQueries({ queryKey: auth.getSession.queryKey() })

// With parameters
queryClient.invalidateQueries({
  queryKey: auth.admin.getUser.queryKey({ query: { id: : '123'} }),
})

Mutations

All other methods are treated as mutations. Use mutationOptions() to get TanStack Query compatible options:

import { useMutation } from '@tanstack/react-query'

function SignInForm() {
  const signIn = useMutation(auth.signIn.email.mutationOptions())

  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault()
    const formData = new FormData(e.currentTarget)

    signIn.mutate({
      email: formData.get('email') as string,
      password: formData.get('password') as string,
    })
  }

  return (
    <form onSubmit={handleSubmit}>
      <input name="email" type="email" />
      <input name="password" type="password" />
      <button type="submit" disabled={signIn.isPending}>
        Sign In
      </button>
    </form>
  )
}

Error Handling

Errors from Better Auth are automatically thrown, making them compatible with TanStack Query's error handling:

const signIn = useMutation(
  auth.signIn.email.mutationOptions({
    onError: (error) => {
      console.error('Sign in failed:', error.message)
    },
  }),
)

TypeScript

The package provides full type inference. All query and mutation options are properly typed based on your Better Auth client configuration:

// Types are inferred from your auth client
const { data } = useQuery(auth.getSession.queryOptions())
// data is typed as your session type

const signUp = useMutation(auth.signUp.email.mutationOptions())
// signUp.mutate() expects the correct input type

Introduction