OmniBase React 19+ SDK
npm install @omnibase/reactReact 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.
!npm version
!License
!TypeScript
| 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 |
``tsx
import { AuthClientProvider, useSession } from '@omnibase/react';
function App() {
return (
);
}
function Dashboard() {
const { session, loading } = useSession();
if (loading) return
return
Installation
bash
npm
npm install @omnibase/reactyarn
yarn add @omnibase/reactpnpm
pnpm add @omnibase/reactbun
bun add @omnibase/react
`Modules Overview
The SDK is organized into three main modules:
- Context -
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 behaviorComplete Workflow Example
`tsx
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 (
{children}
);
}
// 2. Use session hook for authenticated components
function UserProfile() {
const { session, loading } = useSession();
if (loading) return
Loading profile...;
if (!session?.active) {
return Not authenticated;
} return (
{session.identity.traits.email}
User ID: {session.identity.id}
);
}// 3. Protect routes with ProtectedRoute component
function DashboardPage() {
const router = useRouter();
return (
router.push('/auth/login');
return null;
}}
>
Protected Dashboard
);
}// 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 ;
}
`Error Handling
The
hook provides consistent error handling with loading states:`tsx
function SecureComponent() {
const { session, loading } = useSession(); // Handle loading state
if (loading) {
return
Verifying session...;
} // Handle unauthenticated or inactive session
if (!session || !session.active) {
return
Access denied. Please log in.;
} // Session is valid and active
return
Secure content for {session.identity.traits.email};
}
`Environment Configuration
bash
Required: OmniBase API endpoint
NEXT_PUBLIC_API_URL=https://your-api-endpoint.comOr pass directly to AuthClientProvider
basePath="https://your-api-endpoint.com"
``| 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 |
- @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
For detailed API documentation including all hooks, components, and types, visit the full API reference.
MIT