React Web SDK 2.x to 3.0 migration guide

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. To upgrade to the latest Relay Proxy version, visit Relay Proxy releases on GitHub.

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 and dependencies for the v3 SDK

The minimum React version for the LaunchDarkly React Web v3 SDK is 16.3.3. If you want to use hooks, the minimum version is 16.8. LaunchDarkly no longer supports earlier React Web SDK versions, as stated in the End of Life policy.

The React Web SDK version 3.0.0 uses optional chaining. If you encounter an error related to optional chaining during transpiling, bundling, or running tests, updating to version 3.0.2 should resolve the error.

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 Web 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,
})
COPY

Here's how with withLDProvider:

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

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

To learn more, read the unit tests migration guide.

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.