@vexillo/react-sdk 1.0.7 → 2.0.0

package/dist/index.cjs

@@ -21,51 +21,71 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   VexilloProvider: () => VexilloProvider,
+  fetchFlags: () => fetchFlags,
   useFlag: () => useFlag
 });
 module.exports = __toCommonJS(src_exports);
 
 // src/provider.tsx
 var import_react = require("react");
+
+// src/fetch-flags.ts
+async function fetchFlags(baseUrl, apiKey) {
+  try {
+    const res = await fetch(`${baseUrl}/api/flags`, {
+      headers: { Authorization: `Bearer ${apiKey}` }
+    });
+    if (!res.ok) {
+      console.warn(
+        `Vexillo: fetchFlags received status ${res.status} ${res.statusText}. Returning empty flags.`
+      );
+      return {};
+    }
+    const data = await res.json();
+    const map = {};
+    for (const f of data.flags) {
+      map[f.key] = f.enabled;
+    }
+    return map;
+  } catch (e) {
+    console.warn("Vexillo: fetchFlags failed. Returning empty flags.");
+    return {};
+  }
+}
+
+// src/provider.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
 var VexilloContext = (0, import_react.createContext)(null);
+var clientCache = /* @__PURE__ */ new Map();
+function getOrCreateFlagPromise(baseUrl, apiKey) {
+  const key = `${baseUrl}__${apiKey}`;
+  if (!clientCache.has(key)) {
+    clientCache.set(key, fetchFlags(baseUrl, apiKey));
+  }
+  return clientCache.get(key);
+}
 function VexilloProvider({
   baseUrl,
   apiKey,
+  initialFlags,
   fallbacks = {},
   children
 }) {
-  const [flags, setFlags] = (0, import_react.useState)(null);
-  const [error, setError] = (0, import_react.useState)(null);
-  (0, import_react.useEffect)(() => {
-    let cancelled = false;
-    fetch(`${baseUrl}/api/flags`, {
-      headers: { Authorization: `Bearer ${apiKey}` }
-    }).then((res) => {
-      if (!res.ok) {
-        throw new Error(
-          `Vexillo: API responded with status ${res.status} ${res.statusText}`
-        );
-      }
-      return res.json();
-    }).then((data) => {
-      if (cancelled) return;
-      const map = {};
-      for (const f of data.flags) {
-        map[f.key] = f.enabled;
-      }
-      setFlags(map);
-    }).catch((err) => {
-      if (cancelled) return;
-      setError(
-        err instanceof Error ? err : new Error(`Vexillo: unexpected error \u2014 ${String(err)}`)
-      );
-    });
-    return () => {
-      cancelled = true;
-    };
-  }, [apiKey, baseUrl]);
-  if (error) throw error;
+  const isServer = typeof window === "undefined";
+  if (initialFlags) {
+    const key = `${baseUrl}__${apiKey}`;
+    if (!isServer && !clientCache.has(key)) {
+      clientCache.set(key, Promise.resolve(initialFlags));
+    }
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(VexilloContext.Provider, { value: { flags: initialFlags, fallbacks }, children });
+  }
+  let flagPromise;
+  if (isServer) {
+    flagPromise = fetchFlags(baseUrl, apiKey);
+  } else {
+    flagPromise = getOrCreateFlagPromise(baseUrl, apiKey);
+  }
+  const flags = (0, import_react.use)(flagPromise);
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(VexilloContext.Provider, { value: { flags, fallbacks }, children });
 }
 function useVexilloContext() {
@@ -80,7 +100,7 @@ function useVexilloContext() {
 function useFlag(key) {
   var _a;
   const { flags, fallbacks } = useVexilloContext();
-  if (flags !== null && key in flags) {
+  if (key in flags) {
     return flags[key];
   }
   return (_a = fallbacks[key]) != null ? _a : false;
@@ -88,5 +108,6 @@ function useFlag(key) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   VexilloProvider,
+  fetchFlags,
   useFlag
 });

package/dist/index.d.cts

@@ -5,11 +5,48 @@ interface VexilloProviderProps {
     baseUrl: string;
     /** SDK API key for the target environment */
     apiKey: string;
-    /** Flag values used before the fetch resolves and for unknown keys */
+    /**
+     * Pre-resolved flags from the server.
+     *
+     * **Required when using `renderToString`** — pass the result of
+     * `fetchFlags(baseUrl, apiKey)` here, as `renderToString` does not support
+     * Suspense. Without this, the provider will throw during server rendering.
+     *
+     * Optional for `renderToPipeableStream`, RSC, and SPA — the provider will
+     * suspend and fetch flags on its own if omitted.
+     */
+    initialFlags?: Record<string, boolean>;
+    /** Flag values used as defaults for unknown keys */
     fallbacks?: Record<string, boolean>;
     children: ReactNode;
 }
-declare function VexilloProvider({ baseUrl, apiKey, fallbacks, children, }: VexilloProviderProps): React.ReactElement;
+/**
+ * Provides feature flag values to the React tree via Suspense.
+ *
+ * The subtree suspends until flags are resolved — wrap with `<Suspense>`
+ * to show a loading state.
+ *
+ * ```tsx
+ * <Suspense fallback={<Spinner />}>
+ *   <VexilloProvider baseUrl="..." apiKey="...">
+ *     <App />
+ *   </VexilloProvider>
+ * </Suspense>
+ * ```
+ *
+ * ### SSR with `renderToString`
+ * `renderToString` does not support Suspense. Call `fetchFlags` before
+ * rendering and pass the result as `initialFlags`:
+ * ```ts
+ * const flags = await fetchFlags(baseUrl, apiKey);
+ * renderToString(<VexilloProvider initialFlags={flags} ...>);
+ * ```
+ *
+ * ### SSR with `renderToPipeableStream` / RSC
+ * `initialFlags` is optional. The provider suspends and streams the resolved
+ * flags inline. Pass `initialFlags` to avoid the suspension entirely.
+ */
+declare function VexilloProvider({ baseUrl, apiKey, initialFlags, fallbacks, children, }: VexilloProviderProps): React.ReactElement;
 
 /**
  * Returns the current boolean value for a feature flag key.
@@ -22,4 +59,32 @@ declare function VexilloProvider({ baseUrl, apiKey, fallbacks, children, }: Vexi
  */
 declare function useFlag(key: string): boolean;
 
-export { VexilloProvider, type VexilloProviderProps, useFlag };
+/**
+ * Fetches feature flags from your Vexillo deployment.
+ *
+ * Use this on the server before rendering to pass resolved flags as
+ * `initialFlags` to `<VexilloProvider>`.
+ *
+ * ## When to use
+ *
+ * - **`renderToString`** — Suspense is not supported. You MUST call
+ *   `fetchFlags` before rendering and pass the result as `initialFlags`:
+ *   ```ts
+ *   const flags = await fetchFlags(baseUrl, apiKey);
+ *   renderToString(<VexilloProvider initialFlags={flags} ...>);
+ *   ```
+ *
+ * - **`renderToPipeableStream` / `renderToReadableStream`** — Suspense is
+ *   supported. `initialFlags` is optional; the provider will suspend and
+ *   fetch flags inline. You may still pass `initialFlags` to avoid the
+ *   suspension entirely.
+ *
+ * - **React Server Components (Next.js App Router)** — call `fetchFlags`
+ *   in your server component and pass the result as `initialFlags`.
+ *
+ * - **SPA (no SSR)** — omit `initialFlags`. The provider fetches on the
+ *   client and suspends until resolved.
+ */
+declare function fetchFlags(baseUrl: string, apiKey: string): Promise<Record<string, boolean>>;
+
+export { VexilloProvider, type VexilloProviderProps, fetchFlags, useFlag };

package/dist/index.d.ts

@@ -5,11 +5,48 @@ interface VexilloProviderProps {
     baseUrl: string;
     /** SDK API key for the target environment */
     apiKey: string;
-    /** Flag values used before the fetch resolves and for unknown keys */
+    /**
+     * Pre-resolved flags from the server.
+     *
+     * **Required when using `renderToString`** — pass the result of
+     * `fetchFlags(baseUrl, apiKey)` here, as `renderToString` does not support
+     * Suspense. Without this, the provider will throw during server rendering.
+     *
+     * Optional for `renderToPipeableStream`, RSC, and SPA — the provider will
+     * suspend and fetch flags on its own if omitted.
+     */
+    initialFlags?: Record<string, boolean>;
+    /** Flag values used as defaults for unknown keys */
     fallbacks?: Record<string, boolean>;
     children: ReactNode;
 }
-declare function VexilloProvider({ baseUrl, apiKey, fallbacks, children, }: VexilloProviderProps): React.ReactElement;
+/**
+ * Provides feature flag values to the React tree via Suspense.
+ *
+ * The subtree suspends until flags are resolved — wrap with `<Suspense>`
+ * to show a loading state.
+ *
+ * ```tsx
+ * <Suspense fallback={<Spinner />}>
+ *   <VexilloProvider baseUrl="..." apiKey="...">
+ *     <App />
+ *   </VexilloProvider>
+ * </Suspense>
+ * ```
+ *
+ * ### SSR with `renderToString`
+ * `renderToString` does not support Suspense. Call `fetchFlags` before
+ * rendering and pass the result as `initialFlags`:
+ * ```ts
+ * const flags = await fetchFlags(baseUrl, apiKey);
+ * renderToString(<VexilloProvider initialFlags={flags} ...>);
+ * ```
+ *
+ * ### SSR with `renderToPipeableStream` / RSC
+ * `initialFlags` is optional. The provider suspends and streams the resolved
+ * flags inline. Pass `initialFlags` to avoid the suspension entirely.
+ */
+declare function VexilloProvider({ baseUrl, apiKey, initialFlags, fallbacks, children, }: VexilloProviderProps): React.ReactElement;
 
 /**
  * Returns the current boolean value for a feature flag key.
@@ -22,4 +59,32 @@ declare function VexilloProvider({ baseUrl, apiKey, fallbacks, children, }: Vexi
  */
 declare function useFlag(key: string): boolean;
 
-export { VexilloProvider, type VexilloProviderProps, useFlag };
+/**
+ * Fetches feature flags from your Vexillo deployment.
+ *
+ * Use this on the server before rendering to pass resolved flags as
+ * `initialFlags` to `<VexilloProvider>`.
+ *
+ * ## When to use
+ *
+ * - **`renderToString`** — Suspense is not supported. You MUST call
+ *   `fetchFlags` before rendering and pass the result as `initialFlags`:
+ *   ```ts
+ *   const flags = await fetchFlags(baseUrl, apiKey);
+ *   renderToString(<VexilloProvider initialFlags={flags} ...>);
+ *   ```
+ *
+ * - **`renderToPipeableStream` / `renderToReadableStream`** — Suspense is
+ *   supported. `initialFlags` is optional; the provider will suspend and
+ *   fetch flags inline. You may still pass `initialFlags` to avoid the
+ *   suspension entirely.
+ *
+ * - **React Server Components (Next.js App Router)** — call `fetchFlags`
+ *   in your server component and pass the result as `initialFlags`.
+ *
+ * - **SPA (no SSR)** — omit `initialFlags`. The provider fetches on the
+ *   client and suspends until resolved.
+ */
+declare function fetchFlags(baseUrl: string, apiKey: string): Promise<Record<string, boolean>>;
+
+export { VexilloProvider, type VexilloProviderProps, fetchFlags, useFlag };

package/dist/index.mjs

@@ -1,49 +1,67 @@
 // src/provider.tsx
 import {
   createContext,
-  useContext,
-  useEffect,
-  useState
+  use,
+  useContext
 } from "react";
+
+// src/fetch-flags.ts
+async function fetchFlags(baseUrl, apiKey) {
+  try {
+    const res = await fetch(`${baseUrl}/api/flags`, {
+      headers: { Authorization: `Bearer ${apiKey}` }
+    });
+    if (!res.ok) {
+      console.warn(
+        `Vexillo: fetchFlags received status ${res.status} ${res.statusText}. Returning empty flags.`
+      );
+      return {};
+    }
+    const data = await res.json();
+    const map = {};
+    for (const f of data.flags) {
+      map[f.key] = f.enabled;
+    }
+    return map;
+  } catch (e) {
+    console.warn("Vexillo: fetchFlags failed. Returning empty flags.");
+    return {};
+  }
+}
+
+// src/provider.tsx
 import { jsx } from "react/jsx-runtime";
 var VexilloContext = createContext(null);
+var clientCache = /* @__PURE__ */ new Map();
+function getOrCreateFlagPromise(baseUrl, apiKey) {
+  const key = `${baseUrl}__${apiKey}`;
+  if (!clientCache.has(key)) {
+    clientCache.set(key, fetchFlags(baseUrl, apiKey));
+  }
+  return clientCache.get(key);
+}
 function VexilloProvider({
   baseUrl,
   apiKey,
+  initialFlags,
   fallbacks = {},
   children
 }) {
-  const [flags, setFlags] = useState(null);
-  const [error, setError] = useState(null);
-  useEffect(() => {
-    let cancelled = false;
-    fetch(`${baseUrl}/api/flags`, {
-      headers: { Authorization: `Bearer ${apiKey}` }
-    }).then((res) => {
-      if (!res.ok) {
-        throw new Error(
-          `Vexillo: API responded with status ${res.status} ${res.statusText}`
-        );
-      }
-      return res.json();
-    }).then((data) => {
-      if (cancelled) return;
-      const map = {};
-      for (const f of data.flags) {
-        map[f.key] = f.enabled;
-      }
-      setFlags(map);
-    }).catch((err) => {
-      if (cancelled) return;
-      setError(
-        err instanceof Error ? err : new Error(`Vexillo: unexpected error \u2014 ${String(err)}`)
-      );
-    });
-    return () => {
-      cancelled = true;
-    };
-  }, [apiKey, baseUrl]);
-  if (error) throw error;
+  const isServer = typeof window === "undefined";
+  if (initialFlags) {
+    const key = `${baseUrl}__${apiKey}`;
+    if (!isServer && !clientCache.has(key)) {
+      clientCache.set(key, Promise.resolve(initialFlags));
+    }
+    return /* @__PURE__ */ jsx(VexilloContext.Provider, { value: { flags: initialFlags, fallbacks }, children });
+  }
+  let flagPromise;
+  if (isServer) {
+    flagPromise = fetchFlags(baseUrl, apiKey);
+  } else {
+    flagPromise = getOrCreateFlagPromise(baseUrl, apiKey);
+  }
+  const flags = use(flagPromise);
   return /* @__PURE__ */ jsx(VexilloContext.Provider, { value: { flags, fallbacks }, children });
 }
 function useVexilloContext() {
@@ -58,12 +76,13 @@ function useVexilloContext() {
 function useFlag(key) {
   var _a;
   const { flags, fallbacks } = useVexilloContext();
-  if (flags !== null && key in flags) {
+  if (key in flags) {
     return flags[key];
   }
   return (_a = fallbacks[key]) != null ? _a : false;
 }
 export {
   VexilloProvider,
+  fetchFlags,
   useFlag
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vexillo/react-sdk",
-  "version": "1.0.7",
+  "version": "2.0.0",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -19,8 +19,8 @@
     "dist"
   ],
   "peerDependencies": {
-    "react": "^18 || ^19",
-    "react-dom": "^18 || ^19"
+    "react": "^19",
+    "react-dom": "^19"
   },
   "devDependencies": {
     "@testing-library/react": "^16",