Migrating From statsig-js

The architecture and majority of the APIs in the updated SDK have been retained; however, modifications have been made to address common pitfalls, resolve existing issues, and streamline the SDK logic.

Below is a list of identified breaking changes that will require manual refactoring:

Initialization

Previously, the SDK employed a single method for initialization. However, we have recognized that waiting for a method call during app startup can be impractical. Consequently, we have introduced two distinct initialization approaches: one synchronous and one asynchronous.

Synchronous initialization will leverage cache (if available), returning immediately. Data for subsequent sessions will then be fetched in the background.

Asynchronous initialization, on the other hand, is awaitable and ensures that the most current data is fetched and used.

statsig-js (Legacy)

import Statsig from "statsig-js";

// initialize returns a promise which always resolves
await Statsig.initialize(
  "client-sdk-key",
  { userID: "some_user_id" },
  { environment: { tier: "staging" } } // optional, pass options here if needed
);

New

...

You can read more about StatsigClient initialization here.

Updating the User

Similar to initialization, the updateUser method now supports both synchronous and asynchronous approaches. Each method functions in the same manner as the initialization process.

statsig-js (Legacy)

import Statsig from "statsig-js";

const user = { userID: "a-user" };

await Statsig.updateUser(user);

New

...

Static Instance

In the previous SDK version, there was a top-level static interface for using Statsig. To enhance support for multiple instances, we have replaced this with a static method that retrieves an instance.

statsig-js (Legacy)

import Statsig from "statsig-js";

await Statsig.initialize(YOUR_CLIENT_KEY, { userID: 'a-user' });

// then later, at some other location in your code base
if (Statsig.checkGate('a_gate')) { 
  // do something...
}

New

...

You can read more about StatsigClient multi-instance support here.

GDPR

In certain use cases, it is necessary to suspend cache and network usage until the user grants specific permissions. Previously, the method for achieving this was somewhat fragmented. In the new SDK, these functionalities have been consolidated for improved coherence and ease of implementation.

statsig-js (Legacy)

// start the SDK without storage or logging
Statsig.initialize(
  'client-key',
  { userID: 'a_user' },
  { disableAllLogging: true, disableLocalStorage: true },
);

// then, once permission was granted
Statsig.shutdown();
Statsig.initialize(
  'client-key',
  { userID: 'a_user' },
  { disableAllLogging: false, disableLocalStorage: false },
);

// or, by manually flipping the related flags
Statsig.reenableAllLogging();
StatsigLocalStorage.disabled = false;

New

...