@omnibase/react

React SDK for OmniBase authentication and session management

The OmniBase React SDK provides React 19+ hooks, components, and context providers for integrating Ory Kratos authentication flows into your React applications. Built on top of @omnibase/core-js, it delivers type-safe session management, route protection, and seamless authentication state handling.

Features

| Feature | Description | Documentation | |---------|-------------|---------------| | Session Management | React hook for accessing user session with loading states | Session Docs | | Authentication Context | Provider component for app-wide authentication configuration | Context Docs | | Route Protection | Component-based client-side route guards | Protection Docs | | Direct Ory Access | Low-level hook for custom authentication flows | API Reference | | Type Safety | Full TypeScript definitions with comprehensive type coverage | Types Reference |

Quick Start

import { AuthClientProvider, useSession } from '@omnibase/react';

function App() {
  return (
    <AuthClientProvider basePath="http://localhost:4000">
      <Dashboard />
    </AuthClientProvider>
  );
}

function Dashboard() {
  const { session, loading } = useSession();

  if (loading) return <div>Loading...</div>;
  if (!session || !session.active) return <div>Please log in</div>;

  return <div>Welcome, {session.identity.traits.email}!</div>;
}

Installation

# npm
npm install @omnibase/react

# yarn
yarn add @omnibase/react

# pnpm
pnpm add @omnibase/react

# bun
bun add @omnibase/react

Modules Overview

The SDK is organized into three main modules:

• Context - AuthClientProvider for app-wide authentication configuration and useAuth() for accessing the Ory Kratos client instance
• Hooks - useSession() for session state management with automatic loading and error handling
• Components - ProtectedRoute for client-side route protection with customizable redirect behavior

Complete Workflow Example

import { 
  AuthClientProvider, 
  useSession, 
  useAuth,
  ProtectedRoute 
} from '@omnibase/react';
import { useRouter } from 'next/navigation';

// 1. Wrap your app with the provider
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <AuthClientProvider basePath={process.env.NEXT_PUBLIC_API_URL!}>
      {children}
    </AuthClientProvider>
  );
}

// 2. Use session hook for authenticated components
function UserProfile() {
  const { session, loading } = useSession();

  if (loading) return <div>Loading profile...</div>;
  
  if (!session?.active) {
    return <div>Not authenticated</div>;
  }

  return (
    <div>
      <h1>{session.identity.traits.email}</h1>
      <p>User ID: {session.identity.id}</p>
    </div>
  );
}

// 3. Protect routes with ProtectedRoute component
function DashboardPage() {
  const router = useRouter();

  return (
    <ProtectedRoute
      onInvalidSession={() => {
        router.push('/auth/login');
        return null;
      }}
    >
      <div>
        <h1>Protected Dashboard</h1>
        <UserProfile />
      </div>
    </ProtectedRoute>
  );
}

// 4. Use direct Ory access for custom flows
function LogoutButton() {
  const ory = useAuth();

  const handleLogout = async () => {
    const { data } = await ory.createBrowserLogoutFlow();
    window.location.href = data.logout_url;
  };

  return <button onClick={handleLogout}>Sign Out</button>;
}

Error Handling

The useSession() hook provides consistent error handling with loading states:

function SecureComponent() {
  const { session, loading } = useSession();

  // Handle loading state
  if (loading) {
    return <div>Verifying session...</div>;
  }

  // Handle unauthenticated or inactive session
  if (!session || !session.active) {
    return <div>Access denied. Please log in.</div>;
  }

  // Session is valid and active
  return <div>Secure content for {session.identity.traits.email}</div>;
}

Environment Configuration

# Required: OmniBase API endpoint
NEXT_PUBLIC_API_URL=https://your-api-endpoint.com

# Or pass directly to AuthClientProvider
# basePath="https://your-api-endpoint.com"

Environment Support

| Environment | Status | Notes | |-------------|--------|-------| | React 19+ | ✅ | Required peer dependency | | React 18 | ❌ | Not supported | | TypeScript | ✅ | Full type definitions included | | Next.js | ✅ | Works with App Router and Pages Router | | Vite | ✅ | Full compatibility | | Create React App | ✅ | Full compatibility | | ESM/CJS | ✅ | Both module formats supported |

Related Packages

• @omnibase/core-js - Core SDK with all API methods for authentication, tenants, and database operations
• @omnibase/shadcn - Pre-built authentication UI components with shadcn/ui integration
• @omnibase/nextjs - Next.js optimized SDK with middleware and server component support

API Reference

For detailed API documentation including all hooks, components, and types, visit the full API reference.

License

MIT