@bluealba/config-manager-react

React wrapper for @bluealba/config-manager-core. Provides a <ConfigProvider> that owns a ConfigManager instance and tear-free hooks built on React 18's useSyncExternalStore.

Installation

npm install @bluealba/config-manager-react @bluealba/config-manager-core

react and react-dom are peer dependencies (React 18).

Usage

Build the providers yourself (the wrapper doesn't guess your data sources) and hand them to <ConfigProvider>. It builds the manager, calls init() on mount and dispose() on unmount.

import { ConfigProvider, useConfig, useConfigStatus } from '@bluealba/config-manager-react';
import { httpProvider, pollingTransport } from '@bluealba/config-manager-core';
import { localStorageFallback } from '@bluealba/config-manager-core/browser';

function App() {
  return (
    <ConfigProvider
      providers={[httpProvider({ url: '/config' })]}
      transport={pollingTransport({ intervalMs: 5000 })}
      fallback={localStorageFallback({ key: 'app:config' })}
    >
      <Title />
      <StaleBanner />
    </ConfigProvider>
  );
}

function Title() {
  const title = useConfig<string>('feature.title', 'Default'); // re-renders only when this key changes
  return <h1>{title}</h1>;
}

function StaleBanner() {
  const status = useConfigStatus();
  if (!status.degraded) return null;
  return <div className="banner">Configuration stale — using last known copy ({status.activeSource})</div>;
}

<ConfigProvider> accepts the full ConfigManagerOptions as props: providers (required, highest→lowest precedence), transport?, fallback?, retry?, debounceMs?, validate?, context?.

Naming: antd also exports a ConfigProvider. Alias when both are used: import { ConfigProvider as ConfigManagerProvider } from '@bluealba/config-manager-react'.

API

| Export | Description | |--------|-------------| | <ConfigProvider {...options}> | Builds + owns the manager; provides it via context. | | useConfig<T>(key, defaultValue?) | Value for a key; re-renders only when that key changes. | | useConfigEntry<T>(key) | Full ConfigEntry (value + audit metadata incl. degraded). | | useConfigStatus() | ConfigStatus (healthy/degraded/activeSource/…); re-renders on transitions. | | useConfigManager() | The raw ConfigManager for imperative use (refresh(), getAll()). Throws outside a provider. | | <ConfigGuard when={fn} fallback? invert?> | Conditionally renders children based on a reactive predicate over config. |

<ConfigGuard when={({ get }) => get('feature.beta') === true} fallback={<Legacy />}>
  <BetaFeature />
</ConfigGuard>

Notes

• Reactivity uses useSyncExternalStore, so reads never tear across concurrent renders.
• react/react-dom must stay peers — in single-spa they are shared via the import map; a second React instance breaks context and useSyncExternalStore.
• Dual ESM + CJS build (unbuild).

License

PolyForm-Noncommercial-1.0.0 · Blue Alba