@skystate/react

@skystate/react provides a React context provider and hooks that integrate SkyState public state, user state, and end-user auth into React applications. Public state is useful for application config, feature flags, settings, and catalog or inventory values.

---

Basic Example

import { SkyStateProvider, useStatus, usePublicState, useUserState } from '@skystate/react';

function Root() {
  return (
    <SkyStateProvider account="acc_example" project="my-project" environment="production">
      <App />
    </SkyStateProvider>
  );
}

function App() {
  const { auth } = useStatus();
  const { value: banner } = usePublicState('banner', { text: 'Welcome' });
  const { value: theme, set: setTheme } = useUserState('theme', 'dark');

  if (auth.status !== 'authenticated') {
    return <button onClick={auth.loginWithRedirect}>Sign in</button>;
  }

  return (
    <>
      <p>{banner?.text}</p>
      <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
        Theme: {theme}
      </button>
    </>
  );
}

---

Installation

npm install @skystate/react

@skystate/react depends on @skystate/core. You do not need to install @skystate/core separately.

React 18 or later is required.

---

API Reference

Provider

Export	Description
SkyStateProvider	Context provider. Wrap your app (or a subtree) to make SkyState available to hooks.
SkyStateProviderProps	TypeScript type for the provider's props.

Hooks

Export	Description
useStatus()	Returns { auth, health }: auth status plus loginWithRedirect() and logout(), and overall client health.
usePublicState<T>(key, fallback?)	Returns { value: T | null }.
useUserState<T>(key, fallback?)	Returns { value: T | null, set, clear, syncStatus, draft }.

---

Sections

• SkyStateProvider: props reference and setup patterns
• usePublicState: reading public state with full type safety
• useUserState: reading, writing, and drafting user state
• useStatus: auth status, auth actions, and client health

Contract

Contract	Detail
Provider scope	One mounted provider maps to one account, project, and environment. Remount to switch scope.
Keyed hooks	Keyed public hooks return { value }; keyed user hooks return { value, set, clear, syncStatus, draft }.
Health	useStatus().health reports overall loading/error status.
Metadata	Use the console, CLI, or REST API for inspection, audit, or history metadata.

---

Error Codes

Code	Surfaced
missing_provider	Thrown: a React SDK hook was called outside a SkyStateProvider.
missing_config	Thrown: required client configuration is missing, for example an empty account or project.
disposed	Thrown: a client method was called after the client was disposed.
invalid_path	Invalid key or non-JSON value. Thrown at the call site when detectable there; a functional updater that fails validation at save time instead fires onError and pins a permanent health error until remount.

For broader error handling patterns, see useStatus.

---

Key Behaviors to Know

Behavior	Detail
Public reads are available before login	Public state can render for signed-out visitors.
User state requires login	User state loads and writes require an authenticated end-user session. Call useStatus().auth.loginWithRedirect() to start the login flow.
Production cache TTL: 900 seconds	Public-state reads are cached 15 minutes in production.
Config size limit: 256,000 chars	The serialized JSON for a public-state object must not exceed 256,000 characters.
Account/project route changes break URLs	SDK clients must use the current account route identifier and project identifier.