feat: add ability to bootstrap flags on server and populate clients

.github/workflows/package-ci.yml

@@ -13,9 +13,11 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
       - name: Checkout source code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
+      - name: Enable corepack
+        run: corepack enable
       - name: Use Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version-file: ".nvmrc"
           cache: "yarn"

.github/workflows/publish.yml

@@ -9,9 +9,11 @@ jobs:
   release:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       # Setup .npmrc file to publish to npm
-      - uses: actions/setup-node@v3
+      - name: Enable corepack
+        run: corepack enable
+      - uses: actions/setup-node@v4
         with:
           node-version-file: ".nvmrc"
           cache: "yarn"

.vscode/settings.json

@@ -20,6 +20,9 @@
   "[typescriptreact]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   },
+  "[vue]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
   "[yaml]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   },
@@ -32,6 +35,7 @@
     "**/node_modules": true
   },
   "search.exclude": {
+    "**/.next": true,
     "**/build": true,
     "**/dist": true,
     "**/coverage": true,

.yarnrc.yml

@@ -1,3 +1 @@
 nodeLinker: node-modules
-
-yarnPath: .yarn/releases/yarn-4.1.1.cjs

package.json

@@ -21,7 +21,7 @@
     "version": "lerna version --exact --no-push",
     "docs": "./docs.sh"
   },
-  "packageManager": "yarn@4.1.1",
+  "packageManager": "yarn@4.10.3",
   "devDependencies": {
     "lerna": "^8.1.3",
     "prettier": "^3.5.2",

packages/browser-sdk/README.md

@@ -227,7 +227,71 @@ const flags = reflagClient.getFlags();
 Just as `isEnabled`, accessing `config` on the object returned by `getFlags` does not automatically
 generate a `check` event, contrary to the `config` property on the object returned by `getFlag`.
 
-## Updating user/company/other context
+## Server-side rendering and bootstrapping
+
+For server-side rendered applications, you can eliminate the initial network request by bootstrapping the client with pre-fetched flag data.
+
+### Init options bootstrapped
+
+```typescript
+type Configuration = {
+  logger: console; // by default only logs warn/error, by passing `console` you'll log everything
+  apiBaseUrl?: "https://front.reflag.com";
+  sseBaseUrl?: "https://livemessaging.bucket.co";
+  feedback?: undefined; // See FEEDBACK.md
+  enableTracking?: true; // set to `false` to stop sending track events and user/company updates to Reflag servers. Useful when you're impersonating a user
+  offline?: boolean; // Use the SDK in offline mode. Offline mode is useful during testing and local development
+  bootstrappedFlags?: FetchedFlags; // Pre-fetched flags from server-side (see Server-side rendering section)
+};
+```
+
+### Using bootstrappedFlags
+
+Use the Node SDK's `getFlagsForBootstrap()` method to pre-fetch flags server-side, then pass them to the browser client:
+
+```typescript
+// Server-side: Get flags using Node SDK
+import { ReflagClient as ReflagNodeClient } from "@reflag/node-sdk";
+
+const serverClient = new ReflagNodeClient({ secretKey: "your-secret-key" });
+await serverClient.initialize();
+
+const { flags } = serverClient.getFlagsForBootstrap({
+  user: { id: "user123", name: "John Doe", email: "john@acme.com" },
+  company: { id: "company456", name: "Acme Inc", plan: "enterprise" },
+});
+
+// Pass flags data to client using your framework's preferred method
+// or for example in a script tag
+app.get("/", (req, res) => {
+  res.set("Content-Type", "text/html");
+  res.send(
+    Buffer.from(
+      `<script>var flags = ${JSON.stringify(flags)};</script>
+      <main id="app"></main>`,
+    ),
+  );
+});
+
+// Client-side: Initialize with pre-fetched flags
+import { ReflagClient } from "@reflag/browser-sdk";
+
+const reflagClient = new ReflagClient({
+  publishableKey: "your-publishable-key",
+  user: { id: "user123", name: "John Doe", email: "john@acme.com" },
+  company: { id: "company456", name: "Acme Inc", plan: "enterprise" },
+  bootstrappedFlags: flags, // No network request needed
+});
+
+await reflagClient.initialize(); // Initializes all but flags
+const { isEnabled } = reflagClient.getFlag("huddle");
+```
+
+This eliminates loading states and improves performance by avoiding the initial flags API call.
+
+## Context management
+
+### Updating user/company/other context
 
 Attributes given for the user/company/other context in the ReflagClient constructor can be updated for use in flag targeting evaluation with the `updateUser()`, `updateCompany()` and `updateOtherContext()` methods.
 They return a promise which resolves once the flags have been re-evaluated follow the update of the attributes.
@@ -244,6 +308,57 @@ await reflagClient.updateUser({ voiceHuddleOptIn: (!isEnabled).toString() });
 
 > [!NOTE] > `user`/`company` attributes are also stored remotely on the Reflag servers and will automatically be used to evaluate flag targeting if the page is refreshed.
 
+### setContext()
+
+The `setContext()` method allows you to replace the entire context (user, company, and other attributes) at once. This method is useful when you need to completely change the context, such as when a user logs in or switches between different accounts.
+
+```ts
+await reflagClient.setContext({
+  user: {
+    id: "new-user-123",
+    name: "Jane Doe",
+    email: "jane@example.com",
+    role: "admin",
+  },
+  company: {
+    id: "company-456",
+    name: "New Company Inc",
+    plan: "enterprise",
+  },
+  other: {
+    feature: "beta",
+    locale: "en-US",
+  },
+});
+```
+
+The method will:
+
+- Replace the entire context with the new values
+- Re-evaluate all flags based on the new context
+- Update the user and company information on Reflag servers
+- Return a promise that resolves once the flags have been re-evaluated
+
+### getContext()
+
+The `getContext()` method returns the current context being used for flag evaluation. This is useful for debugging or when you need to inspect the current user, company, and other attributes.
+
+```ts
+const currentContext = reflagClient.getContext();
+console.log(currentContext);
+// {
+//   user: { id: "user-123", name: "John Doe", email: "john@example.com" },
+//   company: { id: "company-456", name: "Acme Inc", plan: "enterprise" },
+//   other: { locale: "en-US", feature: "beta" }
+// }
+```
+
+The returned context object contains:
+
+- `user`: Current user attributes (if any)
+- `company`: Current company attributes (if any)
+- `other`: Additional context attributes not related to user or company
+
 ## Toolbar
 
 The Reflag Toolbar is great for toggling flags on/off for yourself to ensure that everything works both when a flag is on and when it's off.

packages/browser-sdk/example/typescript/app.ts

@@ -1,4 +1,4 @@
-import { ReflagClient, CheckEvent, RawFlags } from "../../src";
+import { ReflagClient, RawFlags } from "../../src";
 
 const urlParams = new URLSearchParams(window?.location?.search);
 const publishableKey = urlParams.get("publishableKey");

packages/browser-sdk/index.html

@@ -15,6 +15,7 @@
       const urlParams = new URLSearchParams(window.location.search);
       const publishableKey = urlParams.get("publishableKey");
       const flagKey = urlParams.get("flagKey") ?? "huddles";
+      const isBootstrapped = urlParams.get("bootstrapped") === "true";
     </script>
     <style>
       body {
@@ -47,11 +48,29 @@
             placement: "bottom-right",
           },
         },
