Merge pull request #188 from splitio/migration-guide

Add MIGRATION-GUIDE.md file

CHANGES.txt

@@ -1,7 +1,13 @@
 1.11.0 (January 16, 2023)
- - Added the new `SplitFactoryProvider` component as a replacement for the now deprecated `SplitFactory` component.
- The new component is a revised version of `SplitFactory`, addressing improper handling of the SDK initialization side-effects in the `componentDidMount` and `componentDidUpdate` methods (commit phase), causing some issues like memory leaks and the SDK not reinitializing when component props change (Related to issue #11 and #148).
- The `SplitFactoryProvider` component can be used as a drop-in replacement for `SplitFactory`. It utilizes the React Hooks API, that requires React 16.8.0 or later, and supports server-side rendering. See our documentation for more details (Related to issue #11 and #109).
+ - Added new `SplitFactoryProvider` component as a replacement for the now deprecated `SplitFactory` component.
+      - Bugfixing: The new component is a revised version of `SplitFactory` that properly handles SDK side effects (i.e., factory creation and destruction) within the React component lifecycle,
+           - resolving memory leak issues in React development mode, strict mode and server-side rendering (Related to issues #11 and #109),
+           - and also ensuring that the SDK is updated if `config` or `factory` props change (Related to issues #11 and #148).
+      - Notable changes when migrating from `SplitFactory` to `SplitFactoryProvider`:
+           - `SplitFactoryProvider` utilizes the React Hooks API, requiring React 16.8.0 or later, while `SplitFactory` is compatible with React 16.3.0 or later.
+           - When using the `config` prop with `SplitFactoryProvider`, the `factory` and `client` properties in `SplitContext` and the `manager` property in `useSplitManager` results are `null` in the first render, until the context is updated when some event is emitted on the SDK main client (ready, ready from cache, timeout, or update, depending on the configuration of the `updateOn<Event>` props of the component). This differs from the previous behavior where `factory`, `client`, and `manager` were immediately available.
+           - Updating the `config` prop in `SplitFactoryProvider` reinitializes the SDK with the new configuration, while `SplitFactory` does not reinitialize the SDK. You should pass a reference to the configuration object (e.g., via a global variable, `useState`, or `useMemo`) rather than a new instance on each render, to avoid unnecessary reinitializations.
+           - Updating the `factory` prop in `SplitFactoryProvider` replaces the current SDK instance, unlike `SplitFactory` where it is ignored.
  - Updated internal code to remove a circular dependency and avoid warning messages with tools like PNPM (Related to issue #176).
  - Updated @splitsoftware/splitio package to version 10.25.1 for vulnerability fixes.
 

MIGRATION-GUIDE.md

@@ -0,0 +1,142 @@
+
+# Migrating to get React SDK v1.11.0 improvements: Replacing the deprecated `SplitFactory` and `withSplitFactory` components
+
+Starting from React SDK v1.11.0, the `SplitFactoryProvider` component is available and can replace the older `SplitFactory` and `withSplitFactory` components. The deprecated components will continue working, until they are removed in a future major release.
+
+We recommend migrating to the new `SplitFactoryProvider` component instead. This component is a revised version of `SplitFactory` that properly handles SDK side effects (i.e., factory creation and destruction) within the React component lifecycle. By migrating, you can benefit from a number of improvements:
+
+ - Resolution of memory leak issues in React development mode, strict mode, and server-side rendering.
+
+ - Updating the SDK when `config` or `factory` props change.
+
+Notable changes to consider when migrating:
+ - `SplitFactoryProvider` utilizes the React Hooks API, requiring React 16.8.0 or later, while `SplitFactory` is compatible with React 16.3.0 or later.
+
+ - When using the `config` prop with `SplitFactoryProvider`, the `factory` and `client` properties in `SplitContext` and the `manager` property in `useSplitManager` results are `null` in the first render, until the context is updated when some event is emitted on the SDK main client (ready, ready from cache, timeout, or update, depending on the configuration of the `updateOn<Event>` props of the component). This differs from the previous behavior where `factory`, `client`, and `manager` were immediately available. Nonetheless, it is not recommended to use the `client` and `factory` properties directly as better alternatives are available. For example, use the `useTrack` and `useSplitTreatments` hooks rather than the client's `track` and `getTreatments` methods.
+
+ - Updating the `config` prop in `SplitFactoryProvider` reinitializes the SDK with the new configuration, while `SplitFactory` does not reinitialize the SDK. You should pass a reference to the configuration object (e.g., via a global variable, `useState`, or `useMemo`) rather than a new instance on each render, to avoid unnecessary reinitializations.
+
+ - Updating the `factory` prop in `SplitFactoryProvider` replaces the current SDK instance, unlike `SplitFactory` where it is ignored.
+
+To migrate your existing code, replace:
+
+```javascript
+const MyApp = () => {
+  return (
+    <SplitFactory config={mySplitConfig}>
+      <MyComponent />
+    </SplitFactory>
+  );
+};
+```
+
+or
+
+```javascript
+const MyApp = withSplitFactory(mySplitConfig)(MyComponent);
+```
+
+with:
+
+```javascript
+const MyApp = () => {
+  return (
+    <SplitFactoryProvider config={mySplitConfig}>
+      <MyComponent />
+    </SplitFactoryProvider>
+  );
+};
+```
+
+and consider that `factory`, `client` and `manager` properties might be `null` until the SDK has emitted some event:
+
+```javascript
+const MyComponent = () => {
+  // factoryFromContext === factory, clientFromContext === client, and they are null until some SDK event is emitted
+  const { factory: factoryFromContext, client: clientFromContext } = useContext(SplitContext);
+  const { factory, client } = useSplitClient();
+
+  // Example to evaluate all your flags when the SDK is ready and re-evaluate on SDK_UPDATE events
+  const { manager } = useSplitManager();
+  const FEATURE_FLAG_NAMES = manager ? manager.names() : [];
+  const { treatments, isReady } = useSplitTreatments({ names: FEATURE_FLAG_NAMES, updateOnSdkUpdate: true }); // updateOnSdkReady is true by default
+
+  return isReady ?
+    treatments['feature-flag-1'].treatment === 'on' ?
+      <FeatureOn /> :
+      <FeatureOff /> :
+    <LoadingPage />
+}
+```
+
+# Migrating to get React SDK v1.10.0 improvements: Replacing the deprecated `useClient`, `useTreatments`, and `useManager` hooks
+
+Starting from React SDK v1.10.0, the `useSplitClient`, `useSplitTreatments`, and `useSplitManager` hooks are available and can replace the older `useClient`, `useTreatments`, and `useManager` hooks respectively. The deprecated hooks will continue working, until they are removed in a future major release.
+
+We recommend migrating to the new versions `useSplitClient`, `useSplitTreatments` and `useSplitManager` respectively, which provide a more flexible API:
+
+- They accept an options object as parameter, instead of a list of parameters as their deprecated counterparts. The options object can contain the same parameters as the old hooks, plus some extra optional parameters: `updateOnSdkReady`, `updateOnSdkReadyFromCache`, `updateOnSdkTimedout`, and `updateOnSdkUpdate`, which control when the hook updates the component. For example, you can set `updateOnSdkUpdate` to `true`, which is `false` by default, to update the component when an `SDK_UPDATE` event is emitted. This is useful when you want to avoid unnecessary re-renders of your components.
+
+- They return an object containing the SDK status properties. These properties are described in the ['Subscribe to events and changes' section](https://help.split.io/hc/en-us/articles/360038825091-React-SDK#subscribe-to-events-and-changes) and enable conditional rendering of components based on the SDK status, eliminating the need to access the Split context or use the client's `ready` promise or event listeners. For example, you can show a loading spinner until the SDK is ready, and use the `treatments` result to render the variants of your app once the SDK is ready.
+
+The usage of the new hooks is shown below:
+
+```js
+const { client, isReady, isReadyFromCache, hasTimedout, lastUpdate } = useSplitClient({ splitKey: userId, updateOnSdkUpdate: true });
+const { treatments, isReady, isReadyFromCache, hasTimedout, lastUpdate } = useSplitTreatments({ names: ['feature-flag-1'], updateOnSdkTimedout: false });
+const { manager, isReady, isReadyFromCache, hasTimedout, lastUpdate } = useSplitManager();
+```
+
+
+
+To migrate your existing code, replace:
+
+```javascript
+const client = useClient(optionalSplitKey, optionalTrafficType, optionalAttributes);
+const treatments = useTreatments(featureFlagNames, optionalAttributes, optionalSplitKey);
+const manager = useManager();
+```
+
+with:
+
+```javascript
+const { client } = useSplitClient({ splitKey: optionalSplitKey, trafficType: optionalTrafficType, attributes: optionalAttributes });
+const { treatments } = useSplitTreatments({ names: featureFlagNames, attributes: optionalAttributes, splitKey: optionalSplitKey });
+const { manager } = useSplitManager();
+```
+
+and use the status properties to conditionally render your components. For example, use the following code:
+
+```javascript
+const MyComponent = ({ userId }) => {
+
+  const { treatments, isReady } = useSplitTreatments({ names: [FEATURE_X], splitKey: userId })
+
+  return isReady ?
+    treatments[FEATURE_X].treatment === 'on' ?
+      <FeatureOn /> :
+      <FeatureOff /> :
+    <LoadingPage />
+}
+```
+
+instead of:
+
+```javascript
+const MyComponent = ({ userId }) => {
+
+  const [sdkIsReady, setSdkIsReady] = useState(false);
+  const client = useClient(userId);
+  const treatments = useTreatments([FEATURE_X], undefined, userId);
+
+  useEffect(() => {
+    if (client) client.ready().then(() => setSdkIsReady(true));
+  }, [client]);
+
+  return isReady ?
+    treatments[FEATURE_X].treatment === 'on' ?
+      <FeatureOn /> :
+      <FeatureOff /> :
+    <LoadingPage />
+}
+```

package.json

@@ -8,6 +8,7 @@
   "files": [
     "README.md",
     "CONTRIBUTORS-GUIDE.md",
+    "MIGRATION-GUIDE.md",
     "LICENSE",
     "CHANGES.txt",
     "src",

src/SplitFactory.tsx

@@ -14,10 +14,19 @@ import { DEFAULT_UPDATE_OPTIONS } from './useSplitClient';
  * The underlying SDK factory and client is set on the constructor, and cannot be changed during the component lifecycle,
  * even if the component is updated with a different config or factory prop.
  *
- * @deprecated Replace with the new `SplitFactoryProvider` component.
- * `SplitFactoryProvider` is a drop-in replacement that properly handles side effects (factory creation and destruction) within the React component lifecycle, avoiding issues with factory recreation and memory leaks.
- * Note: There is a subtle breaking change in `SplitFactoryProvider`. When using the `config` prop, `factory` and `client` properties in the context are `null` in the first render, until the context is updated when some event is emitted on
- * the SDK main client (ready, ready from cache, timeout or update depending on the configuration of the `updateOnXXX` props of the component). This differs from the previous behavior where `factory` and `client` were immediately available.
+ * @deprecated `SplitFactory` will be removed in a future major release. We recommend replacing it with the new `SplitFactoryProvider` component.
+ *
+ * `SplitFactoryProvider` is a revised version of `SplitFactory` that properly handles SDK side effects (i.e., factory creation and destruction) within the React component lifecycle,
+ * resolving memory leak issues in React development mode, strict mode and server-side rendering, and also ensuring that the SDK is updated if `config` or `factory` props change.
+ *
+ * Notable changes to consider when migrating:
+ * - `SplitFactoryProvider` utilizes the React Hooks API, requiring React 16.8.0 or later, while `SplitFactory` is compatible with React 16.3.0 or later.
+ * - When using the `config` prop with `SplitFactoryProvider`, the `factory` and `client` properties in `SplitContext` and the `manager` property in `useSplitManager` results
+ * are `null` in the first render, until the context is updated when some event is emitted on the SDK main client (ready, ready from cache, timeout, or update, depending on
+ * the configuration of the `updateOn<Event>` props of the component). This differs from the previous behavior where `factory`, `client`, and `manager` were immediately available.
+ * - Updating the `config` prop in `SplitFactoryProvider` reinitializes the SDK with the new configuration, while `SplitFactory` does not reinitialize the SDK. You should pass a
+ * reference to the configuration object (e.g., via a global variable, `useState`, or `useMemo`) rather than a new instance on each render, to avoid unnecessary reinitializations.
+ * - Updating the `factory` prop in `SplitFactoryProvider` replaces the current SDK instance, unlike `SplitFactory` where it is ignored.
  *
  * @see {@link https://help.split.io/hc/en-us/articles/360038825091-React-SDK#2-instantiate-the-sdk-and-create-a-new-split-client}
  */

src/SplitFactoryProvider.tsx

@@ -3,16 +3,16 @@ import React from 'react';
 import { SplitComponent } from './SplitClient';
 import { ISplitFactoryProps } from './types';
 import { WARN_SF_CONFIG_AND_FACTORY } from './constants';
-import { getSplitFactory, destroySplitFactory, IFactoryWithClients, getSplitClient, getStatus, __factories } from './utils';
+import { getSplitFactory, destroySplitFactory, IFactoryWithClients, getSplitClient, getStatus } from './utils';
 import { DEFAULT_UPDATE_OPTIONS } from './useSplitClient';
 
 /**
  * SplitFactoryProvider will initialize the Split SDK and its main client when `config` prop is provided or updated, listen for its events in order to update the Split Context,
  * and automatically destroy the SDK (shutdown and release resources) when it is unmounted or `config` prop updated. SplitFactoryProvider must wrap other library components and
  * functions since they access the Split Context and its properties (factory, client, isReady, etc).
  *
- * NOTE: Either pass a factory instance or a config object. If both are passed, the config object will be ignored.
- * Pass the same reference to the config or factory object rather than a new instance on each render, to avoid unnecessary props changes and SDK reinitializations.
+ * NOTE: Either pass a `factory` instance or a `config` object as props. If both props are passed, the `config` prop will be ignored.
+ * Pass the same reference to the `config` or `factory` object rather than a new instance on each render, to avoid unnecessary props changes and SDK reinitializations.
  *
  * @see {@link https://help.split.io/hc/en-us/articles/360038825091-React-SDK#2-instantiate-the-sdk-and-create-a-new-split-client}
  */
@@ -44,7 +44,7 @@ export function SplitFactoryProvider(props: ISplitFactoryProps) {
 
   // Effect to subscribe/unsubscribe to events
   React.useEffect(() => {
-    const factory = config && __factories.get(config);
+    const factory = config && getSplitFactory(config);
     if (factory) {
       const client = getSplitClient(factory);
       const status = getStatus(client);

src/__tests__/testUtils/utils.tsx

@@ -110,7 +110,7 @@ export function testAttributesBinding(Component: React.FunctionComponent<TestCom
   // With splitKey undefined, mainClient and client refer to the same client instance.
   wrapper = render(<Component splitKey={undefined} attributesFactory={{ at1: 'at1' }} attributesClient={{ at2: 'at2' }} testSwitch={attributesBindingSwitch} factory={factory} />);
 
-  wrapper.rerender(<Component splitKey={undefined}  attributesFactory={undefined} attributesClient={{ at3: 'at3' }} testSwitch={attributesBindingSwitch} factory={factory} />);
-  wrapper.rerender(<Component splitKey={undefined}  attributesFactory={{ at4: 'at4' }} attributesClient={undefined} testSwitch={attributesBindingSwitch} factory={factory} />);
-  wrapper.rerender(<Component splitKey={undefined}  attributesFactory={undefined} attributesClient={undefined} testSwitch={attributesBindingSwitch} factory={factory} />);
+  wrapper.rerender(<Component splitKey={undefined} attributesFactory={undefined} attributesClient={{ at3: 'at3' }} testSwitch={attributesBindingSwitch} factory={factory} />);
+  wrapper.rerender(<Component splitKey={undefined} attributesFactory={{ at4: 'at4' }} attributesClient={undefined} testSwitch={attributesBindingSwitch} factory={factory} />);
+  wrapper.rerender(<Component splitKey={undefined} attributesFactory={undefined} attributesClient={undefined} testSwitch={attributesBindingSwitch} factory={factory} />);
 }

src/withSplitFactory.tsx

@@ -10,10 +10,19 @@ import { SplitFactory } from './SplitFactory';
  * @param config Config object used to instantiate a Split factory
  * @param factory Split factory instance to use instead of creating a new one with the config object.
  *
- * @deprecated Use `SplitFactoryProvider` instead.
- * `SplitFactoryProvider` is a drop-in replacement of `SplitFactory` that properly handles side effects (factory creation and destruction) within the React component lifecycle, avoiding issues with factory recreation and memory leaks.
- * Note: There is a subtle breaking change in `SplitFactoryProvider`. When using the `config` prop, `factory` and `client` properties in the context are `null` in the first render, until the context is updated when some event is emitted on
- * the SDK main client (ready, ready from cache, timeout or update depending on the configuration of the `updateOnXXX` props of the component). This differs from the previous behavior where `factory` and `client` were immediately available.
+ * @deprecated `withSplitFactory` will be removed in a future major release. We recommend replacing it with the new `SplitFactoryProvider` component.
+ *
+ * `SplitFactoryProvider` is a revised version of `SplitFactory` that properly handles SDK side effects (i.e., factory creation and destruction) within the React component lifecycle,
+ * resolving memory leak issues in React development mode, strict mode and server-side rendering, and also ensuring that the SDK is updated if `config` or `factory` props change.
+ *
+ * Notable changes to consider when migrating:
+ * - `SplitFactoryProvider` utilizes the React Hooks API, requiring React 16.8.0 or later, while `SplitFactory` is compatible with React 16.3.0 or later.
+ * - When using the `config` prop with `SplitFactoryProvider`, the `factory` and `client` properties in `SplitContext` and the `manager` property in `useSplitManager` results
+ * are `null` in the first render, until the context is updated when some event is emitted on the SDK main client (ready, ready from cache, timeout, or update, depending on
+ * the configuration of the `updateOn<Event>` props of the component). This differs from the previous behavior where `factory`, `client`, and `manager` were immediately available.
+ * - Updating the `config` prop in `SplitFactoryProvider` reinitializes the SDK with the new configuration, while `SplitFactory` does not reinitialize the SDK. You should pass a
+ * reference to the configuration object (e.g., via a global variable, `useState`, or `useMemo`) rather than a new instance on each render, to avoid unnecessary reinitializations.
+ * - Updating the `factory` prop in `SplitFactoryProvider` replaces the current SDK instance, unlike `SplitFactory` where it is ignored.
  */
 export function withSplitFactory(config?: SplitIO.IBrowserSettings, factory?: SplitIO.IBrowserSDK, attributes?: SplitIO.Attributes) {