vwo-fme-react-sdk 0.1.0 → 1.0.0

package/CHANGELOG.md

@@ -5,7 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.0.0] - 2025-02-13
+## [1.0.0] - 2025-04-12
+
+### Changed
+
+- Stable Release of VWO FME React SDK
+
+### Fixed
+
+- Update dependency of `useMemo` hook inside `useGetFlag` hook
+
+## [0.2.0] - 2025-04-11
+
+### Added
+
+- Ensure compatibility with older versions that do not support optional chaining.
+- Allow user context to be optionally passed to the `useGetFlag` hook, enabling it to override the context provided to the `VWOProvider` hook.
+
+## [0.1.0] - 2025-02-13
 
 ### Added
 
@@ -13,7 +30,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
   #### Basic Usage
 
-  ```javascript
+  ```typescript
   import React from 'react';
   import { VWOProvider } from 'vwo-fme-react-sdk';
 
@@ -34,7 +51,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   };
 
   const App = () => (
-    <VWOProvider config={vwoConfig} context={userContext}>
+    <VWOProvider config={vwoConfig} userContext={userContext}>
       <YourComponent />
     </VWOProvider>
   );

package/README.md

@@ -47,7 +47,7 @@ const userContext = {
 };
 
 const App = () => (
-  <VWOProvider config={vwoConfig} context={userContext}>
+  <VWOProvider config={vwoConfig} userContext={userContext}>
     <YourComponent />
   </VWOProvider>
 );
