> ## Documentation Index
> Fetch the complete documentation index at: https://statsig-4b2ff144-serverless-cloudflare.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating to @statsig/js-client

> Learn how to migrate from the legacy statsig-js SDK to the new @statsig/js-client SDK

<Warning>
  ### Deprecated

  Migrate soon! Official support for statsig-js ended Jan 31, 2025.
</Warning>

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

* The SDK now offers both a synchronous and asynchronous [initialization](/client/javascript-sdk/migrating-from-statsig-js#initialization) and [updateUser](/client/javascript-sdk/migrating-from-statsig-js#updating-the-user) methods.
* The "getConfig" method has [changed to "getDynamicConfig"](/client/javascript-sdk/migrating-from-statsig-js#getconfig-is-now-getdynamicconfig)
* When Bootstrapping, you'll now have to [pass the hash parameter as 'djb2'](/client/javascript-sdk/migrating-from-statsig-js#bootstrapping)
* The top-level static instance has moved to a static method, [StatsigClient.instance()](/client/javascript-sdk/migrating-from-statsig-js#static-instance)
* Overrides have moved into their own package: [js-local-overrides](/client/javascript-sdk/migrating-from-statsig-js#overrides)
* Parameters for GDPR compliance have [changed and been centralized](/client/javascript-sdk/migrating-from-statsig-js#gdpr)
* The method to retrieve a stableID [has changed](/client/javascript-sdk/migrating-from-statsig-js#stableid-and-getstableid)
* The structure of [cached values has changed](/client/javascript-sdk/migrating-from-statsig-js#cached-values), with implications on first-run experience
* Several StatsigOptions [have changed](/client/javascript-sdk/migrating-from-statsig-js#legacy-statsigoptions)
* Manual exposure logging methods have been deprecated (`getExperimentWithExposureLoggingDisabled`, `checkGateWithExposureLoggingDisabled`). The checkGate and getExperiment methods now support a second argument to suppress exposure logging [as shown here](https://docs.statsig.com/client/javascript-sdk/#manual-exposures-).

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

<CodeGroup>
  ```typescript statsig-js (Legacy) theme={null}
  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
  );
  ```

  ```typescript New - Async theme={null}
  import { StatsigClient } from '@statsig/js-client';

  const client = new StatsigClient(
    'client-sdk-key',
    { userID: 'some_user_id' },
    { environment: { tier: 'staging' } }
  );

  // Async - waits for latest values
  await client.initializeAsync();
  ```

  ```typescript New - Sync theme={null}
  import { StatsigClient } from '@statsig/js-client';

  const client = new StatsigClient(
    'client-sdk-key',
    { userID: 'some_user_id' },
    { environment: { tier: 'staging' } }
  );

  // Sync - uses cache, fetches in background
  client.initializeSync();
  ```
</CodeGroup>

<Tip>
  View a full example on [GitHub](https://github.com/statsig-io/js-client-monorepo/blob/main/samples/react/src/samples/precomputed-client/sample-precomp-initialize.tsx) or read more about StatsigClient initialization [here](/client/javascript-sdk#initialize-the-sdk).
</Tip>

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

```js theme={null}
// 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:

```js theme={null}
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.

<CodeGroup>
  ```typescript statsig-js (Legacy) theme={null}
  import Statsig from "statsig-js";

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

  await Statsig.updateUser(user);
  ```

  ```typescript New - Async theme={null}
  import { StatsigClient } from '@statsig/js-client';

  const client = new StatsigClient('client-sdk-key', { userID: 'initial-user' });
  await client.initializeAsync();

  // Update to new user - async
  const newUser = { userID: 'a-user' };
  await client.updateUserAsync(newUser);
  ```

  ```typescript New - Sync theme={null}
  import { StatsigClient } from '@statsig/js-client';

  const client = new StatsigClient('client-sdk-key', { userID: 'initial-user' });
  client.initializeSync();

  // Update to new user - sync
  const newUser = { userID: 'a-user' };
  client.updateUserSync(newUser);
  ```
</CodeGroup>

<Tip>
  View a full example on [GitHub](https://github.com/statsig-io/js-client-monorepo/blob/main/samples/react/src/samples/precomputed-client/sample-precomp-update-user.tsx)
</Tip>

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

<CodeGroup>
  ```typescript statsig-js (Legacy) theme={null}
  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...
  }
  ```

  ```typescript New theme={null}
  import { StatsigClient } from '@statsig/js-client';

  // Initialize once in your app
  const client = new StatsigClient(YOUR_CLIENT_KEY, { userID: 'a-user' });
  await client.initializeAsync();

  // then later, at some other location in your code base
  const instance = StatsigClient.instance(YOUR_CLIENT_KEY);
  if (instance.checkGate('a_gate')) { 
    // do something...
  }
  ```
</CodeGroup>

<Tip>
  View a full example on [GitHub](https://github.com/statsig-io/js-client-monorepo/blob/main/samples/react/src/samples/precomputed-client/sample-precomp-static-instance.tsx) or read more about StatsigClient multi-instance support [here](/client/javascript-sdk#multiple-client-instances).
</Tip>

## 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](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.

<CodeGroup>
  ```typescript statsig-js (Legacy) theme={null}
  // 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;
  ```

  ```typescript New theme={null}
  import { StatsigClient } from '@statsig/js-client';

  // start the SDK without storage or logging
  const client = new StatsigClient(
    'client-key',
    { userID: 'a_user' },
    {
      disableLogging: true,
      disableStorage: true,
      networkConfig: { preventAllNetworkTraffic: true },
    }
  );

  await client.initializeAsync();

  // then, once permission was granted
  client.updateRuntimeOptions({
    disableLogging: false,
    disableStorage: false,
    networkConfig: { preventAllNetworkTraffic: false },
  });
  ```
</CodeGroup>

<Tip>
  View a full example on [GitHub](https://github.com/statsig-io/js-client-monorepo/blob/main/samples/react/src/samples/precomputed-client/sample-precomp-gdpr.tsx)
</Tip>

## 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`](https://www.npmjs.com/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](/client/javascript-sdk/using-evaluations-data-adapter)

#### eventLoggingApi

> Replaced by `StatsigOptions.networkConfig.logEventUrl`

#### prefetchUsers

> Replaced by the usage of [StatsigEvaluationsDataAdapter](/client/javascript-sdk/using-evaluations-data-adapter)

#### initCompletionCallback

> Replaced by the usage of [StatsigClientEventEmitter](/client/javascript-sdk#client-event-emitter)

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

#### updateUserCompletionCallback

> Replaced by the usage of [StatsigClientEventEmitter](/client/javascript-sdk#client-event-emitter)

#### fetchMode

> Replaced by the usage of [StatsigEvaluationsDataAdapter](/client/javascript-sdk/using-evaluations-data-adapter)

#### 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](/client/javascript-sdk#client-event-emitter)