useProjectConfigStatus

useProjectConfigStatus returns the connection status of the underlying ConfigStore: when config was last successfully fetched and any error that has occurred. Use this hook to build status indicators, error messages, or sync timestamps.

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

---

Signature

function useProjectConfigStatus(): {
  lastFetched: Date | null;
  error: Error | null;
}

---

Return Value

{
  lastFetched: Date | null; // Timestamp of the last successful fetch, or null
  error: Error | null;      // Last error, or null if the most recent fetch succeeded
}

lastFetched

A Date object representing when the SDK last successfully received config from the server. null before the first successful fetch completes.

This value updates after each successful re-fetch (initial load and any subsequent poll cycles triggered by Cache-Control: max-age).

error

The most recent error from the HTTP client, or null if the last fetch succeeded. Errors do not clear lastFetched — if a re-fetch fails after a previous success, lastFetched still holds the timestamp of the last successful fetch and error holds the new error.

Errors are instances of SkyStateError (which has a code string and optional HTTP status) or standard Error objects for network failures.

---

Usage Examples

Connection status footer

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

export function StatusBar() {
  const { lastFetched, error } = useProjectConfigStatus();

  const hasError = error !== null;

  return (
    <footer
      style={{
        backgroundColor: hasError ? '#fef2f2' : '#f9fafb',
        color: hasError ? '#b91c1c' : '#6b7280',
        padding: '8px 24px',
        fontSize: '12px',
      }}
    >
      {hasError ? (
        <span>Config error: {error.message}</span>
      ) : lastFetched ? (
        <span>Config synced at {lastFetched.toLocaleTimeString()}</span>
      ) : (
        <span>Connecting to SkyState...</span>
      )}
    </footer>
  );
}

Retry on error (manual refresh trigger)

useProjectConfigStatus surfaces errors but does not provide a manual refresh method — the SDK manages its own polling schedule. If you want to surface a retry prompt, you can use the error state to show a message:

export function ConfigErrorBanner() {
  const { error } = useProjectConfigStatus();

  if (!error) return null;

  return (
    <div role="alert" style={{ color: 'red', padding: '8px' }}>
      Failed to load configuration. The app is using last known values.
      {error instanceof SkyStateError && ` (Error: ${error.code})`}
    </div>
  );
}

Sync indicator with status dot

import { useProjectConfigStatus } from '@skystate/react';
import { SkyStateError } from '@skystate/react'; // re-exported from @skystate/core

type StatusDotColor = 'green' | 'amber' | 'red';

function getStatusColor(lastFetched: Date | null, error: Error | null): StatusDotColor {
  if (error !== null) return 'red';
  if (lastFetched !== null) return 'green';
  return 'amber'; // still loading
}

export function SyncIndicator() {
  const { lastFetched, error } = useProjectConfigStatus();
  const color = getStatusColor(lastFetched, error);

  return (
    <span
      aria-label={`Config status: ${color}`}
      style={{
        display: 'inline-block',
        width: '8px',
        height: '8px',
        borderRadius: '50%',
        backgroundColor: color === 'green' ? '#22c55e'
                        : color === 'amber' ? '#f59e0b'
                        : '#ef4444',
      }}
    />
  );
}

---

isLoading

Notice that useProjectConfigStatus does not return isLoading. The loading state is available on useProjectConfig:

const { data, isLoading, error } = useProjectConfig('my.key', defaultValue);

isLoading is true until the first fetch (successful or failed) completes. Use useProjectConfig when you need both a value and a loading indicator. Use useProjectConfigStatus when you only need the connection status and timestamp.

---

Render Behaviour

useProjectConfigStatus subscribes to the '__status' path on the ConfigStore. It re-renders the component when lastFetched or error changes — that is, after each successful or failed fetch. It does not re-render when individual config values change.

---

Error Types

Errors surfaced via error are one of:

Error type	When
SkyStateError with code: 'fetch_failed'	Server returned a non-2xx HTTP status
Error (network error)	DNS failure, connection refused, timeout, etc.

To distinguish between them:

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

const { error } = useProjectConfigStatus();

if (error instanceof SkyStateError) {
  // Structured SDK error
  console.log(error.code);    // 'fetch_failed'
  console.log(error.status);  // HTTP status code, e.g. 404
  console.log(error.message); // Human-readable description
} else if (error) {
  // Network error, timeout, etc.
  console.log(error.message);
}