Skip to main content

Migrating to @statsig/js-client

DEPRECATED

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

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, resulting in some breaking changes.

Breaking Changes​

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.

...

You can read more about StatsigClient initialization here.

getConfig is now getDynamicConfig​

Make sure you update your getConfig call sites to call the new method, getDynamicConfig. In addition, DynamicConfig and Layer are no longer classes, but javascript objects. There are still convenience get methods, which should remain unchanged.

// old
statsig.getConfig('config_name');

// new
statsigClient.getDynamicConfig('config_name');

Bootstrapping​

If you are using a server SDK to bootstrap your js/react app, you will need to make some updates to how your server SDK generates values. One of the optimizations we made with this new js-client SDK was to remove the sha256 library for hashing gate/experiment names. Instead, we use a djb2 hash. 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. This does not change any of the bucketing logic, only the obfuscation method used for the payload.

For example, if you are bootstrapping from a nodejs app, you will need to do:

statsig.getClientInitializeResponse(
  user,
  '[client-key]',
  {
    hash: 'djb2',
  },
);

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.

...

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.

...

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

Overrides​

Previously, the client had top level methods for managing overrides for gates/configs/experiments/layers, etc. Now, this has been removed from the main SDK and is in its own package. You can implement your own overrides, or use @statsig/js-local-overrides and plug it in as the local override adapter in StatsigOptions

import { StatsigClient } from '@statsig/js-client';
import { LocalOverrideAdapter } from '@statsig/js-local-overrides';

const overrideAdapter = new LocalOverrideAdapter();
overrideAdapter.overrideGate('gate_a', false);
overrideAdapter.overrideGate('gate_b', true);

const client = new StatsigClient(
  DEMO_CLIENT_KEY,
  { userID: 'a-user' },
  {
    overrideAdapter,
  },
);

Full example here:

https://github.com/statsig-io/js-client-monorepo/blob/0e7201635f71e77633de04c4c19c1006030a3a81/samples/next-js/src/app/override-adapter-example/OverrideAdapterExample.tsx#L14

GDPR​

In certain use cases (consent management), 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.

...

stableID and getStableID​

statsig.getStableID() no longer exists. You can get the stableID like this: myStatsigClient.getContext().stableID

The key for the stableID in local storage has changed. It is now a function of the SDK key used to initialize the sdk, which enables multiple instances of the SDK to coexist on a single page and not overlap with cached data. If you wish to keep the existing stableID, you should access it in local storage from the old key STATSIG_LOCAL_STORAGE_STABLE_ID, and set it in customIDs to override the stableID.

Cached Values​

The structure of cached values has changed significantly, and there is no supported way to migrate from the old cached values to the new format. If you wish to pre-populate cached values, we recommend running the new SDK without issuing checks against it for some time before swapping to use it for all checks.

Legacy StatsigOptions​

The options to parameterize initialization of the SDK have changed. In some cases, the underlying features were removed or moved and can be enabled/disabled in a different way. In other scenarios, there is a new API for managing them. The following is a mapping of old options to their equivalents in the new sdk.

disableErrorLogging​

This feature does not exist in the new Javascript SDK, so there is no option to disable it.

disableAutoMetricsLogging​

Moved to optional package @statsig/web-analytics

disableAllLogging​

This is now referred to as StatsigOptions.disableLogging

disableCurrentPageLogging​

This is now referred to as StatsigOptions.includeCurrentPageUrlWithEvents

disableLocalStorage​

This is now referred to as StatsigOptions.disableStorage

localMode​

This is now referred to as StatsigOptions.networkConfig.preventAllNetworkTraffic

loggingIntervalMillis​

This is now referred to as StatsigOptions.loggingIntervalMs

loggingBufferMaxSize​

Unchanged

environment​

Unchanged

disableNetworkKeepalive​

This is has been completely removed. Network requests can be controlled with StatsigOptions.networkConfig.networkOverrideFunc

api​

This is now referred to as StatsigOptions.networkConfig.api

overrideStableID​

stableID is now just part of StatsigUser.customIDs. This brings it inline with Statsig server SDKs and helps avoid mis-configuration between client and server

initTimeoutMs​

Timeouts now live as part of the async call.

eg: myStatsigClient.initializeAsync(1000); // 1 sec timeout

initializeValues​

Replaced by the usage of StatsigEvaluationsDataAdapter

eventLoggingApi​

Replaced by StatsigOptions.networkConfig.logEventUrl

prefetchUsers​

Replaced by the usage of StatsigEvaluationsDataAdapter

initCompletionCallback​

Replaced by the usage of StatsigClientEventEmitter

statsigClient.on('values_updated', function(evt) {
  if(evt.status && evt.status === 'Ready') { /* client has initialized */ } 
});

updateUserCompletionCallback​

Replaced by the usage of StatsigClientEventEmitter

fetchMode​

Replaced by the usage of StatsigEvaluationsDataAdapter

disableDiagnosticsLogging​

There currently is no diagnostics logging in the new SDK

initRequestRetries​

This is has been completely removed. Network requests can be controlled with StatsigOptions.networkConfig.networkOverrideFunc

ignoreWindowUndefined​

No longer applicable

disableHashing​

This is now referred to as StatsigOptions.networkConfig.initializeHashAlgorithm

logLevel​

This has not been changed, but the enum values are no longer UPPERCASED.

logger​

Not yet supported

evaluationCallback​

Replaced by the usage of StatsigClientEventEmitter