# Set up React

Source: /docs/reference/react/setup.md

Use the React SDK to call your APIs, start background work, and add conversations to an ordinary React app. The Vortexify app starter already includes it. In an existing React 18+ app, install the published package:

```sh
npm install --save-exact @vortexify/react@0.1.1
```

The app starter targets 0.1.1. Existing apps should update their dependency and lockfile to receive HTTP errors with the server's message; see [error handling](/docs/reference/react/calling-your-backend#errors-waiting-and-retries).

## Put the provider around the app [#put-the-provider-around-the-app]

```tsx
import {
  VortexifyProvider, createVortexifyConfig, useVortexify,
} from "@vortexify/react";

const config = createVortexifyConfig(import.meta.env);

export function Root() {
  return <VortexifyProvider config={config}><App /></VortexifyProvider>;
}

function App() {
  const { ready } = useVortexify();
  return <main>{ready ? "Connected to the app runtime" : "Connecting…"}</main>;
}
```

Keep configuration stable across renders, as in the module-level constant above. The provider shares the authenticated client with components below it.

`useVortexify()` returns four things:

| Value | Use |
| --- | --- |
| `client` | Call APIs, start/observe transforms, and access conversations or analysis results |
| `ready` | Wait until SDK authentication/transport setup permits requests |
| `agentManager` | Consume an assistant stream and manage conversations, messages, and tool activity |
| `logout` | Ask a deployed app's hosted shell to sign the user out |

Each hook call owns its own conversation-manager state. Keep the component that owns your assistant panel mounted across page changes if the conversation should remain selected. Pass its manager or rendered panel down rather than creating unrelated managers in every screen.

## Run locally through the CLI [#run-locally-through-the-cli]

From the app directory, install dependencies and run `vortexify dev`. Open the URL it prints. Local React edits update through the development server; backend requests reach committed platform code through the CLI proxy.

Save backend changes and prepare their inputs before trying the interface. The [configuration guide](/docs/reference/react/configuration) explains local transport, hosted authentication, and preview versus deployed execution.

## Add one interaction at a time [#add-one-interaction-at-a-time]

Start with [an API call](/docs/reference/react/calling-your-backend) from a form. Use a transform when the interaction starts background processing. Add [conversations and browser actions](/docs/reference/react/conversations-and-actions) when users need an assistant, and [analysis charts](/docs/reference/react/analysis-charts) when it should visualize query results.

A deployed app can provide a logout button with `<button onClick={logout}>Log out</button>`. This function asks the hosted shell to end the session and return to login. Render it only in deployed hosted mode; CLI development and preview do not support that logout operation.

In the platform, open the app's **Preview** view to build and inspect a committed app. Its **Code** view lets you inspect working source or choose a read-only saved version. Use [publishing](/docs/building/publish-your-app) when the app should use production resources.