Skip to content

Commit b930e2e

Browse files
EmilianoSanchezEmilianoSanchez
committed
Update MIGRATION-GUIDE.md
1 parent 5fd2166 commit b930e2e

File tree

2 files changed

+256
-1
lines changed

2 files changed

+256
-1
lines changed

‎CHANGES.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
- BREAKING CHANGES:
88
- Updated the default value of the `updateOnSdkUpdate` and `updateOnSdkTimedout` parameters of the `useSplitClient` and `useSplitTreatments` hooks options object to `true`, to re-render on all SDK events by default. The same applies for the equivalent props in the `[with]SplitClient` and `[with]SplitTreatments` components.
99
- Updated error handling: using the library modules without wrapping them in a `SplitFactoryProvider` component will now throw an error instead of logging it, as the modules requires the `SplitContext` to work properly.
10-
- Updated the `SplitFactoryProvider` component to not accept a child as a function (render prop), to avoid unnecessary re-renders when using the library hooks. Refer to ./MIGRATION-GUIDE.md for instructions on how to migrate the child as a function to a regular component.
10+
- Updated the `SplitFactoryProvider` component to not accept a child as a function (render prop), to avoid unnecessary re-renders when using the library hooks. Refer to ./MIGRATION-GUIDE.md for instructions on how to migrate the child as a function to a regular React element.
1111
- Removed the `core.trafficType` option from the SDK configuration object, and the `trafficType` parameter from the SDK `client()` method, `useSplitClient`, `useTrack`, `withSplitClient` and `SplitClient` component. This is because traffic types can no longer be bound to SDK clients in JavaScript SDK v11.0.0, and so the traffic type must be provided as first argument in the `track` method calls.
1212
- Removed deprecated modules: `SplitFactory` component, `useClient`, `useTreatments` and `useManager` hooks. Refer to ./MIGRATION-GUIDE.md for instructions on how to migrate to the new alternatives.
1313
- Renamed `SplitSdk` to `SplitFactory` function, which is the underlying Split SDK factory, i.e., `import { SplitFactory } from '@splitsoftware/splitio'`.

‎MIGRATION-GUIDE.md

+255
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,259 @@
11

