docs(react-sdk): add comprehensive React SDK documentation

Author: yash-pouranik

.github/scripts/generate-changelog-entry.js

@@ -46,9 +46,9 @@ Rules:
 - If no PRs were merged, output: <Update label="${TODAY}" description="Week of ${WEEK_START}–${TODAY}" tags={[]}>No significant changes this week.</Update>`;
 
 const payload = JSON.stringify({
-  model: "llama-3.1-70b-versatile",
+  model: "llama-3.3-70b-versatile",
   messages: [{ role: "user", content: prompt }],
-  max_tokens: 4096,
+  max_tokens: 10000,
   temperature: 0.3,
 });
 

mintlify/docs/docs.json

@@ -56,7 +56,7 @@
              ]
            },
           {
-            "group": "SDK",
+            "group": "TypeScript SDK",
             "pages": [
               "sdk/overview",
               "sdk/auth",
@@ -66,6 +66,18 @@
               "sdk/mail"
             ]
           },
+          {
+            "group": "React SDK",
+            "pages": [
+              "react-sdk/overview",
+              "react-sdk/ur-provider",
+              "react-sdk/ur-auth",
+              "react-sdk/ur-user-button",
+              "react-sdk/routing",
+              "react-sdk/hooks",
+              "react-sdk/integration"
+            ]
+          },
           {
             "group": "Security & Limits",
             "pages": [

mintlify/docs/react-sdk/hooks.mdx

@@ -0,0 +1,109 @@
+---
+title: "React Hooks"
+description: "Interact with the urBackend SDK natively using React hooks."
+---
+
+The `@urbackend/react` SDK exports several hooks to make it easy to access authentication state and perform database/storage operations within your components.
+
+All hooks require your component to be mounted somewhere inside the `<UrProvider>`.
+
+## `useUser()`
+
+The easiest way to read the current authenticated user's profile and state.
+
+```tsx
+import { useUser } from '@urbackend/react';
+
+function UserProfile() {
+  const { user, isAuthenticated, isLoading, isInitializing } = useUser();
+
+  if (isInitializing) return <div>Loading session...</div>;
+  if (!isAuthenticated) return <div>Please log in</div>;
+
+  return (
+    <div>
+      <h1>Welcome, {user?.name}</h1>
+      <p>Email: {user?.email}</p>
+    </div>
+  );
+}
+```
+
+## `useAuth()`
+
+Provides access to authentication methods like login, signup, and logout.
+
+```tsx
+import { useAuth } from '@urbackend/react';
+
+function CustomLoginForm() {
+  const { login, logout, error, isLoading } = useAuth();
+
+  const handleLogin = async () => {
+    await login('alice@example.com', 'password123');
+  };
+
+  return (
+    <div>
+      <button onClick={handleLogin} disabled={isLoading}>
+        Log In
+      </button>
+      <button onClick={logout}>Log Out</button>
+      {error && <p style={{ color: 'red' }}>{error}</p>}
+    </div>
+  );
+}
+```
+
+## `useDb()`
+
+Provides direct access to the `urBackend` database client. Operations are automatically authenticated with the current user's session token for Row-Level Security (RLS).
+
+```tsx
+import { useState, useEffect } from 'react';
+import { useDb } from '@urbackend/react';
+
+function ProductList() {
+  const db = useDb();
+  const [products, setProducts] = useState([]);
+
+  useEffect(() => {
+    async function fetchProducts() {
+      // Automatically passes the user's token for RLS policies
+      const data = await db.getAll('products', { limit: 10 });
+      setProducts(data);
+    }
+    fetchProducts();
+  }, [db]);
+
+  return (
+    <ul>
+      {products.map(p => <li key={p._id}>{p.name}</li>)}
+    </ul>
+  );
+}
+```
+
+## `useStorage()`
+
+Provides access to the Storage API for uploading and deleting files.
+
+```tsx
+import { useStorage } from '@urbackend/react';
+
+function Uploader() {
+  const storage = useStorage();
+
+  const handleUpload = async (file: File) => {
+    const result = await storage.upload(file, 'avatars');
+    console.log("File available at:", result.url);
+  };
+
+  return (
+    <input 
+      type="file" 
+      onChange={(e) => handleUpload(e.target.files[0])} 
+    />
+  );
+}
+```

mintlify/docs/react-sdk/integration.mdx

@@ -0,0 +1,97 @@
+---
+title: "Full Integration Example"
+description: "See how all the pieces of the React SDK fit together in a complete application."
+---
+
+Here is a complete, single-file example showing how to build an application with urBackend using `create-react-app` or `Vite`.
+
+This example includes:
+1. The global `<UrProvider>`.
+2. A client-side router (using simple state for demonstration).
+3. A public Login page (`<GuestRoute>`) with the pre-built `<UrAuth>` UI.
+4. A secure Dashboard page (`<ProtectedRoute>`).
+5. A `<UrUserButton>` for the profile dropdown and logout.
+
+## `App.tsx`
+
+```tsx
+import { useState, useEffect } from 'react';
+import { 
+  UrProvider, 
+  UrAuth, 
+  ProtectedRoute, 
+  GuestRoute, 
+  UrUserButton, 
+  useUser 
+} from '@urbackend/react';
+
+// --- Components ---
+
+function LoginPage({ navigate }: { navigate: (path: string) => void }) {
+  return (
+    // If they are already logged in, send them straight to the dashboard
+    <GuestRoute fallback={<div>Loading...</div>} onRedirect={() => navigate('/dashboard')}>
+      <div style={{ display: 'flex', height: '100vh', alignItems: 'center', justifyContent: 'center' }}>
+        <UrAuth providers={['google', 'github']} />
+      </div>
+    </GuestRoute>
+  );
+}
+
+function Dashboard({ navigate }: { navigate: (path: string) => void }) {
+  const { user } = useUser();
+
+  return (
+    // If they are NOT logged in, kick them back to login
+    <ProtectedRoute fallback={<div>Loading...</div>} onRedirect={() => navigate('/')}>
+      
+      {/* Top right profile dropdown */}
+      <UrUserButton 
+        onSettingsClick={() => alert('Opening Settings')}
+        onProfileClick={() => alert('Opening Profile')}
+      />
+      
+      <div style={{ padding: '40px', fontFamily: 'sans-serif' }}>
+        <h1>Dashboard</h1>
+        <p>Welcome back, {user?.name || user?.email}!</p>
+        <p>Your user ID is: <code>{user?._id}</code></p>
+      </div>
+
+    </ProtectedRoute>
+  );
+}
+
+// --- Main Router ---
+
+function Router() {
+  const [route, setRoute] = useState(window.location.pathname);
+
+  useEffect(() => {
+    const handlePop = () => setRoute(window.location.pathname);
+    window.addEventListener('popstate', handlePop);
+    return () => window.removeEventListener('popstate', handlePop);
+  }, []);
+
+  const navigate = (path: string) => {
+    window.history.pushState({}, '', path);
+    setRoute(path);
+  };
+
+  if (route === '/dashboard') {
+    return <Dashboard navigate={navigate} />;
+  }
+
+  // Default route (Login)
+  return <LoginPage navigate={navigate} />;
+}
+
+// --- Root Entry Point ---
+
+export default function App() {
+  return (
+    <UrProvider apiKey="pk_live_your_publishable_api_key">
+      <Router />
+    </UrProvider>
+  );
+}
+```

mintlify/docs/react-sdk/overview.mdx

@@ -0,0 +1,96 @@
+---
+title: "React SDK Overview"
+description: "Build full-stack React applications in minutes with pre-built authentication UI, session management, and hooks."
+---
+
+The `@urbackend/react` SDK provides everything you need to build secure, scalable React applications on top of urBackend. It handles the heavy lifting of session persistence, social logins, and routing out of the box.
+
+## Features
+
+- **Pre-built Auth UI**: A beautiful, customizable `<UrAuth />` component for login/signup (email/password & social).
+- **Session Management**: Automatically persists tokens to `localStorage` and handles silent background refreshes.
+- **Protected Routing**: Simple `<ProtectedRoute>` and `<GuestRoute>` wrappers to secure your pages.
+- **Customizable UI**: Includes `<UrUserButton />` for a ready-to-use profile dropdown.
+- **Powerful Hooks**: `useUser`, `useAuth`, `useDb`, and `useStorage` to interact with your backend data natively.
+
+## Installation
+
+Install the React SDK along with the core TypeScript SDK (which it uses under the hood):
+
+```bash
+npm install @urbackend/react @urbackend/sdk
+```
+
+## Setup (Create React App / Vite)
+
+To get started, wrap your root application with the `<UrProvider>` and pass your project's Publishable API Key.
+
+<Warning>
+**Always use your Publishable Key (`pk_live_...`) in the browser.** Never use your Secret Key (`sk_live_...`) on the frontend, as it grants full administrative access.
+</Warning>
+
+```tsx src/main.tsx
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App'
+import { UrProvider } from '@urbackend/react'
+import './index.css'
+
+// Initialize the UrBackend Provider
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <UrProvider apiKey="pk_live_your_publishable_api_key">
+      <App />
+    </UrProvider>
+  </React.StrictMode>,
+)
+```
+
+## Setup (Next.js App Router)
+
+If you are using Next.js with the App Router, create a Client Component provider to wrap your application:
+
+```tsx src/components/Providers.tsx
+"use client";
+
+import { UrProvider } from '@urbackend/react';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <UrProvider apiKey={process.env.NEXT_PUBLIC_URBACKEND_API_KEY!}>
+      {children}
+    </UrProvider>
+  );
+}
+```
+
+Then, wrap your layout:
+
+```tsx src/app/layout.tsx
+import { Providers } from '../components/Providers';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <Providers>
+          {children}
+        </Providers>
+      </body>
+    </html>
+  );
+}
+```
+
+## Next Steps
+
+Now that your provider is set up, you can start building your authentication flow and accessing your data.
+
+<CardGroup cols={2}>
+  <Card title="Authentication UI" icon="lock" href="/react-sdk/ur-auth">
+    Add a login screen in one line of code.
+  </Card>
+  <Card title="Protect Routes" icon="shield-check" href="/react-sdk/routing">
+    Secure your application pages.
+  </Card>
+</CardGroup>