# Configure the React client

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

The React client connects your app to the right Vortexify project and execution environment. The starter already sets up the provider. Usually you keep that setup and focus on your components.

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

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

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

`import.meta.env` is Vite's environment object. `createVortexifyConfig` translates its public settings into client configuration. You can pass a second object to override a setting in code, but the CLI and hosted builds normally provide the values you need.

## Local development [#local-development]

Start the app with `vortexify dev` from its directory. The CLI provides the project and organization context and starts a proxy for backend requests. Open its printed development URL.

Your browser calls a same-origin path, `/__vortexify` by default. The CLI forwards those requests with your authentication. Keep credentials in the CLI; browser environment values are public.

`ready` means the client can begin making requests. In development it reflects configured proxy mode, so a failed login, stopped proxy, or unavailable backend can still make a request fail. Show request errors in the interface as well as waiting for readiness.

## Hosted previews and published apps [#hosted-previews-and-published-apps]

The hosted platform opens a built app in an iframe. The provider receives authentication from the actual parent window, checks its configured origin, and uses that authentication for backend requests. Open hosted apps through [the Vortexify dashboard](https://dashboard.vortexify.ai).

The provider owns the token handshake and refresh messages. Your components use `useVortexify()` rather than implementing window-message authentication themselves. A production build opened outside its hosted shell does not establish an authenticated app session.

The platform's app **Preview** view shows the built preview and whether it is stale. Authenticated iframe previews run in the hosted platform. For local app development, use the CLI proxy flow above.

## Preview lifecycle [#preview-lifecycle]

Execution mode determines which backend versions and outputs the app uses:

| Mode | Backend behavior |
| --- | --- |
| `preview` | APIs use committed source with a ready runtime; transforms execute saved source; assistants use committed definitions and API tools with preview data |
| `run` | Execution uses deployed resources and production publications for the published application |

CLI development and hosted preview builds use preview mode. Deployment builds use run mode. This setting affects `runApi`, `startTransform`, and `runAgent`; it is an active execution choice.

Commit backend edits before calling them. If an API runtime is unavailable, prepare it with `vortexify build api NAME --wait`. A source-only change can reuse an already-ready shared runtime when its dependency image and allocation match. A separate preparation job for every new source version is not always necessary.

Run required syncs and transforms to produce data. A new source commit or changed upstream output can make a built preview stale; previous successful outputs remain available until replaced. Rebuilding a preview does not upgrade a deployment. Manual preview runs do not fire production schedules or downstream production triggers.

In the platform, table views let you select **Preview runs** or **Deployed version**, then a specific published run. The selected run remains selected when newer data arrives. Check that selection when comparing the app's result with a table in the platform.

## Public configuration values [#public-configuration-values]

These are useful when adapting the starter or diagnosing setup. The CLI and build pipeline normally populate the relevant values.

| Vite value | Purpose |
| --- | --- |
| `VITE_API_SERVER_URL` | Backend API origin for authenticated hosted requests |
| `VITE_VORTEXIFY_PROJECT_ID` | Project whose resources the app calls |
| `VITE_VORTEXIFY_ORG_ID` | Organization context for development requests |
| `VITE_APP_MODE` | `preview` or `run`; helper default is `preview` |
| `VITE_VORTEXIFY_PARENT_ORIGIN` | Exact trusted HTTPS origin of the hosted parent |
| `VITE_VORTEXIFY_DEV_PROXY_PATH` | Local proxy prefix; default `/__vortexify` |

Vite's `DEV` flag enables development transport. Compatibility fields `VITE_APP_ID` and `VITE_VERSION_ID` are read by the helper, but do not choose backend resource versions. Select saved execution versions through platform execution/deployment workflows.

Authentication refresh does not automatically replay a failed request. Display the failure and decide whether retrying is appropriate for the operation, particularly for writes.

See [React setup](/docs/reference/react/setup), [backend calls](/docs/reference/react/calling-your-backend), and [publishing](/docs/building/publish-your-app).