Migrating to @statsig/js-client

The architecture and most APIs in the updated SDK have been retained. 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'll now have to 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
• Manual exposure logging methods (getExperimentWithExposureLoggingDisabled, checkGateWithExposureLoggingDisabled)have been deprecated. The checkGate and getExperiment methods now support a second argument to suppress exposure logging as shown here.

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. Data for subsequent sessions is then fetched in the background.

Asynchronous initialization is awaitable and ensures the most current data is fetched and used.

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, speed, and payload size. This doesn't change any 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, 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, this has been replaced with a static method that retrieves an instance.

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. This functionality has been removed from the main SDK and moved to 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 consent management use cases, suspending cache and network usage until the user grants specific permissions is necessary. Previously, the approach was fragmented. In the new SDK, these settings are consolidated 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, the underlying features were removed or moved and can be enabled or disabled 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 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 has been completely removed. Control network requests 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 has been completely removed. Control network requests 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