React Router SDK - Wacht Platform Documentation

Overview

@wacht/react-router adds authentication, user management, and multi-tenancy to React Router v7 applications.

What’s Included

Authentication Components - Pre-built sign-in, sign-up, and SSO callback components
Authentication Hooks - Hooks for handling sign-in, sign-up, password reset, and more
User Management - Hooks and components for profile management
Organization & Workspace Support - Multi-tenant support with organizations and workspaces
Session Management - Automatic session handling with token refresh
Notifications - Real-time notification support with hooks and components
AI Agents - Hooks for building AI agent features with context and integrations

Installation

pnpm add @wacht/react-router @wacht/types

Or with npm:

npm install @wacht/react-router @wacht/types

Quick Start

1. Wrap Your Application

Wrap your application with the DeploymentProvider in your root route:

import { DeploymentProvider } from '@wacht/react-router'

export function loader() {
  return {
    publicKey: process.env.WACHT_PUBLIC_KEY
  }
}

export default function Root({ loaderData }) {
  return (
    <DeploymentProvider publicKey={loaderData.publicKey}>
      <Outlet />
    </DeploymentProvider>
  )
}

// routes/signin.tsx
import { SignInForm } from '@wacht/react-router'

export default function SignIn() {
  return (
    <div className="auth-page">
      <h1>Sign In</h1>
      <SignInForm />
    </div>
  )
}

// routes/signup.tsx
import { SignUpForm } from '@wacht/react-router'

export default function SignUp() {
  return (
    <div className="auth-page">
      <h1>Sign Up</h1>
      <SignUpForm />
    </div>
  )
}

3. Protect Routes

// routes/dashboard.tsx
import { SignedIn } from '@wacht/react-router'
import { useSession } from '@wacht/react-router'

export default function Dashboard() {
  return (
    <SignedIn>
      <DashboardContent />
    </SignedIn>
  )
}

function DashboardContent() {
  const { session } = useSession()

  return (
    <div>
      <h1>Welcome, {session.user.first_name}!</h1>
    </div>
  )
}

// routes/root.tsx
import { UserButton } from '@wacht/react-router'
import { SignedIn } from '@wacht/react-router'

export default function Layout() {
  return (
    <html>
      <body>
        <nav>
          <h1>My App</h1>
          <SignedIn>
            <UserButton />
          </SignedIn>
        </nav>
        <Outlet />
      </body>
    </html>
  )
}

Configuration

Environment Variables

Set these environment variables in your React Router app:

# .env
WACHT_PUBLIC_KEY=your_public_key_here

UI Customization

You can customize the UI by passing uiOverwrites to the provider:

import { DeploymentProvider } from '@wacht/react-router'

export default function Root({ loaderData }) {
  return (
    <DeploymentProvider
      publicKey={loaderData.publicKey}
      uiOverwrites={{
        primaryColor: '#4f46e5',
        borderRadius: '8px',
        fontFamily: 'Inter, sans-serif'
      }}
    >
      <Outlet />
    </DeploymentProvider>
  )
}

Components

SignInForm

Complete sign-in form with email/password, OTP, magic link, and social authentication.

import { SignInForm } from '@wacht/react-router'

function LoginPage() {
  return <SignInForm />
}

SignUpForm

Complete sign-up form with validation and social authentication.

import { SignUpForm } from '@wacht/react-router'

function RegisterPage() {
  return <SignUpForm />
}

UserButton

User profile dropdown with account management and sign-out.

import { UserButton } from '@wacht/react-router'

function Navbar() {
  return (
    <nav>
      <UserButton />
    </nav>
  )
}

OrganizationSwitcher

Organization and workspace switcher for multi-tenant apps.

import { OrganizationSwitcher } from '@wacht/react-router'

function Sidebar() {
  return (
    <aside>
      <OrganizationSwitcher />
    </aside>
  )
}

SignedIn / SignedOut

Conditional rendering based on authentication state.

