{"id":18157,"library":"better-auth-react-query","title":"better-auth-react-query","description":"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.","status":"active","version":"0.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/saas-js/saas-js","tags":["javascript"],"install":[{"cmd":"npm install better-auth-react-query","lang":"bash","label":"npm"},{"cmd":"yarn add better-auth-react-query","lang":"bash","label":"yarn"},{"cmd":"pnpm add better-auth-react-query","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; provides useQuery, useMutation, and QueryClient required by the wrapper.","package":"@tanstack/react-query","optional":false},{"reason":"Peer dependency; the source auth client is created via better-auth.","package":"better-auth","optional":false}],"imports":[{"note":"Package is ESM-only; named export.","wrong":"const { createAuthQueryClient } = require('better-auth-react-query')","symbol":"createAuthQueryClient","correct":"import { createAuthQueryClient } from 'better-auth-react-query'"},{"note":"No default export; use named import instead.","wrong":"import { default } from 'better-auth-react-query'","symbol":"default","correct":"import betterAuthReactQuery from 'better-auth-react-query'"},{"note":"In CJS environments, use dynamic import; require is not supported.","wrong":"const createAuthQueryClient = require('better-auth-react-query').createAuthQueryClient","symbol":"createAuthQueryClient","correct":"const { createAuthQueryClient } = await import('better-auth-react-query')"}],"quickstart":{"code":"import { createAuthQueryClient } from 'better-auth-react-query'\nimport { createAuthClient } from 'better-auth/react'\nimport { useQuery, useMutation } from '@tanstack/react-query'\n\nconst authClient = createAuthClient()\nconst auth = createAuthQueryClient(authClient)\n\nfunction Profile() {\n  const { data: session } = useQuery(auth.getSession.queryOptions())\n  return <div>Welcome, {session?.user.name}</div>\n}\n\nfunction SignInForm() {\n  const signIn = useMutation(auth.signIn.email.mutationOptions())\n  const handleSubmit = (e) => {\n    e.preventDefault()\n    const formData = new FormData(e.currentTarget)\n    signIn.mutate({\n      email: formData.get('email'),\n      password: formData.get('password'),\n    })\n  }\n  return (\n    <form onSubmit={handleSubmit}>\n      <input name=\"email\" type=\"email\" />\n      <input name=\"password\" type=\"password\" />\n      <button type=\"submit\" disabled={signIn.isPending}>Sign In</button>\n    </form>\n  )\n}","lang":"typescript","description":"Demonstrates creating an auth query client and using both queries (getSession) and mutations (signIn.email) with TanStack Query hooks."},"warnings":[{"fix":"Pin to exact version and test upgrades.","message":"Package is in early alpha (v0.0.5). API may change without notice.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Upgrade @tanstack/react-query to v5 or later.","message":"Requires @tanstack/react-query >= 5.0.0. Not compatible with v4.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Ensure better-auth is at least v1.4.0.","message":"Requires better-auth >= 1.4.0. Older versions may break.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Only methods named get* or list* are queries; all others are mutations. Rename custom methods accordingly.","message":"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.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Implement custom query options with TanStack Query's SSR helpers.","message":"No native support for server-side rendering (SSR) or deferred data loading patterns (e.g., placeholderData, keepPreviousData). Must be handled manually.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run 'npm install better-auth-react-query' or add it to dependencies.","cause":"Package not installed or missing from package.json.","error":"Cannot find module 'better-auth-react-query' or its corresponding type declarations."},{"fix":"Use named import: import { createAuthQueryClient } from 'better-auth-react-query'","cause":"Importing the wrong symbol (e.g., default export does not exist).","error":"TypeError: createAuthQueryClient is not a function"},{"fix":"Install better-auth: 'npm install better-auth' and ensure React setup.","cause":"better-auth not installed or not configured for React.","error":"Module not found: Can't resolve 'better-auth/react'"},{"fix":"Correct usage: const auth = createAuthQueryClient(authClient); then use auth.getSession.queryOptions()","cause":"Auth client not properly wrapped; createAuthQueryClient not called.","error":"TypeError: auth.getSession.queryOptions is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}