React Web SDK 2.x to 3.0 migration guide

Read time: 2 minutes

Last edited: Jan 31, 2023

Contexts are for Early Access Program customers only

A context is a generalized way of describing and referring to the people, services, machines, or other resources that encounter feature flags in your product.

Creating contexts and evaluating flags based on contexts is the primary feature in the React Web SDK 3.0 release. However, the ability to target flags or segments by context, or review context instances that have encountered flags in your application, is only available to members of LaunchDarkly's Early Access Program (EAP). To learn more or join the EAP, read Contexts.

Overview

This topic explains the changes in the React Web SDK 3.0 release and how to adapt code that uses a 2.28 version of the React Web SDK to use version 3 or later.

Version 3 includes several breaking changes. Additionally, if you use the Relay Proxy, you must update your Relay Proxy to version 7.0 before you update your SDK to version 3. To learn more, read the Relay Proxy 7.0 release notes.

Before you migrate to version 3, update to the latest 2.28 version. Some of the changes that are mandatory in 3 were originally added in a 2.28 version and made optional.

If you update to the latest 2.28 version, deprecation warnings appear in areas of your code that need to be changed for 3. You can update them at your own pace while still using 2.28, rather than migrating everything simultaneously. To learn more about updating to the latest 2.28 version, visit the SDK's GitHub repository.

Identifying supported React versions for the 3 SDK

The minimum React version for LaunchDarkly 3 SDK is 16.3.3. If you want to use hooks, the minimum version is 16.8.

LaunchDarkly no longer supports earlier React Web versions, as stated in the End of Life policy.

Understanding changes to provider configuration

Version 3 of this SDK lets you use contexts. When you migrate from version 2.x, replace the user provider configuration option with context. If you do not replace it, version 3 of the React SDK will look for the user configuration option as a fallback. This fallback may be removed in a future major release.

Here's how with asyncWithLDProvider:

const user = {
  key: "user-key-123abc",
}
const LDProvider = await asyncWithLDProvider({
  clientSideID: "client-side-id-123abc",
  user: user,
})

Here's how with withLDProvider:

const user = {
  key: "user-key-123abc",
}
export default withLDProvider({
  clientSideID: "client-side-id-123abc",
  user: user,
})(App)

If you use the jest-launchdarkly-mock package, update it to version 2.0.

Using this migration guide

The React Web client-side SDK is a wrapper of LaunchDarkly's JavaScript SDK. The updates necessary to migrate to version 3 of the JavaScript SDK are available in the JavaScript SDK migration guide.