@r2wa/domain-config-provider

A reusable Provider for loading domain configuration from a remote JSON file, probing available domains, and exposing runtime state with a React hook.

Install

pnpm add @r2wa/domain-config-provider

Usage

import { DomainConfigProvider, useDomainConfig } from "@r2wa/domain-config-provider";

function Root() {
  return (
    <DomainConfigProvider
      configUrl="https://example-bucket.s3.amazonaws.com/domain-config.json"
      fallbackDomain="https://api.example.com"
    >
      <App />
    </DomainConfigProvider>
  );
}

function App() {
  const { domains, availableDomain, status, error, refresh } = useDomainConfig();

  return null;
}

Provider props

• configUrl: remote JSON config URL.
• fallbackDomain: optional fallback API domain.
• healthCheckPath: default /api/health.
• fetchTimeoutMs: default 5000.
• probeTimeoutMs: default 2500.
• storage: optional storage adapter with getItem/setItem/removeItem.
• storageKey: optional storage key.
• onResolvedDomain: callback when available domain is resolved.

Hook return

• domains: string[]
• availableDomain: string | null
• status: "idle" | "loading" | "probing" | "resolved" | "fallback-cache" | "fallback-default" | "error"
• error: { code; message } | null
• refresh: () => Promise<void>

JSON config shape

Supports either format:

{
  "version": "v1",
  "ttl_seconds": 1800,
  "domains": [
    "https://api-1.example.com",
    "https://api-2.example.com"
  ]
}

or

{
  "version": "v1",
  "ttl_seconds": 1800,
  "domains": {
    "primary": "https://api-1.example.com",
    "backups": ["https://api-2.example.com"]
  }
}