+        bootstrappedFlags: isBootstrapped
+          ? {
+              [flagKey]: {
+                key: flagKey,
+                isEnabled: true,
+              },
+            }
+          : undefined,
       });
 
+      function setVisibility(isVisible) {
+        const startHuddleElem = document.getElementById("start-huddle");
+        if (startHuddleElem)
+          startHuddleElem.style.display = isVisible ? "block" : "none";
+      }
+
       reflag.initialize().then(() => {
         console.log("Reflag initialized");
         document.getElementById("loading").style.display = "none";
+        if (isBootstrapped) {
+          const flag = reflag.getFlag(flagKey);
+          setVisibility(flag.isEnabled);
+        }
       });
 
       reflag.on("check", (check) =>
@@ -61,15 +80,7 @@
       reflag.on("flagsUpdated", (flags) => {
         console.log("Flags updated");
         const flag = reflag.getFlag(flagKey);
-
-        const startHuddleElem = document.getElementById("start-huddle");
-        if (flag.isEnabled) {
-          // show the start-huddle button
-          if (startHuddleElem) startHuddleElem.style.display = "block";
-        } else {
-          // hide the start-huddle button
-          if (startHuddleElem) startHuddleElem.style.display = "none";
-        }
+        setVisibility(flag.isEnabled);
       });
     </script>
   </body>

packages/browser-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reflag/browser-sdk",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "packageManager": "yarn@4.1.1",
   "license": "MIT",
   "repository": {
@@ -13,15 +13,16 @@
   "scripts": {
     "dev": "vite",
     "build": "tsc --project tsconfig.build.json && vite build",
-    "test": "tsc --project tsconfig.json && vitest -c vitest.config.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "test:e2e": "yarn build && playwright test",
-    "test:ci": "tsc --project tsconfig.json && vitest run -c vitest.config.ts --reporter=default --reporter=junit --outputFile=junit.xml && yarn test:e2e",
-    "coverage": "vitest run --coverage",
+    "test:ci": "yarn test --reporter=default --reporter=junit --outputFile=junit.xml && yarn test:e2e",
+    "coverage": "yarn test --coverage",
     "lint": "eslint .",
     "lint:ci": "eslint --output-file eslint-report.json --format json .",
     "prettier": "prettier --check .",
     "format": "yarn lint --fix && yarn prettier --write",
-    "preversion": "yarn lint && yarn prettier && yarn vitest run -c vitest.config.ts && yarn build"
+    "preversion": "yarn lint && yarn prettier && yarn test && yarn build"
   },
   "files": [
     "dist"
@@ -37,7 +38,7 @@
   },
   "dependencies": {
     "@floating-ui/dom": "^1.6.8",
-    "canonical-json": "^0.0.4",
+    "fast-equals": "^5.2.2",
     "js-cookie": "^3.0.5",
     "preact": "^10.22.1"
   },