Migrating to @statsig/react-bindings

Breaking changes:

• The 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 had to be given to the StatsigProvider, which internally set up the Statsig client instance. This approach caused issues in managing state between the Statsig client and the StatsigProvider, making it fragile and likely to break if you used the Statsig client directly.

The new approach runs everything through the Statsig client instance and passes it to the StatsigProvider.

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>
  );
}

waitForInitialization and initializingComponent

In older versions of the StatsigProvider, you could set waitForInitialization to block children from rendering until the latest values were fetched from Statsig. When initializeComponent was set, that component was displayed while values were being fetched.

You could also set waitForInitialization to false, causing the StatsigProvider to render immediately before values were ready. This wasn't recommended because values could change between checks, resulting in unexpected layout changes.

Where did waitForInitialization go?

The newer StatsigProvider removes this option to prevent developers from unintentionally allowing values to change mid-session. You can still replicate the waitForInitialization=false behavior, but it isn't recommended.

Bootstrapping the StatsigClient

When bootstrapping the Statsig Client in your React app from a Statsig Server SDK, you may need to update how the server SDK generates values. The @statsig/js-client SDK uses a djb2 hash instead of sha256 for hashing gate/experiment names. This doesn't change any bucketing logic, only the obfuscation method used for the payload.

By default, all server SDKs generate sha256 hashes in the getClientInitializeResponse method. Set the hash algorithm parameter to "djb2" to bootstrap the new client SDK. This change also reduces the overall payload size, which benefits package size, speed, and payload size.

For example, if you bootstrap from the Statsig Node SDK:

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

Updating the User

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>
  );
}