Migrating to @statsig/js-client

The updated SDK retains the architecture and most APIs. However, some modifications address common pitfalls, resolve existing issues, and streamline the SDK logic, resulting in some breaking changes.

Breaking changes

• The SDK now offers both a synchronous and asynchronous initialization and updateUser methods.
• The "getConfig" method has changed to "getDynamicConfig"
• When Bootstrapping, you now pass the hash parameter as 'djb2'
• The top-level static instance has moved to a static method, StatsigClient.instance()
• Overrides have moved into their own package: js-local-overrides
• Parameters for GDPR compliance have changed and been centralized
• The method to retrieve a stableID has changed
• The structure of cached values has changed, with implications on first-run experience
• Several StatsigOptions have changed
• Statsig has deprecated the manual exposure logging methods (getExperimentWithExposureLoggingDisabled, checkGateWithExposureLoggingDisabled). The checkGate and getExperiment methods now support a second argument that disables exposure logging.

Initialization

Previously, the SDK used a single method for initialization. Because waiting for a method call during app startup can be impractical, the new SDK provides two distinct initialization approaches: one synchronous and one asynchronous.

Synchronous initialization uses cache (if available) and returns immediately. The SDK then fetches data for subsequent sessions in the background.

Asynchronous initialization is awaitable and ensures the SDK fetches and uses the most current data.

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

getConfig is now getDynamicConfig

Update your getConfig call sites to call the new method, getDynamicConfig. In addition, DynamicConfig and Layer are no longer classes but JavaScript objects. Convenience get methods remain unchanged.

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

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

Bootstrapping

When bootstrapping from a server SDK, update how the server SDK generates values. The new js-client SDK uses a djb2 hash instead of sha256 for hashing gate/experiment names. 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, benefiting package size and speed. This doesn't change any bucketing logic, only the obfuscation method used for the payload.

For example, if you're bootstrapping from a nodejs app, you need to:

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

Updating the user

Similar to initialization, the updateUser method now supports both synchronous and asynchronous approaches, working the same way as the corresponding initialization approach.

import Statsig from "statsig-js";

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

await Statsig.updateUser(user);

Static instance

In the previous SDK version, there was a top-level static interface for using Statsig. To improve support for multiple instances, a static method that retrieves an instance now replaces it.

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...
}

Overrides

Previously, the client had top-level methods for managing overrides for gates/configs/experiments/layers. Statsig removed this functionality from the main SDK and moved it to its own package. You can implement your own overrides, or use @statsig/js-local-overrides and set it 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 consent management use cases, you must suspend cache and network usage until the user grants specific permissions. Previously, the approach was fragmented. The new SDK consolidates these settings for consistency and ease of implementation.

// 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;

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. The new key is a function of the SDK key used to initialize the SDK, which allows multiple SDK instances to coexist on a single page without overlapping cached data. To keep the existing stableID, 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 migration path from the old format to the new format. To pre-populate cached values, run the new SDK without issuing checks against it for some time before switching to use it for all checks.

Legacy StatsigOptions

The options for parameterizing SDK initialization have changed. In some cases, Statsig removed or moved the underlying features, and you can enable or disable them in a different way. In other cases, there is a new API for managing them. The following maps old options to their equivalents in the new SDK.

disableErrorLogging

This feature doesn't 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 StatsigOptions.disableLogging

disableCurrentPageLogging

This is now StatsigOptions.includeCurrentPageUrlWithEvents

disableLocalStorage

This is now StatsigOptions.disableStorage

localMode

This is now StatsigOptions.networkConfig.preventAllNetworkTraffic

loggingIntervalMillis

This is now StatsigOptions.loggingIntervalMs

loggingBufferMaxSize

Unchanged

environment

Unchanged

disableNetworkKeepalive

Statsig completely removed this. Control network requests with StatsigOptions.networkConfig.networkOverrideFunc.

api

This is now 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

Statsig completely removed this. Control network requests with StatsigOptions.networkConfig.networkOverrideFunc.

ignoreWindowUndefined

No longer applicable

disableHashing

This is now StatsigOptions.networkConfig.initializeHashAlgorithm

logLevel

Statsig hasn't changed this, but the enum values are no longer UPPERCASED.

logger

Not yet supported

evaluationCallback

Replaced by the usage of StatsigClientEventEmitter