implement Next.js SDK support

Author: alexcasalboni

package-lock.json

@@ -13,7 +13,15 @@
     },
     "./react": {
       "import": "./dist/react.es.js",
-      "types": "./dist/react.d.ts"
+      "types": "./dist/react/index.d.ts"
+    },
+    "./next": {
+      "import": "./dist/next.es.js",
+      "types": "./dist/next/index.d.ts"
+    },
+    "./next/server": {
+      "import": "./dist/next-server.es.js",
+      "types": "./dist/next/server.d.ts"
     },
     "./toolbar.css": "./dist/toolbar.css"
   },
@@ -46,34 +54,31 @@
   "author": "",
   "license": "Apache-2.0",
   "peerDependencies": {
-    "unleash-proxy-client": "^3.0.0",
-    "@unleash/proxy-client-react": "^5.0.1"
+    "unleash-proxy-client": "^3.0.0"
   },
   "peerDependenciesMeta": {
-    "react": {
-      "optional": true
-    },
     "@unleash/proxy-client-react": {
       "optional": true
     }
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.10",
+    "@biomejs/biome": "^2.3.12",
     "@eslint/js": "^9.39.2",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.0",
     "@types/eslint": "^9.6.1",
     "@types/node": "^20.10.5",
-    "@types/react": "^18.2.45",
+    "@types/react": "^18.3.1 || ^19.2.3",
+    "@types/react-dom": "^18.3.1 || ^19.2.3",
     "@unleash/proxy-client-react": "^5.0.1",
     "@vitest/coverage-v8": "^4.0.15",
     "cssnano": "^7.1.2",
     "eslint": "^9.39.2",
     "jsdom": "^27.3.0",
     "postcss": "^8.5.6",
-    "react": "^18.2.0",
-    "react-dom": "^18.3.1",
+    "react": "^18.3.1 || ^19.2.3",
+    "react-dom": "^18.3.1 || ^19.2.3",
     "terser": "^5.44.1",
     "typescript": "^5.3.3",
     "typescript-eslint": "^8.49.0",

package.json

@@ -652,4 +652,46 @@ describe('ToolbarStateManager', () => {
       expect(freshState.contextOverrides.userId).toBeUndefined();
     });
   });
+
+  describe('cookie sync', () => {
+    beforeEach(() => {
+      // Clear any existing cookies
+      document.cookie = 'unleash-toolbar-state=; path=/; max-age=0';
+    });
+
+    it('should not sync to cookies by default', () => {
+      const manager = new ToolbarStateManager('local', 'test-toolbar-state', false);
+      manager.recordEvaluation('flag', 'flag', true, true, {});
+      manager.setFlagOverride('flag', { type: 'flag', value: false });
+
+      // Cookie should not be set
+      expect(document.cookie).not.toContain('unleash-toolbar-state');
+    });
+
+    it('should sync to cookies when enabled', () => {
+      const manager = new ToolbarStateManager('local', 'test-toolbar-state', false);
+      manager.enableCookieSync();
+      
+      manager.recordEvaluation('flag', 'flag', true, true, {});
+      manager.setFlagOverride('flag', { type: 'flag', value: false });
+
+      // Cookie should be set
+      expect(document.cookie).toContain('unleash-toolbar-state');
+    });
+
+    it('should clear cookie when clearing storage with sync enabled', () => {
+      const manager = new ToolbarStateManager('local', 'test-toolbar-state', false);
+      manager.enableCookieSync();
+      
+      manager.recordEvaluation('flag', 'flag', true, true, {});
+      expect(document.cookie).toContain('unleash-toolbar-state');
+
+      manager.clearPersistence();
+      
+      // Cookie should be cleared
+      const cookies = document.cookie.split(';').map(c => c.trim());
+      const toolbarCookie = cookies.find(c => c.startsWith('unleash-toolbar-state='));
+      expect(toolbarCookie).toBeUndefined();
+    });
+  });
 });

src/__tests__/state.test.ts

@@ -87,6 +87,9 @@ export class UnleashToolbar implements UnleashToolbarInstance {
  * Initialize the Unleash Toolbar with a client
  * This is the main entry point - handles both toolbar creation and client wrapping
  * Returns the wrapped client directly for immediate use
+ *
+ * @param client - The Unleash client to wrap
+ * @param options - Toolbar configuration options
  */
 export function initUnleashToolbar(
   client: UnleashClient,
@@ -95,8 +98,15 @@ export function initUnleashToolbar(
   const storageMode = options.storageMode || 'local';
   const storageKey = options.storageKey || 'unleash-toolbar-state';
   const sortAlphabetically = options.sortAlphabetically || false;
+  const enableCookieSync = options.enableCookieSync || false;
 
   const stateManager = new ToolbarStateManager(storageMode, storageKey, sortAlphabetically);
+
+  // Enable cookie sync if requested (for Next.js SSR)
+  if (enableCookieSync) {
+    stateManager.enableCookieSync();
+  }
+
   const wrappedClient = wrapUnleashClient(client, stateManager);
   const toolbar = new UnleashToolbar(stateManager, wrappedClient, options);