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, public settings, and client-visible 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 18+.

  • Browser: Vite, webpack, Rollup, esbuild, or any bundler that supports ESM
  • Node.js: 18+ (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, public 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 useAuth().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 }, and usePublicState() with no args for subsystem status.
Keyed user reads return value, set, and draftUse useUserState(key, fallback?) for { value, set, draft }, and useUserState() with no args for subsystem status.
SDK v1 is value-onlyKeyed SDK calls expose values, setters, drafts, and subsystem status. 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.