@vexillo/react-sdk 1.0.5 → 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

@@ -0,0 +1,90 @@
+import React, { ReactNode } from 'react';
+
+interface VexilloProviderProps {
+    /** Base URL of your Vexillo deployment (e.g. "https://vexillo.example.com") */
+    baseUrl: string;
+    /** SDK API key for the target environment */
+    apiKey: string;
+    /**
+     * 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;
+}
+/**
+ * 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.
+ *
+ * - Before the provider's fetch resolves (including SSR), returns the value
+ *   from `fallbacks`, or `false` if the key is absent.
+ * - After the fetch resolves, returns the live value from the API, falling
+ *   back to `fallbacks[key] ?? false` for keys not present in the response.
+ * - Throws if called outside a `<VexilloProvider>`.
+ */
+declare function useFlag(key: string): boolean;
+
+/**
+ * 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

@@ -0,0 +1,88 @@
+// src/provider.tsx
+import {
+  createContext,
+  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 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() {
+  const ctx = useContext(VexilloContext);
+  if (ctx === null) {
+    throw new Error("useFlag must be called inside a <VexilloProvider>.");
+  }
+  return ctx;
+}
+
+// src/use-flag.ts
+function useFlag(key) {
+  var _a;
+  const { flags, fallbacks } = useVexilloContext();
+  if (key in flags) {
+    return flags[key];
+  }
+  return (_a = fallbacks[key]) != null ? _a : false;
+}
+export {
+  VexilloProvider,
+  fetchFlags,
+  useFlag
+};

package/package.json

@@ -1,18 +1,17 @@
 {
   "name": "@vexillo/react-sdk",
-  "version": "1.0.5",
+  "version": "2.0.0",
+  "type": "module",
   "license": "MIT",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"
   },
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
+      "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
     }
   },
@@ -20,8 +19,8 @@
     "dist"
   ],
   "peerDependencies": {
-    "react": "^18 || ^19",
-    "react-dom": "^18 || ^19"
+    "react": "^19",
+    "react-dom": "^19"
   },
   "devDependencies": {
     "@testing-library/react": "^16",

package/dist/index.d.mts

@@ -1,25 +0,0 @@
-import React, { ReactNode } from 'react';
-
-interface VexilloProviderProps {
-    /** Base URL of your Vexillo deployment (e.g. "https://vexillo.example.com") */
-    baseUrl: string;
-    /** SDK API key for the target environment */
-    apiKey: string;
-    /** Flag values used before the fetch resolves and for unknown keys */
-    fallbacks?: Record<string, boolean>;
-    children: ReactNode;
-}
-declare function VexilloProvider({ baseUrl, apiKey, fallbacks, children, }: VexilloProviderProps): React.ReactElement;
-
-/**
- * Returns the current boolean value for a feature flag key.
- *
- * - Before the provider's fetch resolves (including SSR), returns the value
- *   from `fallbacks`, or `false` if the key is absent.
- * - After the fetch resolves, returns the live value from the API, falling
- *   back to `fallbacks[key] ?? false` for keys not present in the response.
- * - Throws if called outside a `<VexilloProvider>`.
- */
-declare function useFlag(key: string): boolean;
-
-export { VexilloProvider, type VexilloProviderProps, useFlag };

package/dist/index.js

@@ -1,69 +0,0 @@
-// src/provider.tsx
-import {
-  createContext,
-  useContext,
-  useEffect,
-  useState
-} from "react";
-import { jsx } from "react/jsx-runtime";
-var VexilloContext = createContext(null);
-function VexilloProvider({
-  baseUrl,
-  apiKey,
-  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;
-  return /* @__PURE__ */ jsx(VexilloContext.Provider, { value: { flags, fallbacks }, children });
-}
-function useVexilloContext() {
-  const ctx = useContext(VexilloContext);
-  if (ctx === null) {
-    throw new Error("useFlag must be called inside a <VexilloProvider>.");
-  }
-  return ctx;
-}
-
-// src/use-flag.ts
-function useFlag(key) {
-  var _a;
-  const { flags, fallbacks } = useVexilloContext();
-  if (flags !== null && key in flags) {
-    return flags[key];
-  }
-  return (_a = fallbacks[key]) != null ? _a : false;
-}
-export {
-  VexilloProvider,
-  useFlag
-};