SkyStateProvider

SkyStateProvider is a React context provider that initializes a SkyState client, begins fetching public state, restores auth when possible, and makes state available to all descendant hooks.

Place it near the root of your component tree (or near the root of the subtree that needs SkyState). All React SDK hooks below it read from the same client instance.

---

Basic Example

import { SkyStateProvider } from '@skystate/react';

createRoot(document.getElementById('root')!).render(
  <SkyStateProvider account="acc_example" project="my-project" environment="production">
    <App />
  </SkyStateProvider>,
);

---

Props

interface SkyStateProviderProps {
  /** Base URL of the SkyState API. Defaults to https://api.skystate.io. */
  apiUrl?: string;
  /** Account route identifier, for example acc_123. */
  account: string;
  /** Project identifier. */
  project: string;
  /** Environment slug. Defaults to 'development'. */
  environment?: string;
  /** Accepted for compatibility; browser apps should not use project API keys. */
  apiKey?: string;
  /** Accepted for compatibility. */
  debug?: boolean;
  /** Optional explicit auth callback URL. */
  callbackUrl?: string;
  /** Called when provider initialization or state loading fails. */
  onError?: (error: SkyStateError) => void;
  /** Called after an auth callback completes. */
  onLoginComplete?: (returnTo: string) => void;
  children: ReactNode;
}

Prop	Type	Required	Description
account	string	Yes	Account route identifier, for example acc_example.
project	string	Yes	Project identifier.
environment	string	No	development, staging, or production. Defaults to development.
apiUrl	string	No	SkyState API base URL. Defaults to https://api.skystate.io.
callbackUrl	string	No	Explicit hosted-auth callback URL.
onError	(error: SkyStateError) => void	No	Receives provider, auth, and state errors.
onLoginComplete	(returnTo: string) => void	No	Called after an auth callback completes.
apiKey	string	No	Compatibility prop. Do not put project API keys in browser bundles.
debug	boolean	No	Compatibility prop. Most apps can omit it.
children	ReactNode	Yes	Descendant React tree.

---

Dynamic Environment Selection

The environment prop is a plain string you supply. The SDK does not read it from any environment variable — wire it however your build system provides it:

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { SkyStateProvider } from '@skystate/react';
import App from './App';

// Any build variable that resolves to 'development', 'staging', or 'production'.
// import.meta.env.MODE is 'development' in the dev server and 'production' for vite build
// (even staging builds), so use --mode staging and handle all three cases explicitly.
// You can also use a custom variable, e.g. import.meta.env.VITE_ENV.
const mode = import.meta.env.MODE as string;
const environment = mode === 'staging' ? 'staging' : mode === 'development' ? 'development' : 'production';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <SkyStateProvider
      account="acc_example"
      project="my-project"
      environment={environment}
    >
      <App />
    </SkyStateProvider>
  </StrictMode>,
);

The apiUrl and auth endpoints default to the hosted SkyState service (https://api.skystate.io, https://auth.skystate.io). Most apps do not need to override them. For local-stack or custom-host setups, the provider also reads VITE_SKYSTATE_API_URL, NEXT_PUBLIC_SKYSTATE_API_URL, or REACT_APP_SKYSTATE_API_URL (and the _AUTH_FRONT_URL variants) from the build environment before falling back to the hosted defaults. The explicit apiUrl prop always takes precedence over env vars.

---

Lifecycle

The provider owns one SkyState client for the mounted account, project, and environment.

Props are read once at mount. To switch account, project, or environment, unmount and remount the provider, or give it a different React key.

---

Using Multiple Providers

Each SkyStateProvider instance connects to one (apiUrl, account, project, environment) tuple. If your application reads state from multiple projects, nest or render multiple providers:

<SkyStateProvider account="acc_example" project="website">
  <WebsiteSection />
</SkyStateProvider>

<SkyStateProvider account="acc_example" project="admin">
  <AdminSection />
</SkyStateProvider>

Hooks will use the nearest SkyStateProvider ancestor in the tree.