usePublicState

usePublicState reads public state for the project mounted by SkyStateProvider. Use it for application config, feature flags, settings, announcements, theme values, safe limits, and catalog or inventory values. Keyed calls subscribe to a single top-level key and return { value } only. The no-argument call returns the public-state subsystem status.

Must be called inside a component that is a descendant of SkyStateProvider. Throws a SkyStateError if called outside a provider.

---

Basic Example

import { usePublicState } from '@skystate/react';

export function AnnouncementBanner() {
  const { value: enabled } = usePublicState('bannerEnabled', true);
  const { value: text } = usePublicState('bannerText', 'Welcome!');

  if (!enabled) return null;

  return <div className="banner">{text}</div>;
}

---

API

function usePublicState(): SubsystemStatus

function usePublicState<T = unknown>(
  key: string,
): { value: T | null }

function usePublicState<T>(
  key: string,
  fallback: T,
): { value: T }

type SubsystemStatus =
  | { status: 'idle' | 'loading' | 'ready' }
  | { status: 'error'; error: SkyStateError };

Parameters

Parameter	Description
key	Top-level public-state key such as banner, flags, or theme.
fallback	Value returned while public state is not ready, when the key is absent, or when the stored value is null. Also narrows value from T | null to T.

Keys are top-level names. They are not nested paths, and '' is not a root-object escape hatch.

Returns

Call	Return
usePublicState()	{ status: 'idle' | 'loading' | 'ready' } or { status: 'error'; error: SkyStateError }.
usePublicState<T>(key)	{ value: T | null }.
usePublicState<T>(key, fallback)	{ value: T }.

---

Public Contract

Contract	Detail
Auth	Public state is available before login.
Keyed return	Keyed calls return { value } only.
Status	Use usePublicState() with no arguments for loading and error state.
Metadata	Use the console, CLI, or REST API for inspection, audit, or history metadata.