Providers

API reference for the providers exported from @urun-sh/react.

Public API at a glance

Name	Import	Description
`UrunProvider`	`@urun-sh/react`	Configures the app proxy
`UrunErrorBoundary`	`@urun-sh/react`	Catches session/transport errors
`UrunWorkOSProvider`	`@urun-sh/react/workos`	WorkOS auth bridge (React)
`UrunWorkOSProvider`	`@urun-sh/react/next-workos`	WorkOS auth bridge (Next.js)
`UrunAuthProvider`	`@urun-sh/react`	Generic bridge with `getAccessToken`
`UrunJwtProvider`	`@urun-sh/react`	Static JWT (tests / customer-JWT)

For patterns and narrative, see React Providers.

UrunProvider

<UrunProvider baseUrl orgId appId authProvider>{children}</UrunProvider>

Configures the app proxy returned by useApp(). Nest it inside an auth bridge that supplies access tokens.

Prop	Type	Required	Description
`baseUrl`	`string`	if `jwt`/`orgId` set	Base URL of your uRun backend (e.g. `https://urun.sh`). Optional in self-mint mode (see below) — the token endpoint's response configures it.
`orgId`	`string`	if `jwt` set	Your organization ID. Leave it out (with `jwt`) to activate self-mint mode.
`appId`	`string`	for `useApp()`	The deployed app `useApp()` resolves (optional in the prop types; `useApp()` throws without it). Alias of `app`; `app` wins when both are set.
`app`	`string`	in self-mint mode	Alias of `appId`. Required in self-mint mode.
`authProvider`	`string`	—	Auth provider id, e.g. `"workos"`
`jwt`	`string`	—	Manual short-lived user JWT (bypasses the auth bridge and self-mint; advanced)
`tokenEndpoint`	`string`	self-mint mode only	Token-exchange endpoint POSTed after mount (default `/api/urun-token`, the `@urun-sh/next` `createTokenRoute()` on-ramp). Expects `{ token, orgId, gatewayUrl? }`.
`errorFallback`	`ReactNode \| (error) => ReactNode`	—	Self-mint mode only: rendered when the token endpoint fails
`eventsUrl`	`string`	—	Local developer-tooling endpoint that receives structured session diagnostics (e.g. the endpoint `urun demo` runs); never receives tokens or function args
`fallback`	`ReactNode \| (error) => ReactNode`	—	Rendered by the built-in error boundary on session/transport errors

Self-mint mode — omit both jwt and orgId and UrunProvider POSTs to tokenEndpoint after mount, reading { token, orgId, gatewayUrl? } off the response; the org is derived server-side from your URUN_API_KEY, so app code never hardcodes it. app becomes the one required prop. Passing jwt (or a non-empty orgId) keeps the explicit-JWT behavior shown below, where baseUrl/orgId are required.

import { UrunProvider } from '@urun-sh/react'
import { UrunWorkOSProvider } from '@urun-sh/react/workos'

<UrunWorkOSProvider clientId="client_...">
  <UrunProvider baseUrl="https://urun.sh" orgId="your-org-id" authProvider="workos" appId="my-app">
    {children}
  </UrunProvider>
</UrunWorkOSProvider>

UrunErrorBoundary

<UrunErrorBoundary fallback={<Fallback />}>{children}</UrunErrorBoundary>

A React error boundary that catches session and transport errors thrown inside the tree and renders a fallback instead of crashing.

Auth bridges

Each bridge supplies UrunProvider with short-lived access tokens. Pick the one matching your auth.

Bridge	Import	Notes
`UrunWorkOSProvider`	`@urun-sh/react/workos`	Reads WorkOS AuthKit context; forwards refreshed access tokens
`UrunWorkOSProvider`	`@urun-sh/react/next-workos`	Same, for Next.js WorkOS apps
`UrunAuthProvider`	`@urun-sh/react`	Provide a `getAccessToken: () => string \| Promise<string>`
`UrunJwtProvider`	`@urun-sh/react`	A static JWT, intended for tests and customer-JWT flows

import { UrunAuthProvider } from '@urun-sh/react'

<UrunAuthProvider getAccessToken={async () => tokenStore.current()}>
  <UrunProvider baseUrl="https://urun.sh" orgId="your-org-id" authProvider="workos" appId="my-app">
    {children}
  </UrunProvider>
</UrunAuthProvider>

No secrets in the browser

Bridges forward short-lived user JWTs only. Never pass a server API key or the urun_… deploy key to a browser client.

Styling

Import the package CSS when using the styled built-in components (media components, session-state components, the component registry built-ins):

import '@urun-sh/react/styles.css'