SkyState

SDK Overview ​

SkyState ships JavaScript/TypeScript SDKs for public state, user state, and hosted end-user auth. Use public state for application config, feature flags, settings, and catalog or inventory values.

PackageDescription
@skystate/coreFramework-agnostic client library. Use this for any JavaScript runtime - Node.js, Vanilla JS, or when building your own framework integration.
@skystate/reactReact bindings built on @skystate/core. Provides a context provider and hooks for public state, user state, and hosted auth.

Basic Examples ​

React ​

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

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

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

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

Core ​

ts
import { createSkyStateClient } from '@skystate/core';

const client = createSkyStateClient({
  account: 'acc_example',
  project: 'my-project',
  environment: 'production',
});

await client.init();

const banner = client.publicState.get('banner', { text: 'Welcome' });
client.setAuthTokens({ idToken, refreshToken });
client.userState.set('theme', 'dark');

Supported Platforms ​

Both packages run in modern browsers and Node.js 20+.

  • Browser: Vite, webpack, Rollup, esbuild, or any bundler that supports ESM
  • Node.js: 20+ (uses the built-in fetch API)
  • React: 18+
  • Framework support: The core package is framework-agnostic. The React package targets React 18 and React 19.

Public Contract ​

BehaviorDetail
Public stateReadable before login. Use it for application config, feature flags, settings, and catalog or inventory values. Use publicState.get() in core or usePublicState() in React.
User stateRequires a signed-in end user. Use userState.get/set/draft() in core or useUserState() in React.
AuthReact starts hosted login through useStatus().auth.loginWithRedirect(). Core accepts tokens from an auth flow with setAuthTokens().
Provider scope is mount-timeSwitching account, project, or environment requires remounting SkyStateProvider with a new React key.
Keyed public reads return value onlyUse usePublicState(key, fallback?) for { value }. Status is unified: read useStatus().health.
Keyed user reads return value, writers, sync status, and draftUse useUserState(key, fallback?) for { value, set, clear, syncStatus, draft }. Status is unified: read useStatus().health.
SDK exposes values, setters, and draftsKeyed SDK calls expose values, setters, drafts, and the key's syncStatus. Auth and operational health come from useStatus() in React or the client snapshot in core. Use the console, CLI, or REST API for inspection, audit, or history metadata.
Production cache TTL: 900 secondsPublic state reads are cached 15 minutes in production.
Dev/staging cache TTL: 10 secondsDevelopment and staging public state is cached for 10 seconds.
Fixed environmentsOnly development, staging, and production are valid environment slugs.
Account/project route changes break URLsSDK clients must use the current account route identifier and project identifier.

Installation ​

For React applications (@skystate/react on npm):

bash
npm install @skystate/react

For framework-agnostic JavaScript or Node.js (@skystate/core on npm):

bash
npm install @skystate/core

@skystate/react depends on @skystate/core and re-exports the types you need, so you do not need to install @skystate/core separately when using React.

Sections ​

@skystate/core ​

Framework-agnostic client. Covers createSkyStateClient, public state, and user state.

  • Client: initialization, reading values, subscribing to changes
  • Environments: how environment slugs work

@skystate/react ​

React bindings. Covers the provider, hooks, and TypeScript patterns.