Migrating to @statsig/react-bindings

DEPRECATED

Migrate soon! Official support for statsig-react ends Jan 31, 2025.

note

Also refer to our migration from js-client guide, which lists other impacts on statsig-react installations.

Breaking Changes:

• Our initialization pattern has changed, along with waitForInitialization and initializeComponent
• Bootstrapping has changed, now requiring a new hashing parameter: Bootstrapping the StatsigClient

Initialize

In the old statsig-react package, all values needed to be given to the StatsigProvider, which internally would setup the Statsig client instance. This approach lead to issues in managing state between the Statsig client and the StatsigProvider, making it fragile and likely to break if you ever tried using the Statsig client directly.

The new approach is to run everything through the Statsig client instance, and just pass that to the StatsigProvider.

statsig-react (Legacy)

import { StatsigProvider } from "statsig-react";

function App() {
  return (
    <StatsigProvider
      sdkKey="<STATSIG_CLIENT_SDK_KEY>"
      user={{ userID: "a-user" }}
      waitForInitialization={true}
      // StatsigOptions (Not Required)
      options={{
        environment: { tier: "staging" },
      }}
    >
      <div className="App">{/* Rest of App ... */}</div>
    </StatsigProvider>
  );
}

New

...

waitForInitialization and initializingComponent

In the older versions of the StatsigProvider, it was possible to set the waitForInitialization to block children from rendering until after the latest values were fetched from Statsig and if a initializeComponent was set, this was displayed while the latest values were fetched.

It was also possible to set waitForInitialization to false, meaning the StatsigProvider would render immediately, before values were ready. This was not recommended as it meant values could change between checks, resulting in unexpected layout changes.

Where did waitForInitialization go?

In the newer StatsigProvider this is no longer an option as we want to prevent developers from unintentionally allowing values to change mid-session. It is still possible to get the same behavior as setting waitForInitialization to false, but we recommend against it.

Read the Initialization Strategies guide to learn how to replicate the waitForInitialization=false behavior, as well as the recommended approaches to synchronous initialization.

Bootstrapping the StatsigClient

If you are using a Statsig Server SDK to bootstrap the Statsig Client used by your React app, you may need to make some updates to how your server SDK generates values. One of the optimizations we made with the @statsig/js-client SDK was to remove the sha256 library for hashing gate/experiment names. Instead, we use a djb2 hash. This does not change any of the bucketing logic, only the obfuscation method used for the payload.

By default, all server SDKs generate sha256 hashes of gate/experiment names in the getClientInitializeResponse method. You will need to set the hash algorithm parameter to that method call to "djb2" instead in order to bootstrap this new client SDK. One of the benefits to this hashing algorithm is it will make the entire payload smaller as well, so its a net win on package size, speed, and payload size for the SDK.

For example, if you are bootstrapping from the Statsig Node SDK, you will need to do:

statsig.getClientInitializeResponse(
  user,
  '[client-key]',
  {
    hash: 'djb2', // <- New Hashing Algorithm
  },
);

Updating the User

statsig-react (Legacy)

import { useContext, useState } from "react";
import { StatsigUser, StatsigProvider, StatsigContext } from "statsig-react";

function UpdateUserButton() {
  const { updateUser } = useContext(StatsigContext);

  return <button onClick={() => updateUser({ userID: "b-user" })}>Update</button>
}

function App() {
  const [user, setUser] = useState<StatsigUser>({ userID: "a-user" });

  return (
    <StatsigProvider
      sdkKey="<STATSIG_CLIENT_SDK_KEY>"
      user={user}
      setUser={setUser}
    >
      <UpdateUserButton />
    </StatsigProvider>
  );
}

New

...