2+
# Migrating to React SDK v2.0.0:
3+
4+
React SDK v2.0.0 has a few breaking changes that you should consider when migrating from a previous version. The main changes are:
5+
6+
- Deprecated `useClient`, `useTreatments`, and `useManager` hooks have been removed.
7+
8+
Follow [this section](#migrating-to-get-react-sdk-v1100-improvements-replacing-the-deprecated-useclient-usetreatments-and-usemanager-hooks) to migrate to the new hooks `useSplitClient`, `useSplitTreatments`, and `useSplitManager` respectively.
9+
10+
- Deprecated `SplitFactory` provider has been removed, `withSplitFactory` is deprecated, and `SplitFactoryProvider` doesn't accept `updateOn` props and a render function as children anymore.
11+
12+
To migrate your existing code to the new version of `SplitFactoryProvider`, consider the following refactor example. Replace:
13+
14+
```tsx
15+
const MyComponent = (props: ISplitContextValues) => {
16+
const { factory, client, isReady, isReadyFromCache, ... } = props;
17+
...
18+
};
19+
20+
// if using SplitFactoryProvider v1.11.0
21+
const App = () => {
22+
return (
23+
<SplitFactoryProvider config={mySplitConfig} updateOnSdkUpdate={false} attributes={DEFAULT_CLIENT_ATTRIBUTES} >
24+
{MyComponent}
25+
</SplitFactoryProvider>
26+
);
27+
};
28+
29+
// or SplitFactory
30+
const App = () => {
31+
return (
32+
<SplitFactory config={mySplitConfig} updateOnSdkUpdate={false} attributes={DEFAULT_CLIENT_ATTRIBUTES} >
33+
{MyComponent}
34+
</SplitFactory>
35+
);
36+
};
37+
38+
// or withSplitFactory
39+
const App = withSplitFactory(mySplitConfig, undefined, DEFAULT_CLIENT_ATTRIBUTES)(
40+
MyComponent, false /* updateOnSdkUpdate */
41+
);
42+
```
43+
44+
with:
45+
46+
```tsx
47+
const MyComponent = () => {
48+
const props: ISplitContextValues = useSplitClient({ updateOnSdkUpdate: false, attributes: DEFAULT_CLIENT_ATTRIBUTES });
49+
const { factory, client, isReady, isReadyFromCache, ... } = props;
50+
...
51+
};
52+
53+
const App = () => {
54+
return (
55+
<SplitFactoryProvider config={mySplitConfig} >
56+
<MyComponent />
57+
</SplitFactoryProvider>
58+
);
59+
};
60+
```
61+
62+
Notice that `MyComponent` was refactored to use the `useSplitClient` hook and is passed as a React element rather than a render function as children.
63+
The `useSplitClient` hook is called without providing an `splitKey` param, meaning that the client at the context will be used, i.e., the default client which key is set in the `core.key` property of the `mySplitConfig` object, and the `updateOn` and `attributes` props are passed as options to the hook.
64+
65+
- High-Order-Components (`withSplitClient`, `withSplitTreatments`) and components that accept a render function as child component (`SplitTreatments`, and `SplitClient`) have been deprecated and might be removed in future major releases. The deprecation is intended to simplify the API and discourage the use of old patterns (HOCs and render props) in favor of hook alternatives to take advantage of React optimizations.
66+
67+
To migrate your existing code based on `withSplitClient` or `SplitClient`, consider the following refactor using the `useSplitClient` hook. Replace:
68+
69+
```tsx
70+
const MyComponent = (props: ISplitContextValues) => {
71+
const { client, isReady, ... } = props;
72+
...
73+
};
74+
75+
const App = withSplitFactory(mySplitConfig)(
76+
withSplitClient(KEY)(
77+
MyComponent, undefined, undefined, undefined, false /* updateOnSdkReadyFromCache */
78+
)
79+
);
80+
81+
// or
82+
const App = () => {
83+
return (
84+
<SplitFactory config={mySplitConfig} >
85+
<SplitClient splitKey={KEY} updateOnSdkReadyFromCache={false} >
86+
{MyComponent}
87+
</SplitClient>
88+
</SplitFactory>
89+
)
90+
};
91+
```
92+
93+
with:
94+
95+
```tsx
96+
const MyComponent = () => {
97+
const props: ISplitContextValues = useSplitClient({ splitKey: KEY, updateOnSdkReadyFromCache: false });
98+
const { client, isReady, ... } = props;
99+
...
100+
};
101+
102+
const App = () => {
103+
return (
104+
<SplitFactoryProvider config={mySplitConfig} >
105+
<MyComponent />
106+
</SplitFactory>
107+
)
108+
};
109+
```
110+
111+
To migrate your existing code based on `withSplitTreatments` or `SplitTreatments`, consider the following refactor using the `useSplitTreatments` hook. Replace:
112+
113+
```tsx
114+
const MyComponent = (props: ISplitTreatmentsChildProps) => {
115+
const { treatments, isReady, ... } = props;
116+
...
117+
};
118+
119+
const App = withSplitFactory(mySplitConfig)(
120+
withSplitClient(KEY)(
121+
withSplitTreatments(FEATURE_FLAG_NAMES, ATTRIBUTES)(
122+
MyComponent, undefined, undefined, undefined, false /* updateOnSdkReadyFromCache */
123+
)
124+
)
125+
);
126+
127+
// or
128+
const App = () => {
129+
return (
130+
<SplitFactory config={mySplitConfig} >
131+
<SplitClient splitKey={KEY} updateOnSdkReadyFromCache={false} >
132+
<SplitTreatments names={FEATURE_FLAG_NAMES} attributes={ATTRIBUTES} >
133+
{MyComponent}
134+
</SplitTreatments>
135+
</SplitClient>
136+
</SplitFactory>
137+
)
138+
};
139+
```
140+
141+
with:
142+
143+
```tsx
144+
const MyComponent = () => {
145+
const props: ISplitTreatmentsChildProps = useSplitTreatments({ splitKey: KEY, names: FEATURE_FLAG_NAMES, attributes: ATTRIBUTES, updateOnSdkReadyFromCache: false });
146+
const { treatments, isReady, ... } = props;
147+
...
148+
};
149+
150+
const App = () => {
151+
return (
152+
<SplitFactoryProvider config={mySplitConfig} >
153+
<MyComponent />
154+
</SplitFactory>
155+
)
156+
};
157+
```
158+
159+
- Renamed `SplitSdk` function to `SplitFactory`.
160+
161+
If you are using the `SplitSdk` function to create a factory and pass it to the `SplitFactoryProvider` component, you should rename it to `SplitFactory`. For example:
162+
163+
```tsx
164+
import { SplitSdk, SplitFactoryProvider } from '@splitsoftware/splitio-react';
165+
166+
const myFactory = SplitSdk(mySplitConfig);
167+
168+
const App = () => {
169+
return (
170+
<SplitFactoryProvider factory={myFactory} >
171+
<MyComponent />
172+
</SplitFactoryProvider>
173+
);
174+
};
175+
```
176+
177+
should be refactored to:
178+
179+
```tsx
180+
import { SplitFactory, SplitFactoryProvider } from '@splitsoftware/splitio-react';
181+
182+
const myFactory = SplitFactory(mySplitConfig);
183+
184+
const App = () => {
185+
return (
186+
<SplitFactoryProvider factory={myFactory} >
187+
<MyComponent />
188+
</SplitFactoryProvider>
189+
);
190+
};
191+
```
192+
193+
- Traffic type cannot be bound to SDK clients anymore.
194+
195+
If you were passing the `trafficType` to the SDK config or the `useSplitClient` or `useTrack` hooks, you should remove it. The `trafficType` is now required to be passed as initial argument of the `track` method. For example:
196+
197+
```tsx
198+
const mySplitConfig = {
199+
core: {
200+
authorizationKey: YOUR_CLIENT_SIDE_SDK_KEY,
201+
key: USER_KEY,
202+
trafficType: 'user'
203+
}
204+
}
205+
206+
const MyComponent = () => {
207+
const track = useTrack();
208+
const accountTrack = useTrack(ACCOUNT_KEY, 'account');
209+
210+
useEffect(() => {
211+
track('my_event');
212+
accountTrack('my_event');
213+
}, []);
214+
215+
...
216+
};
217+
218+
const App = () => {
219+
return (
220+
<SplitFactoryProvider config={mySplitConfig} >
221+
<MyComponent />
222+
</SplitFactory>
223+
)
224+
};
225+
```
226+
227+
should be refactored to:
228+
229+
```tsx
230+
const mySplitConfig = {
231+
core: {
232+
authorizationKey: YOUR_CLIENT_SIDE_SDK_KEY,
233+
key: USER_KEY
234+
}
235+
}
236+
237+
const MyComponent = () => {
238+
const track = useTrack();
239+
const accountTrack = useTrack(ACCOUNT_KEY);
240+
241+
useEffect(() => {
242+
track('user', 'my_event');
243+
accountTrack('account', 'my_event');
244+
}, []);
245+
...
246+
};
247+
248+
const App = () => {
249+
return (
250+
<SplitFactoryProvider config={mySplitConfig} >
251+
<MyComponent />
252+
</SplitFactory>
253+
)
254+
};
255+
```
256+
2257
# Migrating to get React SDK v1.11.0 improvements: Replacing the deprecated `SplitFactory` and `withSplitFactory` components
3258

4259
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.

0 commit comments

Comments
 (0)