Your First Health Universe App

This tutorial walks through building a minimal clinical frontend on Health Universe with React and the @health-universe/react SDK. By the end you'll have an app that authenticates against the Health Universe API and renders a list of patients.

For a complete, runnable example — provider wiring, a local dev proxy, and a tabbed app with a run-review reader — clone the react-starter repo as a starting point.

Step 1: Install the SDK

npm install @health-universe/react @tanstack/react-query react

react and @tanstack/react-query are peer dependencies, so they live in your app. You do not install @clerk/clerk-react — the SDK manages Clerk internally (requires @health-universe/react ≥ 0.2.2).

Step 2: How it works with your Health Universe account

You don't build a login or manage sessions. When your app runs on Health Universe, the user is already signed in to their Health Universe account, and the SDK authenticates every API request as that user automatically. You just give the provider a way to read the current account, and the platform takes care of the rest.

Step 3: Set up HealthUniverseProvider

Wrap your app once near the root. HealthUniverseProvider wires up the authenticated client and a React Query QueryClient (pass your own via queryClient), and manages Clerk for you — it loads Clerk under the hood and authenticates every request as the signed-in user. You never install or import @clerk/clerk-react.

import { HealthUniverseProvider } from '@health-universe/react'

// API origin WITHOUT the /api/v1 suffix (the SDK adds it). On Health Universe the
// API is served same-origin with your app, so there's no CORS. `??` (not `||`) so
// an explicit '' is respected — '' means same-origin (the dev proxy; see Typical Setup).
const API_URL = import.meta.env.VITE_HU_API_URL ?? 'https://api.healthuniverse.com'

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <HealthUniverseProvider
      baseUrl={API_URL}
      // The SDK self-loads Clerk with this key. On Health Universe it's injected
      // automatically; passing it from your env makes the same code work locally too.
      publishableKey={import.meta.env.VITE_CLERK_PUBLISHABLE_KEY}
    >
      {children}
    </HealthUniverseProvider>
  )
}

On Health Universe you can omit publishableKey entirely — the platform injects the key and the SDK reads it, so <HealthUniverseProvider baseUrl={API_URL}> alone is enough and the user is already signed in. Pass it from VITE_CLERK_PUBLISHABLE_KEY (a pk_test_… key in .env.local) so the same code also runs in local dev, where there's no injected key.

The provider props:

Prop	Required	Purpose
baseUrl	Yes	API origin without /api/v1 (the SDK adds it). From the injected VITE_HU_API_URL; an explicit '' means same-origin (no CORS).
publishableKey	No	Clerk key the SDK self-loads with. Defaults to the platform-injected key on Health Universe; pass it from VITE_CLERK_PUBLISHABLE_KEY for local dev.
organizationId	No	Override the active workspace for org-scoped hooks. Defaults to the signed-in user's active org.
tokenTemplate	No	Clerk JWT template for the bearer. Defaults to 'app-session' (carries the org_id org-scoped endpoints require).
getToken / clerk={false}	No	Escape hatch: bring your own token / Clerk instance (e.g. an app already running @clerk/clerk-react).
queryClient	No	Your own React Query client. If omitted, the provider creates one.

No @clerk/clerk-react. The SDK bundles and lazy-loads Clerk itself, so sign-in state, the active organization (and its slug), and sign-in/out/org-switching are all available through the SDK — see useHealthUniverseAuth and the <SignedIn> / <SignedOut> / <OrganizationSwitcher> / <UserButton> components. For a quick off-platform smoke test with no Clerk, pass getToken={async () => import.meta.env.VITE_HU_TOKEN || null} instead.

Step 4: Render a patient list

With the provider in place, any component below it can use the SDK's hooks. Here's a minimal searchable patient roster:

import { useState } from 'react'
import { usePatients, useHealthUniverse } from '@health-universe/react'

function PatientList() {
  const { organizationId } = useHealthUniverse()
  const [search, setSearch] = useState('')

  const { data, isFetching } = usePatients(
    { organizationId, search: search || undefined, limit: 50 },
    { enabled: !!organizationId },
  )

  return (
    <>
      <input
        value={search}
        onChange={(e) => setSearch(e.target.value)}
        placeholder="Search patients…"
      />
      {isFetching && <p>Loading…</p>}
      {data?.patients.map((p) => (
        <div key={p.id}>
          {p.firstName} {p.lastName} · {p.birthDate}
        </div>
      ))}
    </>
  )
}

useHealthUniverse() exposes the provider's context (including the active organizationId). Org-scoped hooks like usePatients take the org id as a query param and accept the standard React Query options as a second argument (enabled, staleTime, and so on).

Step 5: Workspaces — one shared, or each visitor's

When you deploy (on the Privacy & access step), you choose how the app is bound to a workspace. The SDK handles both modes for you:

• One shared workspace (pinned) — the app always works inside the workspace you deployed it into. Everyone who opens it sees that same workspace's data. The SDK activates that workspace automatically; there's nothing to switch.

• Each visitor's workspace — the app works inside whoever's using it's own active workspace, just like the main Health Universe app. Different people see their own data, and they can switch between the workspaces they belong to.

You usually don't need to do anything special — usePatients, useRoutines, etc. already operate in the active workspace. If you want to let people switch workspaces (only meaningful in the "each visitor's workspace" mode), render the SDK's <OrganizationSwitcher> and gate it on the mode the SDK reports via useWorkspace():

import { OrganizationSwitcher, useWorkspace } from '@health-universe/react'

function WorkspaceBar() {
  const { isPinned } = useWorkspace()
  // A pinned app is locked to one workspace — no switcher needed.
  if (isPinned) return null
  return <OrganizationSwitcher />
}

The SDK's <OrganizationSwitcher> renders Clerk's prebuilt widget (via clerk-js, no @clerk/clerk-react). Switching the active workspace updates the SDK's resolved org, and its hooks automatically refetch for the new workspace. Need the active workspace's slug (for useSources / useBundleDetail)? Read it from useHealthUniverseAuth().organization?.slug.

Step 6: Deploy

Push your repo to GitHub, then Create → Source Code in Health Universe and select it. The runtime auto-detects as React (main file package.json), the platform runs your build, and the app is served under a path prefix. See Typical Project Setup for base-path handling and runtime detection, and Deploying to Health Universe for the full deploy flow.

Congratulations — you've built your first custom clinical frontend on Health Universe. From here, explore the SDK Reference to wire up routines, documents, sources/bundles, and chat threads.