React Native SDK 9.x to 10.0 migration guide

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 renamed ReactNativeLDClient, 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 to LDOptions, 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 component
  useEffect(() => {
    client.identify(context).catch((e: any) => console.log(e));
  }, []);
  return (
    <LDProvider client={client}>
      /* your application code here */
      <YourComponent />
    </LDProvider>
  );
};
export default App;
COPY

The identify() method returns a promise that can be awaited:

// This example waits for the context to be identified,
// either resolved from cache or the network
await client.identify(context);
COPY

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 returns LDFlagSet 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 hook useBoolVariation() instead of client.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 hook useBoolVariationDetail() instead of client.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 returns ConnectionMode directly, rather than returning a promise. To learn more, read getConnectionMode.

The following new client methods have been added:

• The getContext method has been added. It returns the current context if identify has been called. To learn more, read getContext.
• The on and off methods, used for registering and unregistering event listeners, have been added. The on 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, read setConnectionMode.
• The variation and variationDetail 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 the ReactNativeLDClient constructor to create a new client instance. Then call identify.
• 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 called LDOptions. To learn more, read Configuration.
• The application option is now called applicationInfo. If you have enabled the collection of environment attributes, the ld_application context will only be returned if you set applicationInfo. To learn more, read Application metadata configuration.
• The debugMode option is now called debug.
• The diagnosticRecordingInterval is now specified in seconds, not milliseconds.
• The evaluationReasons option is now called withReasons. To learn more, read Flag evaluation reasons.
• The eventsCapacity is now called capacity.
• The flushInterval is now specified in seconds, not milliseconds and defaults to 2 seconds.
• The streamUrl, pollUrl, and eventsUrl configuration options are now called streamUri, baseUri, and eventsUri, 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, read initialConnectionMode.
• 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 of info. 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, read streamInitialReconnectDelay.

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: Use setConnectionMode.
• 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 anonymous
const deviceContext = {
  // The key attribute is required and should be empty
  // The SDK will automatically generate a unique, stable key
  key: '',
  kind: 'device',
  deviceId: '12345',
  anonymous: true
}
COPY

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.