React Native SDK 9.x to 10.0 migration guide
Read time: 6 minutes
Last edited: May 01, 2024
Overview
This topic explains the changes in the React Native SDK version 10 release and how to migrate to that version.
Version 10.0 includes the following breaking changes:
- Version 10 of the React Native SDK has been rewritten in pure JavaScript and is compatible with Expo 49 and 50. It is compatible with React Native 0.72 and 0.73.
- The
LDClient
has been renamedReactNativeLDClient
, and several of the methods have changed. To learn more, read Understanding changes to client initialization and Understanding changes to the client, below. - The
LDConfig
configuration object has been renamed toLDOptions
, and several of the configuration options have changed. To learn more, read Understanding changes to configuration options, below. - The
LDContext
has been updated: anonymous contexts now require a context key, which should be set to an empty string. To learn more, read Understanding changes to contexts, below.
Understanding changes to client initialization
There are several breaking changes to the client initialization.
Version 10 of the SDK provides a new ReactNativeLDClient
class, which you can instantiate and pass to LDProvider
.
When you instantiate the ReactNativeLDClient
class, you must pass in your mobile key and indicate whether to collect environment attributes. These are no longer set as part of the configuration.
LDProvider
uses the React context API to store and pass data to child components through hooks. It requires the client.
In version 10 of the SDK, you do not specify a context when you initialize the client. Instead, you must provide the context in an identify()
call, for example on application mount. End users will receive fallback values until you specify a context by calling identify()
.
The following example shows the simplest way to create a shared instance of ReactNativeLDClient
, and identify a context:
const client = new ReactNativeLDClient('mobile-key-123abc', AutoEnvAttributes.Enabled, options);const context = { kind: 'user', key: 'user-key-123abc' }const App = () => {// call identify on App mount or later in some other componentuseEffect(() => {client.identify(context).catch((e: any) => console.log(e));}, []);return (<LDProvider client={client}>/* your application code here */<YourComponent /></LDProvider>);};export default App;
In version 10 of the SDK, you are not required to specify a context when you initialize ReactNativeLDClient
. If you do not specify a context initially, you must call identify()
manually to get flags at a later time. End users will receive fallback values until you do specify a context by calling identify()
.
To learn more, read Get started in the React Native SDK reference.
Understanding changes to the client
There are several breaking changes to the client.
In version 10.0 of the SDK, the LDClient
has been renamed ReactNativeLDClient
. The following ReactNativeLDClient
methods have changed:
- The
allFlags
method now no longer accepts any arguments and returnsLDFlagSet
directly, rather than returning a promise. If flags cannot be evaluated it returns an empty object. To learn more, read Getting all flags. - The
*Variation
methods now return the flag value directly, rather than returning a promise. Additionally, there are now corresponding hooks for each of the*Variation
methods. For example, you can use the hookuseBoolVariation()
instead ofclient.boolVariation()
. To learn more, read Evaluating flags. - The
*VariationDetail
methods now return evaluation details directly, rather than returning a promise. Additionally, there are now corresponding hooks for each of the*Variation
methods. For example, you can use the hookuseBoolVariationDetail()
instead ofclient.boolVariationDetail()
. To learn more, read Flag evaluation reasons. - The
flush
method now returns a promise that resolves to an object containing an error, if there is one, and a boolean result. To learn more, read Flushing events. - The
getConnectionMode
method signature has changed. It returnsConnectionMode
directly, rather than returning a promise. To learn more, readgetConnectionMode
.
The following new client methods have been added:
- The
getContext
method has been added. It returns the current context ifidentify
has been called. To learn more, readgetContext
. - The
on
andoff
methods, used for registering and unregistering event listeners, have been added. Theon
method supports the following event names:error
,change
. To learn more, read Subscribing to flag changes. - The
setConnectionMode
method has been added. It sets the SDK connection mode. To learn more, readsetConnectionMode
. - The
variation
andvariationDetail
methods have been added. These are untyped methods you can use to determine the variation of a feature flag. However, we recommend using strongly typed variation methods which perform type checks and handle type errors. To learn more, read Evaluating flags and Flag evaluation reasons.
The following client methods have been removed:
configure
: Instead, use theReactNativeLDClient
constructor to create a new client instance. Then callidentify
.getLastFailedConnection
getLastFailure
getLastSuccessfulConnection
getVersion
isInitialized
isOffline
registerAllFlagsListener
registerCurrentConnectionModeListener
registerFeatureFlagListener
setOffline
setOnline
unregisterAllFlagsListener
unregisterCurrentConnectionModeListener
unregisterFeatureFlagListener
To learn more, read the release notes in GitHub.
Understanding changes to configuration options
There are several breaking changes to the configuration options.
In version 10.0 of the SDK, the following configuration options have changed:
- The
LDConfig
object is now calledLDOptions
. To learn more, read Configuration. - The
application
option is now calledapplicationInfo
. If you have enabled the collection of environment attributes, theld_application
context will only be returned if you setapplicationInfo
. To learn more, read Application metadata configuration. - The
debugMode
option is now calleddebug
. - The
diagnosticRecordingInterval
is now specified in seconds, not milliseconds. - The
evaluationReasons
option is now calledwithReasons
. To learn more, read Flag evaluation reasons. - The
eventsCapacity
is now calledcapacity
. - The
flushInterval
is now specified in seconds, not milliseconds and defaults to 2 seconds. - The
streamUrl
,pollUrl
, andeventsUrl
configuration options are now calledstreamUri
,baseUri
, andeventsUri
, respectively. To learn more, read Service endpoint configuration.
In version 10.0 of the SDK, the following configuration options have been added:
initialConnectionMode
: Sets the mode to use for connections when the SDK is initialized. To learn more, readinitialConnectionMode
.logger
: This is an object that will perform logging for the client. In the default configuration, the SDK sends output to the console, with a default log level ofinfo
. To learn more, read Logging.sendEvents
: Whether to send analytics events back to LaunchDarkly. By default, this is true.streamInitialReconnectDelay
: Sets the initial reconnect delay for the streaming connection, in seconds. The default value is 1. To learn more, readstreamInitialReconnectDelay
.
In version 10.0 of the SDK, the following configuration options have been removed:
backgroundPollingInterval
connectionTimeout
disableBackgroundUpdating
enableAutoEnvAttributes
: Specify this as the second argument when constructing the client.maxCachedContexts
mobileKey
: In version 10, you pass the mobile key in during client initialization. You can no longer set it as a configuration option. To learn more, read Understanding changes to client initialization, above.offline
: UsesetConnectionMode
.pollingInterval
pollUrl
secondaryMobileKeys
stream
useReport
To learn more, read the release notes in GitHub.
Understanding changes to contexts
In version 10 of the SDK, you must include the key
attribute when building the context.
If the context is anonymous, you should set the key
to an empty string. The SDK will automatically set the key to a LaunchDarkly-specific, device-unique string that is consistent between app restarts and device reboots.
The SDK gives a usage error if you omit the key
attribute. It also gives a usage error if you set the key to an empty string and do not mark the context as anonymous.
Here's how:
// This device context is anonymousconst deviceContext = {// The key attribute is required and should be empty// The SDK will automatically generate a unique, stable keykey: '',kind: 'device',deviceId: '12345',anonymous: true}
In versions 7 through 9 of the SDK, you could omit the context key when building an anonymous context, and the client would automatically set it to a LaunchDarkly-specific, device-unique string that is consistent between app restarts and device reboots.
To learn more, read Anonymous contexts and users.