React SDK overview

The React SDK (@orga-ai/react) is the browser adapter that turns the shared Orga core runtime into idiomatic React primitives—providers, hooks, and lightweight media components. It owns everything between your React tree and the raw WebRTC APIs while delegating security-sensitive work to your backend and the Node SDK.

What it adds on top of core

Provider lifecycle – <OrgaAIProvider> boots the core client exactly once, wires your fetchSessionConfig callback, and exposes connection state through context.
Hooks – useOrgaAI() is a thin projection of the core session state into React, giving you startSession, endSession, media stream handles, and live configuration values.
WebRTC orchestration – Handles device permission prompts, track attachment, ICE gathering, and cleanup in a browser-safe way. Core never touches RTCPeerConnection; the adapter does.

Why teams use it

Rapid UX experiments – Drop-in hooks mean you can wire a prototype session with a few components.
Consistency across platforms – API surface mirrors the React Native adapter, so product logic ports easily.
Framed security story – Because the SDK never sees your permanent API key, the security boundary is clear: React fetches short-lived credentials, Node issues them, Orga validates them.

Runtime expectations

Aspect	Details
React version	18.2+ for concurrent-safe context updates.
Browser APIs	Requires modern WebRTC + Permissions APIs; fallbacks are not provided.
Tooling	Supports Next.js (App Router), Vite, CRA, and custom bundlers that honor package `exports`.
Backend dependency	Needs a proxy route (often built with `@orga-ai/node`) that returns `{ ephemeralToken, iceServers }`.

Conceptual flow (React point of view)

Your app renders <OrgaAIProvider> and passes a function that hits /api/orga-client-secrets.
When UI code calls startSession(), the provider fetches session config, spins up a RTCPeerConnection, and gathers ICE candidates.
The SDK asks Orga core to connectToRealtime, sending the SDP offer plus your ephemeral token.
After Orga responds with an SDP answer and conversation_id, the hook updates live state so your UI can reflect the connected session.
When the provider unmounts—or endSession() runs—it disposes the peer connection and media tracks to avoid leaks.

This cycle mirrors the WebRTC model explanation but highlights the responsibilities specific to web clients.

Relationship to other SDKs

Core (@orga-ai/core) – Provides configuration storage, shared types, and the connectToRealtime helper. The React adapter sits entirely on top.
Node (@orga-ai/node) – Every React deployment has a paired backend route using the Node SDK (or REST equivalent) to mint credentials.
React Native – Shares hook names and configuration schema, making it easy to replicate flows between desktop web, mobile web, and native apps.

Where to go next

Need the step-by-step install path? Start with the React tutorial.
Wiring backend auth? Follow the secure backend proxy how-to.
Looking for exact method signatures? Check the React SDK reference.