better-auth-react-query

0.0.5 verified Sat Apr 25 auth: no javascript

A TanStack React Query client wrapper for Better Auth, currently at v0.0.5. This package transforms a Better Auth client into a TanStack Query-compatible client with full TypeScript support. It automatically treats `get` and `list` methods as queries and all other methods as mutations, providing `queryOptions()` and `mutationOptions()` helpers. The package is in early development with no major release cadence. It requires `@tanstack/react-query` >= 5.0.0 and `better-auth` >= 1.4.0. Key differentiators include automatic distinction between queries and mutations, full type inference from Better Auth client configuration, and query key helpers for cache invalidation.

Common errors

error Cannot find module 'better-auth-react-query' or its corresponding type declarations. ↓

cause Package not installed or missing from package.json.

fix

Run 'npm install better-auth-react-query' or add it to dependencies.

error TypeError: createAuthQueryClient is not a function ↓

cause Importing the wrong symbol (e.g., default export does not exist).

fix

Use named import: import { createAuthQueryClient } from 'better-auth-react-query'

error Module not found: Can't resolve 'better-auth/react' ↓

cause better-auth not installed or not configured for React.

fix

Install better-auth: 'npm install better-auth' and ensure React setup.

error TypeError: auth.getSession.queryOptions is not a function ↓

cause Auth client not properly wrapped; createAuthQueryClient not called.

fix

Correct usage: const auth = createAuthQueryClient(authClient); then use auth.getSession.queryOptions()

Warnings

gotcha Package is in early alpha (v0.0.5). API may change without notice. ↓

fix Pin to exact version and test upgrades.

gotcha Requires @tanstack/react-query >= 5.0.0. Not compatible with v4. ↓

fix Upgrade @tanstack/react-query to v5 or later.

gotcha Requires better-auth >= 1.4.0. Older versions may break. ↓

fix Ensure better-auth is at least v1.4.0.

gotcha Methods not starting with 'get' or 'list' are treated as mutations. If your auth client has custom methods that should be queries, they will be incorrectly wrapped. ↓

fix Only methods named get* or list* are queries; all others are mutations. Rename custom methods accordingly.

gotcha No native support for server-side rendering (SSR) or deferred data loading patterns (e.g., placeholderData, keepPreviousData). Must be handled manually. ↓

fix Implement custom query options with TanStack Query's SSR helpers.

Install

npm install better-auth-react-query

yarn add better-auth-react-query

pnpm add better-auth-react-query

Imports

createAuthQueryClient

wrong

const { createAuthQueryClient } = require('better-auth-react-query')

correct

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

Package is ESM-only; named export.

default

wrong

import { default } from 'better-auth-react-query'

correct

import betterAuthReactQuery from 'better-auth-react-query'

No default export; use named import instead.

createAuthQueryClient

wrong

const createAuthQueryClient = require('better-auth-react-query').createAuthQueryClient

correct

const { createAuthQueryClient } = await import('better-auth-react-query')

In CJS environments, use dynamic import; require is not supported.

Quickstart

Demonstrates creating an auth query client and using both queries (getSession) and mutations (signIn.email) with TanStack Query hooks.

import { createAuthQueryClient } from 'better-auth-react-query'
import { createAuthClient } from 'better-auth/react'
import { useQuery, useMutation } from '@tanstack/react-query'

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

function Profile() {
  const { data: session } = useQuery(auth.getSession.queryOptions())
  return <div>Welcome, {session?.user.name}</div>
}

function SignInForm() {
  const signIn = useMutation(auth.signIn.email.mutationOptions())
  const handleSubmit = (e) => {
    e.preventDefault()
    const formData = new FormData(e.currentTarget)
    signIn.mutate({
      email: formData.get('email'),
      password: formData.get('password'),
    })
  }
  return (
    <form onSubmit={handleSubmit}>
      <input name="email" type="email" />
      <input name="password" type="password" />
      <button type="submit" disabled={signIn.isPending}>Sign In</button>
    </form>
  )
}