import { SignedIn, SignedOut } from '@wacht/react-router'

function ProtectedPage() {
  return (
    <>
      <SignedOut>
        <p>Please sign in to continue</p>
      </SignedOut>
      <SignedIn>
        <p>Welcome back!</p>
      </SignedIn>
    </>
  )
}

Hooks

useSignIn

Handle user authentication with multiple strategies.

import { useSignIn, SignInStrategy } from '@wacht/react-router'

function CustomSignIn() {
  const { signIn, loading, errors } = useSignIn()

  const handleEmailSignIn = async (email: string, password: string) => {
    const emailSignIn = signIn.createStrategy(SignInStrategy.Email)
    const result = await emailSignIn({ email, password })

    if (result.data) {
      console.log('Sign in successful')
    }
  }

  return <div>{/* Custom sign-in UI */}</div>
}

useSignUp

Handle user registration.

import { useSignUp } from '@wacht/react-router'

function CustomSignUp() {
  const { signUp, loading, errors } = useSignUp()

  const handleSignUp = async (userData) => {
    const result = await signUp.create(userData)

    if (result.data) {
      console.log('Sign up successful')
    }
  }

  return <div>{/* Custom sign-up UI */}</div>
}

useSession

Access and manage user sessions.

import { useSession } from '@wacht/react-router'

function UserProfile() {
  const { session, loading, signOut } = useSession()

  if (loading) return <div>Loading...</div>

  return (
    <div>
      <h1>{session.user.first_name} {session.user.last_name}</h1>
      <button onClick={() => signOut()}>Sign Out</button>
    </div>
  )
}

useUser

Manage user profile and settings.

import { useUser } from '@wacht/react-router'

function ProfileSettings() {
  const { user, updateProfile, updatePassword } = useUser()

  const handleUpdate = async () => {
    await updateProfile({
      first_name: 'John',
      last_name: 'Doe'
    })
  }

  return <div>{/* Profile settings UI */}</div>
}

useOrganization

Manage organizations and memberships.

import { useOrganization } from '@wacht/react-router'

function OrganizationPage() {
  const { organization, members, loading } = useOrganization()

  if (loading) return <div>Loading...</div>

  return (
    <div>
      <h1>{organization.name}</h1>
      <p>{members.length} members</p>
    </div>
  )
}

useWorkspace

Manage workspaces within organizations.

import { useWorkspace } from '@wacht/react-router'

function WorkspaceSettings() {
  const { workspace, updateWorkspace } = useWorkspace()

  return (
    <div>
      <h1>{workspace.name}</h1>
      <button onClick={() => updateWorkspace({ name: 'New Name' })}>
        Update Name
      </button>
    </div>
  )
}

useNavigation

Navigate between authentication pages and routes.

import { useNavigation } from '@wacht/react-router'

function CustomRedirects() {
  const { navigate, navigateToSignIn, navigateToSignUp } = useNavigation()

  return (
    <div>
      <button onClick={() => navigate('/dashboard')}>
        Go to Dashboard
      </button>
      <button onClick={() => navigateToSignIn()}>
        Go to Sign In
      </button>
    </div>
  )
}

API Reference

Components

Component	Description
`SignInForm`	Complete sign-in form component
`SignUpForm`	Complete sign-up form component
`UserButton`	User profile dropdown
`OrganizationSwitcher`	Organization/workspace switcher
`ManageAccount`	Account management component
`ManageOrganization`	Organization management component
`CreateOrganizationForm`	Create organization form
`CreateWorkspaceForm`	Create workspace form
`SignedIn`	Render children only when signed in
`SignedOut`	Render children only when signed out
`SSOCallback`	OAuth/SSO callback handler
`WaitlistForm`	Waitlist signup form
`MagicLinkVerification`	Magic link verification handler
`NotificationBell`	Notification bell icon
`NotificationPopover`	Notification popover
`NotificationPanel`	Full notification panel

