feat: add feature flag capabilities to across app (#1935)

We want to be able to toggle features on and off for specific users with Amplitude experiment. 

This PR introduces a mechanism for initialising feature flags across the frontend with the relevant user data. The feature flags are fetched on application load and when the wallet provider changes the connected wallet. The feature flags are also cached in localstorage, so that subsequent refreshes will be faster. 

This is the first small step towards feature flags. In the future, we might want to
* support feature flag payloads so that properties like text, colours, and images can be changed from amplitude without requiring a commit. 
* Improve speed by caching feature flags in vercel functions on the edge


https://github.com/user-attachments/assets/f60f5a66-28f8-457c-bc7b-86b316a340c3

feature flag configuration page: https://app.amplitude.com/experiment/risklabs/414806/config/680059/configure

Author: 0xjorgen

package.json

@@ -9,6 +9,7 @@
     "@across-protocol/contracts-v4.1.1": "npm:@across-protocol/contracts@4.1.1",
     "@across-protocol/sdk": "^4.3.98",
     "@amplitude/analytics-browser": "^2.3.5",
+    "@amplitude/experiment-js-client": "^1.18.0",
     "@balancer-labs/sdk": "1.1.6-beta.16",
     "@coral-xyz/borsh": "^0.30.1",
     "@emotion/react": "^11.13.0",

src/components/Footer/Footer.tsx

@@ -7,6 +7,7 @@ import {
   StyledTwitterIcon,
 } from "./Footer.styles";
 import { ReactComponent as DiscordLogo } from "assets/icons/discord.svg";
+import { useFeatureFlag } from "../../hooks";
 
 export const NAV_LINKS = [
   {
@@ -42,6 +43,7 @@ export const NAV_LINKS = [
 ];
 
 const Footer = () => {
+  const hasDemoFlag = useFeatureFlag("demo-flag");
   return (
     <Wrapper>
       <LinksContainer>
@@ -63,6 +65,7 @@ const Footer = () => {
         rel="noopener noreferrer"
       >
         <FooterLogo />
+        {hasDemoFlag && <p> - Demo feature flag active</p>}
       </AccentLink>
     </Wrapper>
   );

src/hooks/feature-flags/feature-flags.ts

@@ -0,0 +1,2 @@
+export const FEATURE_FLAGS = ["demo-flag"] as const;
+export type FeatureFlag = (typeof FEATURE_FLAGS)[number];

src/hooks/feature-flags/featureFlagsContext.tsx

@@ -0,0 +1,13 @@
+import { createContext } from "react";
+import { Variants } from "@amplitude/experiment-js-client";
+
+interface FeatureFlagsContextValue {
+  flags: Variants;
+  isLoading: boolean;
+  isInitialized: boolean;
+  initializeFeatureFlags: () => void;
+  fetchFlags: () => Promise<void>;
+}
+
+export const FeatureFlagsContext =
+  createContext<FeatureFlagsContextValue | null>(null);

src/hooks/feature-flags/featureFlagsProvider.tsx

@@ -0,0 +1,66 @@
+import { ReactNode, useCallback, useRef, useState } from "react";
+import {
+  Experiment,
+  ExperimentClient,
+  Variants,
+} from "@amplitude/experiment-js-client";
+import { FEATURE_FLAGS } from "./feature-flags";
+import { FeatureFlagsContext } from "./featureFlagsContext";
+
+const publicDeploymentKey = "client-jAXxBGw14klnGdfOPcGCrIpbvpvBXZqL";
+
+export function FeatureFlagsProvider({ children }: { children: ReactNode }) {
+  const [flags, setFlags] = useState<Variants>({});
+  const [isLoading, setIsLoading] = useState(false);
+  const [isInitialized, setIsInitialized] = useState(false);
+  const experimentClientRef = useRef<ExperimentClient | null>(null);
+
+  const initializeFeatureFlags = useCallback(() => {
+    if (experimentClientRef.current) {
+      console.warn("Experiment client already initialized");
+      return;
+    }
+    experimentClientRef.current = Experiment.initializeWithAmplitudeAnalytics(
+      publicDeploymentKey,
+      {}
+    );
+    // set flags from localstorage cache before a fetch is initialized
+    setFlags(experimentClientRef.current.all());
+    setIsInitialized(true);
+  }, []);
+
+  const fetchFlags = useCallback(async () => {
+    if (!experimentClientRef.current) {
+      console.error(
+        "Experiment client not initialized. Call initializeExperiment() first."
+      );
+      return;
+    }
+
+    try {
+      setIsLoading(true);
+      await experimentClientRef.current.fetch(undefined, {
+        flagKeys: [...FEATURE_FLAGS],
+      });
+      setFlags(experimentClientRef.current.all());
+    } catch (error) {
+      console.error("Failed to fetch feature flags:", error);
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
+
+  return (
+    <FeatureFlagsContext.Provider
+      value={{
+        flags,
+        isLoading,
+        isInitialized,
+        initializeFeatureFlags,
+        fetchFlags,
+      }}
+    >
+      {children}
+    </FeatureFlagsContext.Provider>
+  );
+}

src/hooks/feature-flags/useFeatureFlag.tsx

@@ -0,0 +1,12 @@
+import { useContext } from "react";
+
+import { FeatureFlag } from "./feature-flags";
+import { FeatureFlagsContext } from "./featureFlagsContext";
+
+export const useFeatureFlag = (featureFlag: FeatureFlag): boolean => {
+  const context = useContext(FeatureFlagsContext);
+  if (!context) {
+    throw new Error("useFeatureFlag must be used within FeatureFlagsProvider");
+  }
+  return context.flags[featureFlag]?.value === "on";
+};

src/hooks/feature-flags/useFeatureFlagsContext.tsx

@@ -0,0 +1,10 @@
+import { useContext } from "react";
+import { FeatureFlagsContext } from "./featureFlagsContext";
+
+export const useFeatureFlagsContext = () => {
+  const context = useContext(FeatureFlagsContext);
+  if (!context) {
+    throw new Error("useFeatureFlags must be used within FeatureFlagsProvider");
+  }
+  return context;
+};

src/hooks/index.ts

@@ -17,4 +17,5 @@ export * from "./useWalletTrace";
 export * from "./useQueue";
 export * from "./useAmplitude";
 export * from "./useRewardSummary";
+export * from "./feature-flags/useFeatureFlag";
 export * from "./useTokenInput";

src/hooks/useInitialUserPropTraces.ts

@@ -1,15 +1,17 @@
-import { useState, useEffect } from "react";
+import { useEffect, useState } from "react";
 
 import { useConnection } from "hooks";
 import {
+  identifyReferrer,
   identifyUserWallet,
-  setUserId,
   identifyWalletChainId,
-  identifyReferrer,
+  setUserId,
 } from "utils/amplitude";
 import { ampli } from "ampli";
+import { useFeatureFlagsContext } from "./feature-flags/useFeatureFlagsContext";
 
 export function useInitialUserPropTraces(isAmpliLoaded: boolean) {
+  const { fetchFlags } = useFeatureFlagsContext();
   const [areInitialUserPropsSet, setAreInitialUserPropsSet] = useState(false);
   const [prevTrackedAccount, setPrevTrackedAccount] = useState<
     string | undefined
@@ -47,6 +49,9 @@ export function useInitialUserPropTraces(isAmpliLoaded: boolean) {
       await identifyReferrer()?.promise;
 
       setAreInitialUserPropsSet(true);
+
+      // Fetch feature flags AFTER userId is set
+      await fetchFlags();
       setPrevTrackedAccount(account);
     })();
   }, [
@@ -56,6 +61,7 @@ export function useInitialUserPropTraces(isAmpliLoaded: boolean) {
     prevTrackedAccount,
     chainId,
     connector,
+    fetchFlags,
   ]);
 
   useEffect(() => {

src/hooks/useLoadAmpli.ts

@@ -1,16 +1,18 @@
-import { useState, useEffect } from "react";
+import { useEffect, useState } from "react";
 import * as amplitude from "@amplitude/analytics-browser";
 
 import { ampli } from "ampli";
 import {
   amplitudeAPIKey,
+  amplitudeServerUrl,
   isAmplitudeLoggingEnabled,
   isProductionBuild,
-  amplitudeServerUrl,
 } from "utils";
+import { useFeatureFlagsContext } from "./feature-flags/useFeatureFlagsContext";
 
 export function useLoadAmpli() {
   const [isAmpliLoaded, setIsAmpliLoaded] = useState(false);
+  const { initializeFeatureFlags } = useFeatureFlagsContext();
 
   useEffect(() => {
     if (amplitudeAPIKey && !isAmpliLoaded) {
@@ -40,10 +42,11 @@ export function useLoadAmpli() {
             }).promise
         )
         .then(() => {
+          initializeFeatureFlags();
           setIsAmpliLoaded(true);
         });
     }
-  }, [isAmpliLoaded]);
+  }, [isAmpliLoaded, initializeFeatureFlags]);
 
   return { isAmpliLoaded };
 }