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. Calls subscribe to a single top-level key and return { value } only. For loading and error status, use useStatus().health.

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<T = unknown>(
  key: string,
): { value: T | null }

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

Parameters

Parameter	Description
key	Top-level public-state key such as banner, flags, or theme.
fallback	Value returned while public state is not ready or when the key is absent. A stored null is returned as-is, never replaced by the fallback, so value stays T | null even with a fallback.

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

Returns

Call	Return
usePublicState<T>(key)	{ value: T | null }.
usePublicState<T>(key, fallback)	{ value: T | null }.

---

Public Contract

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