Hooks

Hook	Description
`useSignIn`	Handle user sign-in
`useSignUp`	Handle user sign-up
`useSession`	Access and manage session
`useUser`	Manage user profile
`useDeployment`	Access deployment settings
`useClient`	Access configured HTTP client
`useNavigation`	Manage navigation redirects
`useForgotPassword`	Handle password reset
`useMagicLinkVerification`	Handle magic link authentication
`useSSOCallback`	Handle OAuth callbacks
`useWaitlist`	Handle waitlist signup
`useOrganizationList`	List user’s organizations
`useActiveOrganization`	Access active organization
`useOrganizationMemberships`	Manage organization memberships
`useWorkspaceList`	List workspaces
`useActiveWorkspace`	Access active workspace
`useWorkspaceMemberships`	Manage workspace memberships
`useNotifications`	Access notifications
`useNotificationStream`	Real-time notification stream
`useAgentContext`	Access AI agent context
`useAgentSession`	Access AI agent session
`useInvitation`	Handle organization invitations

Examples

Complete Authentication Flow

// routes/auth.tsx
import { Outlet } from 'react-router'
import { SignedIn, SignedOut, useSession } from '@wacht/react-router'

export default function AuthLayout() {
  return (
    <div>
      <SignedOut>
        <div className="auth-cta">
          <p>Sign in to access your account</p>
        </div>
      </SignedOut>
      <SignedIn>
        <UserGreeting />
      </SignedIn>
      <Outlet />
    </div>
  )
}

function UserGreeting() {
  const { session } = useSession()
  return <p>Hello, {session.user.first_name}!</p>
}

Protected Routes

// routes/protected.tsx
import { SignedIn, NavigateToSignIn } from '@wacht/react-router'

export default function Protected() {
  return (
    <SignedIn>
      <ProtectedContent />
    </SignedIn>
  )
}

function ProtectedContent() {
  return <div>This is protected content</div>
}

Organization Management

// routes/orgs.$orgId.tsx
import { useOrganization, useOrganizationList } from '@wacht/react-router'
import { useParams } from 'react-router'

export default function OrganizationPage() {
  const { orgId } = useParams()
  const { organization, loading } = useOrganization(orgId)

  if (loading) return <div>Loading...</div>

  return (
    <div>
      <h1>{organization.name}</h1>
      <p>{organization.description}</p>
    </div>
  )
}

Next.js SDK - Next.js SDK documentation
TanStack Router SDK - TanStack Router SDK documentation
API Reference - Frontend API reference

Getting Started

Authentication Components

Authentication Hooks

Multi-Tenancy Components

Multi-Tenancy Hooks

Agent Hooks

User Components

User Hooks

Other Components

Other Hooks

​Overview

​What’s Included

​Installation

​Quick Start

​1. Wrap Your Application

​2. Create Sign-In and Sign-Up Routes

​3. Protect Routes

​4. Add User Menu

​Configuration

​Environment Variables

​UI Customization

​Components

​SignInForm

​SignUpForm

​UserButton

​OrganizationSwitcher

​SignedIn / SignedOut

​Hooks

​useSignIn

​useSignUp

​useSession

​useUser

​useOrganization

​useWorkspace

​useNavigation

​API Reference

​Components

​Hooks

​Examples

​Complete Authentication Flow

​Protected Routes

​Organization Management

​Related

Overview

What’s Included

Installation

Quick Start

1. Wrap Your Application

2. Create Sign-In and Sign-Up Routes

3. Protect Routes

4. Add User Menu

Configuration

Environment Variables

UI Customization

Components

SignInForm

SignUpForm

UserButton

OrganizationSwitcher

SignedIn / SignedOut

Hooks

useSignIn

useSignUp

useSession

useUser

useOrganization

useWorkspace

useNavigation

API Reference

Components

Hooks

Examples

Complete Authentication Flow

Protected Routes

Organization Management

Related