fix(browser-sdk): avoid localStorage crash during SSR

Author: roncohen

packages/browser-sdk/src/flag/flags.ts

@@ -5,7 +5,7 @@ import { ReflagContext } from "../context";
 import { HttpClient } from "../httpClient";
 import { Logger, loggerWithPrefix } from "../logger";
 import RateLimiter from "../rateLimiter";
-import { getLocalStorageAdapter, StorageAdapter } from "../storage";
+import { getDefaultStorageAdapter, StorageAdapter } from "../storage";
 import { createAbortController } from "../utils/abortController";
 import { createEventTarget } from "../utils/eventTarget";
 
@@ -235,7 +235,7 @@ export class FlagsClient {
     this.logger = loggerWithPrefix(logger, "[Flags]");
     this.rateLimiter =
       rateLimiter ?? new RateLimiter(FLAG_EVENTS_PER_MIN, this.logger);
-    this.storage = (cache ? undefined : storage) ?? getLocalStorageAdapter();
+    this.storage = (cache ? undefined : storage) ?? getDefaultStorageAdapter();
     this.cache =
       cache ??
       this.setupCache(this.config.staleTimeMs, this.config.expireTimeMs);

packages/browser-sdk/src/storage.ts

@@ -4,6 +4,20 @@ export type StorageAdapter = {
   removeItem?(key: string): Promise<void>;
 };
 
+export function createMemoryStorageAdapter(): StorageAdapter {
+  const memoryStorage = new Map<string, string>();
+
+  return {
+    getItem: async (key) => memoryStorage.get(key) ?? null,
+    setItem: async (key, value) => {
+      memoryStorage.set(key, value);
+    },
+    removeItem: async (key) => {
+      memoryStorage.delete(key);
+    },
+  };
+}
+
 export function getLocalStorageAdapter(): StorageAdapter {
   if (
     typeof localStorage === "undefined" ||
@@ -24,3 +38,11 @@ export function getLocalStorageAdapter(): StorageAdapter {
     },
   };
 }
+
+export function getDefaultStorageAdapter(): StorageAdapter {
+  try {
+    return getLocalStorageAdapter();
+  } catch {
+    return createMemoryStorageAdapter();
+  }
+}

packages/browser-sdk/test/client.test.ts

@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { ReflagClient } from "../src/client";
 import { FlagsClient } from "../src/flag/flags";
@@ -23,6 +23,25 @@ describe("ReflagClient", () => {
     vi.clearAllMocks();
   });
 
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  describe("storage runtime compatibility", () => {
+    it("can be constructed without localStorage", () => {
+      vi.stubGlobal("localStorage", undefined);
+
+      expect(
+        () =>
+          new ReflagClient({
+            publishableKey: "test-key",
+            user: { id: "user1" },
+            company: { id: "company1" },
+          }),
+      ).not.toThrow();
+    });
+  });
+
   describe("updateUser", () => {
     it("should update the user context", async () => {
       // and send new user data and trigger flag update

packages/browser-sdk/test/storage.test.ts

@@ -0,0 +1,39 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  createMemoryStorageAdapter,
+  getDefaultStorageAdapter,
+  getLocalStorageAdapter,
+} from "../src/storage";
+
+describe("storage adapters", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("memory adapter stores and retrieves values", async () => {
+    const adapter = createMemoryStorageAdapter();
+
+    expect(await adapter.getItem("key")).toBeNull();
+    await adapter.setItem("key", "value");
+    expect(await adapter.getItem("key")).toBe("value");
+
+    await adapter.removeItem?.("key");
+    expect(await adapter.getItem("key")).toBeNull();
+  });
+
+  it("localStorage adapter throws when localStorage is unavailable", () => {
+    vi.stubGlobal("localStorage", undefined);
+    expect(() => getLocalStorageAdapter()).toThrowError(
+      "localStorage is not available. Provide a custom storage adapter.",
+    );
+  });
+
+  it("default adapter falls back when localStorage is unavailable", async () => {
+    vi.stubGlobal("localStorage", undefined);
+    const adapter = getDefaultStorageAdapter();
+
+    await adapter.setItem("fallback", "ok");
+    expect(await adapter.getItem("fallback")).toBe("ok");
+  });
+});