chore: add better auth tanstack query client docs

Author: Pagebakers

apps/website/app/(saas-js)/docs/header.tsx

@@ -237,6 +237,11 @@ const HeaderDesktopNavbar = () => {
               </PrimaryNavLink>
             }
           >
+            <Menu.Item value="better-auth-react-query" asChild>
+              <Link href="/docs/better-auth-react-query">
+                Better Auth React Query
+              </Link>
+            </Menu.Item>
             <Menu.Item value="drizzle-crud" asChild>
               <Link href="/docs/drizzle-crud">Drizzle CRUD</Link>
             </Menu.Item>

apps/website/app/(saas-js)/docs/page.tsx

@@ -57,6 +57,15 @@ export default function Page() {
             </Heading>
 
             <List.Root textStyle="lg" gap="2" listStyle="none">
+              <List.Item>
+                <Link
+                  href="/docs/better-auth-react-query"
+                  colorPalette="cyan"
+                  fontWeight="medium"
+                >
+                  Better Auth React Query
+                </Link>
+              </List.Item>
               <List.Item>
                 <Link
                   href="/docs/drizzle-crud"

apps/website/content/saas-js/docs/(open-source)/better-auth-react-query/index.mdx

@@ -0,0 +1,153 @@
+---
+title: Better Auth React Query
+description: A TanStack Query client wrapper for Better Auth.
+---
+
+A TanStack Query client wrapper for [Better Auth](https://better-auth.com). This
+package transforms your Better Auth client into a TanStack Query-compatible
+client with full TypeScript support.
+
+## Installation
+
+```bash
+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:
+
+```ts
+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:
+
+```tsx
+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:
+
+```tsx
+const { data: user } = useQuery(
+  auth.admin.getUser.queryOptions({ query: { id: '123' } }),
+)
+```
+
+Passing query options:
+
+```tsx
+const { data: user } = useQuery(
+  auth.admin.getUser.queryOptions(
+    { query: { id: '123' } },
+    {
+      staleTime: 100,
+    },
+  ),
+)
+```
+
+### Query Keys
+
+You can access query keys directly for cache invalidation:
+
+```ts
+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:
+
+```tsx
+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:
+
+```tsx
+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:
+
+```ts
+// 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
+```

apps/website/content/saas-js/docs/(open-source)/better-auth-react-query/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Better Auth React Query",
+  "root": true,
+  "pages": ["index"]
+}