Configure the React client
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.
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
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
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.
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
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
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, backend calls, and publishing.