> For the complete documentation index, see [llms.txt](https://docs.healthuniverse.com/overview/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.healthuniverse.com/overview/building-apps-in-health-universe/developing-your-health-universe-app/working-in-react.md).

# Working in React

The React runtime lets you **bring your own frontend** to Health Universe. Instead of using a generated Streamlit or Navigator UI, you build a fully custom single-page application (or server-rendered app) in React, Next.js, or any Node-based framework, and deploy it on Health Universe alongside everything else.

To talk to the platform, your app uses the **`@health-universe/react`** SDK — a typed set of React Query hooks and a ready-wired API client for the clinical surface of the Health Universe API: routines, documents, patients, sources/bundles, chat threads, and clinical tools/connectors. You write your UI; the SDK handles auth and data fetching.

This is the preferred path for building **real, production clinical products** where you need full control over the user experience.

## What the SDK is for

`@health-universe/react` gives clinical customers typed React Query hooks and a ready-wired client for the Health Universe API, so you can build your own UI instead of using the platform's. When your app runs on Health Universe, it works with the **signed-in user's Health Universe account** automatically — the SDK handles authentication for you, so there are no separate logins or tokens to manage.

The client is **deliberately scoped** — only the clinical domains below are generated. The rest of the platform API (admin, deployments, billing, internal tooling) does not exist in this package and cannot be called through it.

| Area                   | What it covers                                                         |
| ---------------------- | ---------------------------------------------------------------------- |
| **Routines**           | Routines, routine runs, triggers, connector bindings                   |
| **Documents**          | Search (structured / semantic / text), status, chunks, export, bundles |
| **Clinical data**      | Patients, providers, rosters, appointments                             |
| **Sources**            | Document bundles + detail (input docs, patient, runs)                  |
| **Chat**               | Navigator threads (where context documents live)                       |
| **Tools & connectors** | Clinical tools, connectors                                             |

## Supported frameworks

All three are supported and auto-detected at deploy time from your `package.json`:

* **React** (e.g. Vite) — built as a **static SPA**. Health Universe runs your build step and serves the static assets.
* **Next.js** — runs as a **Node server** via `npm start`.
* **Node** — any other Node-based server app that exposes a `start` script, also run via `npm start`.

## When to use React

Use the React runtime when you want a **standalone app with a full custom UI** — a product, not a single calculator or a Navigator tool. You get the complete clinical data surface through typed hooks, client-side routing, your own design system, and the ability to compose routines, documents, and patient data into purpose-built workflows.

If you only need a quick Python tool or prototype, Streamlit is faster to stand up; if you need a deterministic Python calculator that surfaces inside Navigator, use FastAPI; if you're building a reusable clinical agent or workflow, use A2A. See [Streamlit vs FastAPI vs A2A vs React](/overview/building-apps-in-health-universe/developing-your-health-universe-app/streamlit-vs-fastapi-vs-a2a.md) for the full comparison.

## Next steps

* [Your First Health Universe App](/overview/building-apps-in-health-universe/developing-your-health-universe-app/working-in-react/your-first-health-universe-app.md) — install the SDK, wire up the provider, and render a patient list.
* [Typical Project Setup](/overview/building-apps-in-health-universe/developing-your-health-universe-app/working-in-react/typical-project-setup.md) — repo layout, build & run, and how the runtime is auto-detected.
* [SDK Reference](/overview/building-apps-in-health-universe/developing-your-health-universe-app/working-in-react/sdk-reference.md) — the hooks by domain, plus the `useApiQuery` / `useApiMutation` escape hatch.

🔗 **Resources**

* `@health-universe/react` on npm: `npm install @health-universe/react @tanstack/react-query react`
* [`react-starter`](https://github.com/Health-Universe/react-starter) — a complete example app (provider wiring, dev proxy, a tabbed app with a run-review reader).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.healthuniverse.com/overview/building-apps-in-health-universe/developing-your-health-universe-app/working-in-react.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.