@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, public settings, and client-visible catalog or inventory values.

---

Basic Example

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

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

function App() {
  const auth = useAuth();
  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
useAuth()	Returns auth status plus loginWithRedirect() and logout().
usePublicState()	Returns public-state subsystem status.
usePublicState<T>(key)	Returns { value: T | null }.
usePublicState<T>(key, fallback)	Returns { value: T }.
useUserState()	Returns user-state subsystem status.
useUserState<T>(key)	Returns { value: T | null, set, draft }.
useUserState<T>(key, fallback)	Returns { value: T, set, draft }.

---

Sections

• SkyStateProvider -- props reference and setup patterns
• usePublicState -- reading public state with full type safety
• useUserState -- reading, writing, and drafting user state
• Auth and subsystem status -- auth actions plus public/user subsystem status

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, draft }.
Status hooks	No-argument hooks return subsystem loading/error status.
Metadata	Use the console, CLI, or REST API for inspection, audit, or history metadata.

---

Error Codes

Code	When thrown
missing_provider	A React SDK hook was called outside a SkyStateProvider.

For broader error handling patterns, see Auth and subsystem status.

---

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 end-user bearer token from useAuth().loginWithRedirect().
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.