SDK Overview

SkyState provides two JavaScript/TypeScript packages for reading remote configuration in your application:

Package	Description
@skystate/core	Framework-agnostic client library. Use this for any JavaScript runtime — Node.js, Vanilla JS, or when building your own framework integration.
@skystate/react	React bindings built on @skystate/core. Provides a context provider and hooks that integrate with React's rendering model.

---

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+ (uses useSyncExternalStore)
• Framework support: The core package is framework-agnostic. The React package targets React 18 and React 19.

---

Philosophy

Network-first, not cache-first. On mount, the SDK fetches the latest config from the server. It does not read from localStorage or a persisted cache. Config values you read always reflect the server state as of the last successful fetch.

Server-driven polling. The server controls how often the SDK re-fetches by setting Cache-Control: max-age=N on the config response. The SDK schedules re-fetches based on the max-age value — no hardcoded interval, no polling configuration required in the client.

Tab visibility awareness. When the browser tab becomes visible after being hidden, the SDK re-fetches if the cached value has expired. This keeps configs fresh without polling while the tab is hidden.

Zero-config in development. When a devKey is present and the resolved environment is development, the SDK automatically creates missing config keys the first time they are read with a fallback value. You write code referencing config keys and they appear in SkyState without a separate setup step.

Singleton stores. A ConfigStore instance is keyed by (apiUrl, accountSlug, projectSlug, environmentSlug). Calling getOrCreateStore multiple times with the same parameters returns the same instance. This means a single HTTP connection is shared across all hooks or components reading from the same project and environment.

---

Installation

# React applications
npm install @skystate/react

# Framework-agnostic / Node.js
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.

---

Quick Example (React)

// main.tsx
import { SkyStateProvider } from '@skystate/react';

createRoot(document.getElementById('root')!).render(
  <SkyStateProvider
    apiUrl="https://api.skystate.io"
    accountSlug="my-account"
    projectSlug="my-project"
  >
    <App />
  </SkyStateProvider>,
);

// Banner.tsx
import { useProjectConfig } from '@skystate/react';

export function Banner() {
  const { data: enabled } = useProjectConfig<boolean>('banner.enabled', true);
  const { data: text } = useProjectConfig<string>('banner.text', 'Welcome!');

  if (!enabled) return null;
  return <div>{text}</div>;
}

---

Sections

@skystate/core

Framework-agnostic client. Covers ConfigStore, getOrCreateStore, environment resolution, and auto-registration.

• ConfigStore — initialization, reading values, subscribing to changes
• Environments — how build-time environment variables map to server environment slugs
• Auto-registration — automatic key creation in development mode

@skystate/react

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

• SkyStateProvider — context provider props and setup
• useProjectConfig — read and subscribe to individual config keys
• useConfigStatus — loading state, errors, and last-fetched timestamp