@@ -55,6 +55,49 @@ const App = () => (
 export default App;
 ```
 
+Inside your component, use feature flagging and experimentation
+
+```javascript
+// Import hooks
+import { useGetFlag, useGetFlagVariable } from 'vwo-fme-react-sdk';
+
+const YourComponent = () => {
+  // Retrieve the flag using the feature key
+  const { flag, isReady } = useGetFlag('feature_key');
+
+  // Or, pass userContext, if not provided at the time of using VWOProvider or you want to use updated user context
+  // const { flag, isReady } = useGetFlag('feature_key', userContext);
+
+  if (!isReady()) {
+    return <div>Default/Zero state</div>;
+  }
+  // Check if the flag is enabled
+  const isEnabled = flag?.isEnabled();
+  if (isEnabled) {
+    // Use the flag object returned by useGetFlag to retrieve a specific variable
+    // Replace 'variableKey' with the actual key for the variable you want to retrieve
+    const variableKey = 'variable_name'; // Replace with actual variable key
+    const variableValue = useGetFlagVariable(flag, variableKey, 'default_value');
+
+    // Display the feature flag variable value
+    return (
+      <div>
+        <p>Feature Flag Variable Value: {variableValue}</p>
+      </div>
+    );
+  }
+
+  // Display a message if the feature is not enabled
+  return (
+    <div>
+      <p>Feature is not enabled!</p>
+    </div>
+  );
+};
+
+export default YourComponent;
+```
+
 ## Advanced Configuration Options
 
 To customize the SDK further, additional parameters can be passed to the `VWOProvider` component. Here’s a table describing each option:
@@ -102,9 +145,10 @@ Feature Flags serve as the foundation for all testing, personalization, and roll
 To implement a feature flag, first use the `useGetFlag` hook to retrieve the flag configuration.
 The `useGetFlag` hook provides a simple way to check if a feature is enabled for a specific user and access its variables. It returns a feature flag object that contains methods for checking the feature's status and retrieving any associated variables.
 
-| Parameter    | Description                           | Required | Type   | Example          |
-| ------------ | ------------------------------------- | -------- | ------ | ---------------- |
-| `featureKey` | Unique identifier of the feature flag | Yes      | String | `'new_checkout'` |
+| Parameter    | Description                                                    | Required | Type   | Example                   |
+| ------------ | -------------------------------------------------------------- | -------- | ------ | ------------------------- |
+| `featureKey` | Unique identifier of the feature flag                          | Yes      | String | `'new_checkout'`          |
+| `context`    | User Context to be passed, if not at the time of `VWOProvider` | No       | Object | `{ id: 'unique_user_id'}` |
 
 Example usage:
 
@@ -114,8 +158,14 @@ import { useGetFlag, useGetFlagVariable } from 'vwo-fme-react-sdk'; // Import ho
 
 const YourComponent = () => {
   // Retrieve the flag using the feature key
-  const flag = useGetFlag('feature_key');
+  const { flag, isReady } = useGetFlag('feature_key');
 
+  // Or, pass userContext, if not provided at the time of using VWOProvider or you want to use updated user context
+  // const { flag, isReady } = useGetFlag('feature_key', userContext);
+
+  if (!isReady()) {
+    return <div>Default/Zero state</div>;
+  }
   // Check if the flag is enabled
   const isEnabled = flag?.isEnabled();
   if (isEnabled) {
@@ -202,7 +252,7 @@ const vwoConfig = {
 };
 
 const App = () => (
-  <VWOProvider config={vwoConfig} context={{ id: 'unique_user_id' }}>
+  <VWOProvider config={vwoConfig} userContext={{ id: 'unique_user_id' }}>
     <YourComponent />
   </VWOProvider>
 );
@@ -260,7 +310,7 @@ const vwoConfig = {
 };
 
 const App = () => (
-  <VWOProvider config={vwoConfig} context={{ id: 'unique_user_id' }}>
+  <VWOProvider config={vwoConfig} userContext={{ id: 'unique_user_id' }}>
     <YourComponent />
   </VWOProvider>
 );
@@ -290,7 +340,7 @@ const options = {
 };
 
 const App = () => (
-  <VWOProvider config={vwoConfig} context={{ id: 'unique_user_id' }}>
+  <VWOProvider config={vwoConfig} userContext={{ id: 'unique_user_id' }}>
     <YourComponent />
   </VWOProvider>
 );
@@ -311,7 +361,7 @@ const options = {
 };
 
 const App = () => (
-  <VWOProvider config={vwoConfig} context={{ id: 'unique_user_id' }}>
+  <VWOProvider config={vwoConfig} userContext={{ id: 'unique_user_id' }}>
     <YourComponent />
   </VWOProvider>
 );

package/dist/VWOContext.d.ts

@@ -13,12 +13,5 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-/**
- * Context for VWO SDK
- */
 export declare const VWOContext: any;
-/**
- * Hook to use the VWO context
- * @returns VWO context
- */
 export declare const useVWOContext: () => any;

package/dist/VWOProvider.d.ts

@@ -13,23 +13,22 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { ReactNode } from 'react';
-/**
- * Props for VWOProvider
- */
+import React, { ReactNode } from 'react';
 interface VWOProviderProps {
   client?: any;
   config?: any;
-  context: any;
+  userContext?: any;
   children: ReactNode;
 }
 /**
- * VWOProvider component to provide the VWO SDK instance and context to the app
- * @param client - VWO SDK instance
- * @param config - VWO SDK config (initialization config)
- * @param context - VWO SDK context (userContext)
- * @param children - React children (ReactNode)
- * @returns VWOProvider component
+ * VWOProvider component to provide VWO client and configuration context to child components.
+ *
+ * @param {Object} props - The properties for the VWOProvider component.
+ * @param {Object} props.client - The VWO client instance.
+ * @param {Object} props.config - Configuration settings for the VWO client.
+ * @param {Object} props.userContext - Initial user context for the VWO client.
+ * @param {React.ReactNode} props.children - Child components that will have access to the VWO context.
+ * @returns {JSX.Element} The provider component wrapping its children with VWO context.
  */
-export declare const VWOProvider: ({ client, config, context, children }: VWOProviderProps) => any;
+export declare const VWOProvider: React.FC<VWOProviderProps>;
 export {};

package/dist/index.d.ts

@@ -20,4 +20,5 @@ export { useGetFlagVariable } from './useGetFlagVariable';
 export { useGetFlagVariables } from './useGetFlagVariable';
 export { useTrackEvent } from './useTrackEvent';
 export { useSetAttribute } from './useSetAttribute';
+export { useVWOContext } from './VWOContext';
 export { init } from 'vwo-fme-node-sdk';

package/dist/useGetFlag.d.ts

@@ -14,8 +14,16 @@
  * limitations under the License.
  */
 /**
- * Hook to get a feature flag value
- * @param featureKey - The key of the feature flag to get
- * @returns The feature flag value
+ * Custom hook to retrieve a feature flag using VWO client.
+ *
+ * @param {string} featureKey - The key of the feature flag to retrieve.
+ * @param {Object} [context] - Optional user context to use for fetching the flag.
+ * @returns {Object} An object containing the flag and a readiness status.
  */
-export declare const useGetFlag: (featureKey: string) => any;
+export declare const useGetFlag: (
+  featureKey: string,
+  context?: any,
+) => {
+  flag: any;
+  isReady: () => boolean;
+};

package/dist/vwo-fme-react-sdk.cjs.development.js

@@ -523,17 +523,11 @@ function getLogger() {
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-/**
- * Context for VWO SDK
- */
 const VWOContext = /*#__PURE__*/React.createContext({
   vwoClient: null,
-  userContext: {}
+  userContext: null,
+  setUserContext: undefined
 });
-/**
- * Hook to use the VWO context
- * @returns VWO context
- */
 const useVWOContext = () => {
   const logger = getLogger();
   try {
@@ -567,69 +561,69 @@ const useVWOContext = () => {
  * limitations under the License.
  */
 /**
- * VWOProvider component to provide the VWO SDK instance and context to the app
- * @param client - VWO SDK instance
- * @param config - VWO SDK config (initialization config)
- * @param context - VWO SDK context (userContext)
- * @param children - React children (ReactNode)
- * @returns VWOProvider component
+ * VWOProvider component to provide VWO client and configuration context to child components.
+ *
+ * @param {Object} props - The properties for the VWOProvider component.
+ * @param {Object} props.client - The VWO client instance.
+ * @param {Object} props.config - Configuration settings for the VWO client.
+ * @param {Object} props.userContext - Initial user context for the VWO client.
+ * @param {React.ReactNode} props.children - Child components that will have access to the VWO context.
+ * @returns {JSX.Element} The provider component wrapping its children with VWO context.
  */
 const VWOProvider = ({
   client,
   config,
-  context,
+  userContext,
   children
 }) => {
   const [vwoClient, setVwoClient] = React.useState(client || null);
-  const vwoClientRef = React.useRef(vwoClient);
-  const isMounted = React.useRef(true);
+  const [context, setContext] = React.useState(userContext || null);
+  const vwoClientRef = React.useRef(vwoClient); // Store the client reference without triggering re-renders
+  const isMounted = React.useRef(true); // Prevent updates after unmount
+  const logger = getLogger();
   // Initialize logger globally before using it
   React.useEffect(() => {
-    if (config?.logger) {
+    if (config != null && config.logger) {
       initLogger(config);
     }
   }, [config]);
-  const logger = getLogger();
-  // Initialize the VWO SDK instance when the component mounts
+  // Initialize the VWO SDK instance only once when the component mounts or if config is updated
   React.useEffect(() => {
+    // If neither vwoClient nor config is provided, log the error
     if (!vwoClient && !config) {
       logger.error("VWOProvider Error: Either `client` or `config` must be provided.");
       return;
     }
-    if (!context || !isObject(context)) {
-      logger.error("VWOProvider Error: `context` is required and must be a valid object.");
-      return;
-    }
-    isMounted.current = true;
-    async function initializeVWO() {
-      if (!vwoClient && config) {
-        try {
-          // Initialize the VWO SDK instance
+    const initializeVWO = async () => {
+      try {
+        if (!vwoClient && config) {
+          // Initialize the VWO SDK instance if vwoClient is not already initialized
           const instance = await vwoFmeNodeSdk.init(config);
           if (isMounted.current) {
-            // Update the VWO SDK instance
             setVwoClient(instance);
-            // Update the ref with the new instance
             vwoClientRef.current = instance;
           }
-        } catch (error) {
-          logger.error("VWO-SDK Initialization failed:");
         }
+      } catch (error) {
+        logger.error(`VWO-SDK Initialization failed: ${error}`);
       }
+    };
+    // Only initialize once
+    if (!vwoClient && config) {
+      initializeVWO();
     }
-    // Initialize the VWO SDK instance
-    initializeVWO();
-    // Cleanup the VWO SDK instance when the component unmounts
     return () => {
       isMounted.current = false;
-      if (vwoClientRef.current?.destroy) vwoClientRef.current.destroy();
+      if (vwoClientRef.current && vwoClientRef.current.destroy) {
+        vwoClientRef.current.destroy();
+      }
     };
-  }, [vwoClient, config]);
-  // Provide the VWO SDK instance and context to the app
+  }, [config, vwoClient]); // Re-run only when config or vwoClient changes
   return React__default.createElement(VWOContext.Provider, {
     value: {
       vwoClient,
-      userContext: context
+      userContext: context,
+      setUserContext: setContext
     }
   }, children);
 };
@@ -686,59 +680,79 @@ const useVWOClient = () => {
  * limitations under the License.
  */
 /**
- * Hook to get a feature flag value
- * @param featureKey - The key of the feature flag to get
- * @returns The feature flag value
+ * Custom hook to retrieve a feature flag using VWO client.
+ *
+ * @param {string} featureKey - The key of the feature flag to retrieve.
+ * @param {Object} [context] - Optional user context to use for fetching the flag.
+ * @returns {Object} An object containing the flag and a readiness status.
  */
-const useGetFlag = featureKey => {
-  // This is the return schema for the flag if the feature key is not found or the flag is not enabled
+const useGetFlag = (featureKey, context) => {
+  // Define the error return schema for the hook
   const errorReturnSchema = {
-    isEnabled: () => false,
-    getVariables: () => [],
-    getVariable: (_key, defaultValue) => defaultValue
+    flag: {
+      isEnabled: () => false,
+      getVariables: () => [],
+      getVariable: (_key, defaultValue) => defaultValue
+    },
+    isReady: () => false
   };
+  // Destructure vwoClient, setUserContext, and userContext from VWOContext
+  const {
+    vwoClient,
+    setUserContext,
+    userContext
+  } = useVWOContext();
+  // State to store the flag and loading status
+  const [flag, setFlag] = React.useState(null);
+  const [isLoading, setIsLoading] = React.useState(true);
+  // Get the logger instance
   const logger = getLogger();
-  try {
+  // Memoize the user context to prevent unnecessary re-renders
+  const stableUserContext = React.useMemo(() => {
+    return context || userContext || {};
+  }, [JSON.stringify(context || userContext || {})]); // Only recreate if userContext actually changes
+  // Define the getFlag function to fetch the feature flag
+  const getFlag = React.useCallback(async () => {
+    // Check if featureKey is provided
     if (!featureKey) {
       logger.error('Feature key is required for useGetFlag hook');
       return errorReturnSchema;
     }
-    const [flag, setFlag] = React.useState(null);
-    const {
-      vwoClient,
-      userContext
-    } = useVWOContext();
-    if (!vwoClient) {
-      logger.error('VWO Client is missing in useGetFlag hook. Ensure VWOProvider is correctly initialized.');
+    // Check if the user context is a valid object
+    if (!isObject(stableUserContext)) {
+      logger.error('Invalid user context in useGetFlag hook');
       return errorReturnSchema;
     }
-    if (!userContext || !isObject(userContext)) {
-      logger.error('Invalid user context in useGetFlag hook. Ensure a valid userContext is provided.');
-      return errorReturnSchema;
+    // Try to fetch the feature flag and handle errors
+    try {
+      setIsLoading(true);
+      const result = await vwoClient.getFlag(featureKey, stableUserContext);
+      setFlag(result);
+      // Set the user context in the context to ensure it's available for other hooks
+      setUserContext(stableUserContext);
+    } catch (error) {
+      logger.error(`Error fetching feature flag "${featureKey}": ${error}`);
+      setFlag(null);
+    } finally {
+      setIsLoading(false);
     }
-    // Memoize the userContext to avoid unnecessary re-fetching
-    const stableUserContext = React.useMemo(() => userContext, [userContext]);
-    // Memoize the getFlag function to avoid re-creation
-    const getFlag = React.useMemo(() => {
-      return async () => {
-        try {
-          const result = await vwoClient.getFlag(featureKey, stableUserContext);
-          setFlag(result);
-        } catch (error) {
-          logger.error(`Error fetching feature flag "${featureKey}": ${error}`);
-          setFlag({});
-        }
-      };
-    }, [featureKey, vwoClient, stableUserContext]);
-    // Runs only when `getFlag` reference changes
-    React.useEffect(() => {
-      getFlag();
-    }, [getFlag]);
-    return flag;
-  } catch (error) {
-    logger.error(`Error getting feature flag: ${error}`);
+  }, [featureKey, stableUserContext, vwoClient]);
+  // Ensure vwoClient is ready
+  if (!vwoClient) {
+    logger.error('VWO Client is missing in useGetFlag hook. Ensure VWOProvider is correctly initialized.');
     return errorReturnSchema;
   }
+  // Run effect when dependencies change to fetch the flag
+  React.useEffect(() => {
+    if (featureKey && vwoClient && stableUserContext) {
+      getFlag();
+    }
+  }, [featureKey, stableUserContext, vwoClient]);
+  // Return the flag and readiness status
+  return {
+    flag,
+    isReady: () => !isLoading && !!flag
+  };
 };
 
 /**
@@ -877,6 +891,10 @@ const useSetAttribute = attributeMap => {
       vwoClient,
       userContext
     } = useVWOContext();
+    if (!vwoClient) {
+      logger.error('VWO Client is missing in useSetAttribute hook. Ensure VWOProvider is correctly initialized.');
+      return {};
+    }
     if (!userContext || !isObject(userContext)) {
       logger.error('Invalid user context in useSetAttribute hook. Ensure a valid userContext is provided.');
       return {};
@@ -901,4 +919,5 @@ exports.useGetFlagVariables = useGetFlagVariables;
 exports.useSetAttribute = useSetAttribute;
 exports.useTrackEvent = useTrackEvent;
 exports.useVWOClient = useVWOClient;
+exports.useVWOContext = useVWOContext;
 //# sourceMappingURL=vwo-fme-react-sdk.cjs.development.js.map