vexapp-sdk

React SDK for Vex Flags: load feature flag values from the Vex API (POST /api/flags) using your app's API key.

Requirements

• React 19 and React DOM 19 (peer dependencies)

Allowed URLs

In the dashboard, each API key has an allowed URL list. The browser sends an Origin (or Referer) on POST /api/flags. The API rejects the request unless that origin matches one of your listed URLs (scheme + host + port). Add every origin you load the app from (production, preview, local dev).

403 Forbidden on POST /api/flags

Check the JSON body reason on the response:

| reason | What to fix | | ---------------------- | ----------- | | vex_flags_disabled | Enable Vex Flags for this app in the dashboard (purchase/add-on). | | missing_origin | The request had no Origin or Referer (common with server-side fetch, curl, or non-browser clients). Call the API from the browser, or ensure your dev server origin is sent. | | origin_not_allowed | Add your page’s exact origin to the key’s allowed URLs (e.g. http://localhost:5173 if that is where the app runs). |

The browser console may still log failed network requests for 403s; that comes from DevTools, not the SDK. The provider debounces flag registration so many <VexFlag> components do not each trigger their own immediate request.

Install

bun add vexapp-sdk

npm install vexapp-sdk

Usage

Wrap your app (or a subtree) with VexProvider, passing your API key and, for local development, baseUrl pointing at the Vex API origin (not your Vite dev server).

import { VexFlag, VexProvider } from "vexapp-sdk";

export function App() {
  return (
    <VexProvider
      apiKey={import.meta.env.VITE_VEX_API_KEY}
      baseUrl={import.meta.env.VITE_VEX_API_URL}
    >
      <Main />
    </VexProvider>
  );
}

Use VexFlag with a name and default when the API is unavailable:

<VexFlag name="my-flag" defaultEnabled={false}>
  {(enabled) => (enabled ? <NewFeature /> : <LegacyFeature />)}
</VexFlag>

If you omit baseUrl, the SDK uses the production API host https://vexapp.io.

API surface

| Export | Role | | ------------------ | ------------------------------------------------- | | VexProvider | Context provider; fetches and caches flags | | VexFlag | Declares a flag and renders from remote/default | | useVexFlags | Low-level context hook (nullable) | | fetchFlags | Imperative POST /api/flags helper | | resolveFlagValue | Pure merge of remote boolean vs default |

Docs

Product and dashboard docs: vexapp.io