JavaScript Client SDK (Web) - Statsig Documentation

Source code: statsig-io/js-client-monorepo

Set Up the SDK

This page explains set up the sdk.

Install the SDK

To install the Statsig Web SDK, add the package via your preferred package manager. Include optional packages if you plan to enable Session Replay or Auto Capture.

npm install @statsig/js-client @statsig/session-replay @statsig/web-analytics
```text

</Tab>
<Tab title="yarn">

```bash
yarn add @statsig/js-client @statsig/session-replay @statsig/web-analytics

If you don’t need Session Replay or Auto Capture, omit the @statsig/session-replay and @statsig/web-analytics packages.

After installation, configure the SDK in your app entry point before rendering your UI.

Initialize the SDK

Next, initialize the SDK with a client SDK key from the “API Keys” tab on the Statsig console. These keys are safe to embed in a client application.Along with the key, pass in a User Object with the attributes you’d like to target later on in a gate or experiment.

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

const client = new StatsigClient(
  'client-xyz',
  { userID: 'a-user' },
  {
    environment: { tier: 'development' },
  },
);

await client.initializeAsync();

Use initializeAsync when you need to await the latest values. For a non-blocking approach, you can call initializeAsync() without awaiting and rely on cached values until the promise resolves.

Use the SDK

Checking a Feature Flag/Gate

Now that your SDK is initialized, let’s check a Feature Gate. Feature Gates can be used to create logic branches in code that can be rolled out to different users from the Statsig Console. Gates are always CLOSED or OFF (think return false;) by default.

if (client.checkGate('new_homepage_design')) {
  // Gate is on, show new experience
} else {
  // Gate is off, render the default experience
}

Reading a Dynamic Config

Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be able send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, Dynamic Configs can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example:

const config = client.getDynamicConfig('awesome_product_details');
const itemName = config.get('product_name', 'Some Fallback');
const price = config.value.price ?? 10.0;

if (config.value.is_discount_enabled === true) {
  // apply discount logic
}

Getting a Layer/Experiment

Then we have Layers/Experiments, which you can use to run A/B/n experiments. We offer two APIs, but we recommend the use of layers to enable quicker iterations with parameter reuse.

// Reading values via getLayer
const layer = client.getLayer('user_promo_experiments');
const promoTitle = layer.get('title', 'Welcome to Statsig!');
const discount = layer.get('discount', 0.1);
```text

```tsx
// Reading values via getExperiment
const titleExperiment = client.getExperiment('new_user_promo_title');
const priceExperiment = client.getExperiment('new_user_promo_price');

const experimentTitle = titleExperiment.value.title ?? 'Welcome to Statsig!';
const experimentDiscount = priceExperiment.value.discount ?? 0.1;

Logging an Event

Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig - simply call the Log Event API for the event, and you can additionally provide some value and/or an object of metadata to be logged together with the event:

client.logEvent('my_simple_event');

client.logEvent({
  eventName: 'add_to_cart',
  value: 'SKU_12345',
  metadata: {
    price: '9.99',
    item_name: 'diet_coke_48_pack',
  },
});

Typed Getters

Layer, Experiment, and DynamicConfig objects support a typed get method. Using a fallback that matches the expected type helps avoid returning unintended values.

// config value: { "my_value": 1 }
const dynamicConfig = client.getDynamicConfig('a_config');

const fallbackString = dynamicConfig.get('my_value', 'fallback'); // returns 'fallback'
const fallbackNumber = dynamicConfig.get('my_value', 0); // returns 1
const rawValue = dynamicConfig.get('my_value'); // returns 1

Passing a fallback of the wrong type returns that fallback. When type safety is not needed, omit the fallback to receive the raw value.

Evaluation Details

Each gate, config, experiment, and layer exposes details describing how the value was resolved.

reason explains the source (e.g., Network:Recognized, Cache:Unrecognized).
lcut is the last time any configuration changed in your project.
receivedAt marks when this response was received, useful for judging cache staleness.

const gate = client.getFeatureGate('a_gate');
console.log(gate.details);
// { reason: 'Cache:Recognized', lcut: 1713837126636, receivedAt: 1713838137598 }

const config = client.getDynamicConfig('a_config');
console.log(config.details);
// { reason: 'Cache:Unrecognized', lcut: 1713837126636, receivedAt: 1713838137598 }

See /sdk/debugging for the full list of reason values.

Sample Projects

Explore end-to-end examples in the js-client-monorepo samples folder for React, Next.js, precomputed clients, and more.

Parameter Stores

Parameter Stores hold a set of parameters for your mobile app. These parameters can be remapped on-the-fly from a static value to a Statsig entity (Feature Gates, Experiments, and Layers), so you can decouple your code from the configuration in Statsig. Read more about Param Stores here.

const homepageStore = client.getParameterStore('homepage');

const title = homepageStore.get('title', 'Welcome');
const showUpsell = homepageStore.get('upsell_upgrade_now', false);

Statsig User

You need to provide a StatsigUser object to check/get your configurations. You should pass as much information as possible in order to take advantage of advanced gate and config conditions. Most of the time, the userID field is needed in order to provide a consistent experience for a given user (see logged-out experiments to understand how to correctly run experiments for logged-out users). Besides userID, we also have email, ip, userAgent, country, locale and appVersion as top-level fields on StatsigUser. In addition, you can pass any key-value pairs in an object/dictionary to the custom field and be able to create targeting based on them. Once the user logs in or has an update/changed, make sure to call updateUser with the updated userID and/or any other updated user attributes:

Updating Users

Call updateUserAsync when the signed-in user changes to fetch fresh values for that identity.

const user = { userID: 'a-user' };
await client.updateUserAsync(user);

For advanced flows—such as bootstrapping or prefetching users—see Using EvaluationsDataAdapter.

Prefetching Users

Use prefetchData to prepare values for another user so you can switch synchronously later.

const nextUser = { userID: 'my-other-user' };

await client.dataAdapter.prefetchData(nextUser);
// Optionally handle failures without blocking the UI
client.dataAdapter.prefetchData(nextUser).catch((err) => {
  console.warn('Failed to prefetch', err);
});

client.updateUserSync(nextUser);
const gate = client.getFeatureGate('a_gate');
console.log(gate.value, gate.details.reason); // true, 'Prefetch:Recognized'

Statsig Options

This page explains statsig options.

loggingEnabled

LoggingEnabledOption

default:"browser-only"

Controls logging behavior.

browser-only (default): log events from browser environments.
disabled: never send events.
always: log in every environment, including non-browser contexts.

disableLogging

boolean

deprecated

Use loggingEnabled: 'disabled' instead.

disableStableID

boolean

default:"false"

Skip generating a device-level Stable ID.

disableEvaluationMemoization

boolean

default:"false"

Recompute every evaluation instead of using the memoized result.

initialSessionID

string

Override the generated session ID.

enableCookies

boolean

default:"false"

Persist Stable ID in cookies for cross-domain tracking.

disableStorage

boolean

Prevent any local storage writes (disables caching).

networkConfig

NetworkConfig

Override network endpoints per request type.

environment

StatsigEnvironment

Set environment-wide defaults (for example { tier: 'staging' }).

logLevel

LogLevel

default:"Warn"

Console verbosity.

loggingBufferMaxSize

number

default:"50"

Max events per log batch.

loggingIntervalMs

number

default:"10_000"

Interval between automatic flushes.

overrideAdapter

OverrideAdapter

Modify evaluations before returning them.

includeCurrentPageUrlWithEvents

boolean

default:"true"

Attach the current page URL to logged events.

disableStatsigEncoding

boolean

default:"false"

Send requests without Statsig-specific encoding.

logEventCompressionMode

LogEventCompressionMode

default:"Enabled"

Control compression for batched events.

disableCompression

boolean

deprecated

Use logEventCompressionMode instead.

dataAdapter

EvaluationsDataAdapter

Provide a custom data adapter to control caching/fetching.

customUserCacheKeyFunc

CustomCacheKeyGenerator

Override cache key generation for stored evaluations.

Network Config Options

api

string

default:"https://api.statsig.com"

Base URL for all requests (append /v1).

logEventUrl

string

default:"https://prodregistryv2.org/v1/rgstr"

Endpoint for event uploads.

logEventFallbackUrls

string[]

Fallback endpoints for event uploads.

networkTimeoutMs

number

default:"10000"

Request timeout in milliseconds.

preventAllNetworkTraffic

boolean

Disable all outbound requests; combine with loggingEnabled: 'disabled' to silence log warnings.

networkOverrideFunc

function

Provide custom transport (e.g., Axios).

initializeUrl

string

default:"https://featureassets.org/v1/initialize"

Endpoint for initialization requests.

Manual Exposures

Manual logging is error-prone and can often introduce issues like uneven exposures, which compromise experiment results.

You can query your gates/experiments without triggering an exposure, and manually log the exposures later:

Feature Gates

const result = client.checkGate('a_gate_name', { disableExposureLog: true });
// ...
client.checkGate('a_gate_name'); // later, when ready to log the exposure
```text

</Tab>
<Tab title="Dynamic Configs">

```tsx
const config = client.getConfig('a_dynamic_config_name', { disableExposureLog: true });
client.getConfig('a_dynamic_config_name');
```text

</Tab>
<Tab title="Experiments">

```tsx
const experiment = client.getExperiment('an_experiment_name', { disableExposureLog: true });
client.getExperiment('an_experiment_name');
```text

</Tab>
<Tab title="Layers">

```tsx
const layer = client.getLayer('a_layer_name', { disableExposureLog: true });
const value = layer.get('param_name', 'fallback');

// When ready to log
const exposure = client.getLayer('a_layer_name');
exposure.get('param_name', 'fallback');

Session Replay

Install @statsig/session-replay and register the plugin to record user sessions.

import { StatsigProvider } from '@statsig/react-bindings';
import { StatsigSessionReplayPlugin } from '@statsig/session-replay';

<StatsigProvider
  sdkKey="client-xyz"
  user={{ userID: 'a-user' }}
  loadingComponent={<div style={{ height: 100, width: 300, padding: 16 }}>Loading...</div>}
  options={{ plugins: [new StatsigSessionReplayPlugin()] }}
>
  <App />
</StatsigProvider>;
```text

<webAnalyticsIntro/>

```tsx
import { StatsigProvider } from '@statsig/react-bindings';
import { StatsigAutoCapturePlugin } from '@statsig/web-analytics';

<StatsigProvider
  sdkKey="client-xyz"
  user={{ userID: 'a-user' }}
  loadingComponent={<div style={{ height: 100, width: 300, padding: 16 }}>Loading...</div>}
  options={{ plugins: [new StatsigAutoCapturePlugin()] }}
>
  <App />
</StatsigProvider>;

Content Security Policy

Add Statsig endpoints to your CSP connect-src directive when running the web SDK.

const cspConfig = {
  directives: {
    'connect-src': [
      'api.statsig.com',
      'featuregates.org',
      'statsigapi.net',
      'events.statsigapi.net',
      'api.statsigcdn.com',
      'featureassets.org',
      'assetsconfigcdn.org',
      'prodregistryv2.org',
      'cloudflare-dns.com',
      'beyondwickedmapping.org',
    ],
  },
};

Statsig occasionally updates its network domains. Verify the latest list in Statsig Domains.

Lifecycle & Advanced Usage

Shutting Statsig Down

In order to save users’ data and battery usage, as well as prevent logged events from being dropped, we keep event logs in client cache and flush periodically. Because of this, some events may not have been sent when your app shuts down. To make sure all logged events are properly flushed or saved locally, you should tell Statsig to shutdown when your app is closing:

await client.shutdown();

StableID

Each client SDK has the notion of stableID, a devive-level identifier that is generated the first time the SDK is initialized and is stored locally for all future sessions. Unless storage is wiped (or app deleted), the stableID will not change. This allows us to run device level experiments and experiments when other user identifiable information is unavailable (Logged out users).

Using multiple instances of the SDK

Up to this point, we’ve used the SDK’s singleton. We also support creating multiples instances of the SDK - the Statsig singleton wraps a single instance of the SDK (typically called a StatsigClient) that you can instantiate.

You must use a different SDK key for each sdk instance you create for this to work. Various functionality of the Statsig client is keyed on the SDK key being used. Using the same key will lead to collisions.

All top level static methods from the singleton carry over as instance methods. To create an instance of the Statsig sdk:

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

const mainClient = new StatsigClient('client-xyz', { userID: 'a-user' });
const secondaryClient = new StatsigClient('client-abc', { userID: 'another-user' });

await Promise.all([
  mainClient.initializeAsync(),
  secondaryClient.initializeAsync(),
]);

if (mainClient.checkGate('a_gate')) {
  // ...
}

if (secondaryClient.checkGate('some_other_gate')) {
  // ...
}

Override Adapter

Use the LocalOverrideAdapter to define local overrides for gates, configs, experiments, or layers.

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

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

const client = new StatsigClient('client-xyz', { userID: 'a-user' }, {
  logLevel: LogLevel.Debug,
  overrideAdapter,
});
```text

### Persisting Overrides

Pass your client SDK key to the adapter to persist overrides between sessions when using multi-instance setups.

```tsx
const overrideAdapter = new LocalOverrideAdapter('client-xyz');

Using Persistent Evaluations

Persist experiment assignments so users keep the same variant even if targeting rules change.

import { StatsigClient } from '@statsig/js-client';
import { UserPersistentOverrideAdapter } from '@statsig/js-user-persisted-storage';

class LocalStorageUserPersistedStorage {
  load(key: string) {
    return JSON.parse(localStorage.getItem(key) ?? '{}');
  }

  save(key: string, experiment: string, data: string) {
    const values = JSON.parse(localStorage.getItem(key) ?? '{}');
    values[experiment] = JSON.parse(data);
    localStorage.setItem(key, JSON.stringify(values));
  }

  delete(key: string, experiment: string) {
    const data = JSON.parse(localStorage.getItem(key) ?? '{}');
    delete data[experiment];
    localStorage.setItem(key, JSON.stringify(data));
  }
}

const storage = new LocalStorageUserPersistedStorage();
const adapter = new UserPersistentOverrideAdapter(storage);
const client = new StatsigClient('client-xyz', { overrideAdapter: adapter });

await client.initializeAsync({ userID: '123' });

const userPersistedValues = adapter.loadUserPersistedValues({ userID: '123' }, 'userID');
const experiment = client.getExperiment('active_experiment', { userPersistedValues });

See Client Persistent Assignment for additional patterns and storage options.

Common Targeting Use Cases

Capture cookies or URL parameters and pass them through StatsigUser.custom for targeting rules.

const user = {
  custom: {
    isLoggedIn: cookieLib.get('isLoggedIn'),
    utm: new URL(window.location.href).searchParams.get('utm'),
  },
};

const client = new StatsigClient('client-xyz', user, options);
```text

<Frame>
  <img src="/images/client/js-common-targeting.png" alt="Targeting in Console" />
</Frame>

## Async Timeouts

Limit how long `initializeAsync` and `updateUserAsync` wait for network responses before falling back to cached values.

```tsx
await client.initializeAsync({ timeoutMs: 1000 });

await client.updateUserAsync(
  { userID: 'a-user' },
  { timeoutMs: 1000 },
);

Data Adapter

StatsigClient uses an EvaluationsDataAdapter to manage caching and network fetches. The default implementation (StatsigEvaluationsDataAdapter) reads from local storage synchronously and refreshes values from Statsig asynchronously. See Using EvaluationsDataAdapter for full examples, including bootstrapping, prefetching, and custom adapters.

Partial User Matching

Use customUserCacheKeyFunc with updateUserSync when you need to enrich a user locally without triggering a full network refresh.

const originalUser = {
  customIDs: {
    analyticsID: 'analytics-123',
  },
};

const customKey = (sdkKey: string, user: StatsigUser) => {
  const analyticsID = user.customIDs?.analyticsID ?? 'anonymous';
  return `sdkKey:${sdkKey}:analyticsID:${analyticsID}`;
};

const client = new StatsigClient('client-xyz', originalUser, {
  customUserCacheKeyFunc: customKey,
});

await client.initializeAsync();

someAsyncFunction().then((newData) => {
  const enrichedUser = {
    ...originalUser,
    userID: newData.userID,
    email: newData.email,
  };

  client.updateUserSync(enrichedUser);
});

Custom cache keys can produce stale or incorrect evaluations if multiple users map to the same key. Await updateUserAsync when you need guaranteed fresh values per user.

Client Event Emitter

Subscribe to Statsig client lifecycle events to respond to initialization, logging, or evaluation changes.

import type {
  AnyStatsigClientEvent,
  StatsigClientEvent,
} from '@statsig/client-core';

const onAnyEvent = (event: AnyStatsigClientEvent) => {
  console.log('Statsig event', event);
};

const onLogsFlushed = (event: StatsigClientEvent<'logs_flushed'>) => {
  console.log('Logs', event.events);
};

client.on('logs_flushed', onLogsFlushed);
client.on('*', onAnyEvent);

client.off('logs_flushed', onLogsFlushed);
client.off('*', onAnyEvent);

Event	Payload	Description
`values_updated`	`{ status, values }`	Fired when initialize/update refreshes cached values.
`session_expired`	`{}`	Fired when the current session expires.
`error`	`{ error, tag }`	Unexpected client errors.
`pre_logs_flushed`	`{ events }`	Before a batch of events is sent.
`logs_flushed`	`{ events }`	After events are sent.
`pre_shutdown`	`{}`	Before the SDK shuts down.
`initialization_failure`	`{}`	Initialization failed.
`gate_evaluation`	`{ gate }`	When a gate is evaluated.
`dynamic_config_evaluation`	`{ dynamicConfig }`	When a config is evaluated.
`experiment_evaluation`	`{ experiment }`	When an experiment is evaluated.
`layer_evaluation`	`{ layer }`	When a layer is evaluated.
`log_event_called`	`{ event }`	When `logEvent` is called.

Quality & Troubleshooting

Testing

Mock Statsig APIs in Jest to isolate business logic.

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

export async function transform(input: string): Promise<string> {
  const client = new StatsigClient('client-xyz', { userID: 'a-user' }, {
    networkConfig: {
      preventAllNetworkTraffic:
        typeof process !== 'undefined' && process.env['NODE_ENV'] === 'test',
    },
  });

  await client.initializeAsync();

  if (client.checkGate('a_gate')) {
    input = 'transformed';
  }

  const experiment = client.getExperiment('an_experiment');
  input += '-' + experiment.get('my_param', 'fallback');

  await client.shutdown();
  return input;
}
```text

```tsx
import { StatsigClient } from '@statsig/js-client';

jest.mock('@statsig/js-client');

test('string transformations', async () => {
  jest
    .spyOn(StatsigClient.prototype, 'checkGate')
    .mockImplementation(() => true);

  jest
    .spyOn(StatsigClient.prototype, 'getExperiment')
    .mockImplementation(() => ({ get: () => 'my-value' } as any));

  const result = await transform('original');
  expect(result).toBe('transformed-my-value');
});

Debugging

When results look unexpected, use these tools to inspect what the SDK is doing.

Enable Verbose Logging

import { LogLevel, StatsigClient } from '@statsig/js-client';

const client = new StatsigClient('client-xyz', { userID: 'a-user' }, {
  logLevel: LogLevel.Debug,
});
```ruby

### Inspect the `__STATSIG__` Global

Open your browser console and run `__STATSIG__` to inspect the current client instance. Useful properties include `_logger._queue` for pending events.

<Frame>
  <img src="/images/client/statsig-global.png" alt="Statsig Global" />
</Frame>

### Review Network Traffic

Filter network requests by `client-` to see initialization and logging calls.

<Frame>
  <img src="/images/client/network-logs.png" alt="Network Logs" />
</Frame>

### Check Evaluation Reasons

```ts
const gate = client.getFeatureGate('a_gate');
console.log(gate.details.reason);

Common reasons:

Network | NetworkNotModified — latest values from the API.
Cache — loaded from local storage.
NoValues — no cached values and network failed.
Bootstrap — values provided via dataAdapter.setData.
Prefetch — values from dataAdapter.prefetchData.

See /sdk/debugging for full details.

FAQs

Does the SDK use local storage or cookies?

Statsig’s web SDK does not set cookies. It stores gate/config values and unsent events in localStorage so features keep working when offline.

Can I access the SDK instance globally?

window.Statsig.instance().logEvent('test_event');
```text

```ts
import { StatsigClient } from '@statsig/js-client';
StatsigClient.instance().logEvent('test_event');
```text

<Info>
With multiple instances, pass the SDK key: `Statsig.instance('client-YOUR_KEY')`.
</Info>

#### How do I handle consent or GDPR flows?

Start with logging disabled and storage blocked, then enable them after consent.

```tsx
const client = new StatsigClient('client-xyz', {}, {
  loggingEnabled: 'disabled',
  disableStorage: true,
});
await client.initializeAsync();

client.updateRuntimeOptions({
  loggingEnabled: 'browser-only',
  disableStorage: false,
});

The SDK buffers up to 500 events in memory and flushes them once logging is re-enabled.

SDK Quickstarts

SDK Concepts

Client SDKs

Server SDKs

AI SDKs

More SDK Methods

Console API Reference

Statsig CLI

HTTP API Reference

​Set Up the SDK

​Use the SDK

​Checking a Feature Flag/Gate

​Reading a Dynamic Config

​Getting a Layer/Experiment

​Logging an Event

​Typed Getters

​Evaluation Details

​Sample Projects

​Parameter Stores

​Statsig User

​Updating Users

​Prefetching Users

​Statsig Options

​Manual Exposures

​Session Replay

​Content Security Policy

​Lifecycle & Advanced Usage

​Shutting Statsig Down

​StableID

​Using multiple instances of the SDK

​Override Adapter

​Using Persistent Evaluations

​Common Targeting Use Cases

​Data Adapter

​Partial User Matching

​Client Event Emitter

​Quality & Troubleshooting

​Testing

​Debugging

​Enable Verbose Logging

​FAQs

​Does the SDK use local storage or cookies?

​Can I access the SDK instance globally?

​Additional Resources

Set Up the SDK

Use the SDK

Checking a Feature Flag/Gate

Reading a Dynamic Config

Getting a Layer/Experiment

Logging an Event

Typed Getters

Evaluation Details

Sample Projects

Parameter Stores

Statsig User

Updating Users

Prefetching Users

Statsig Options

Manual Exposures

Session Replay

Content Security Policy

Lifecycle & Advanced Usage

Shutting Statsig Down

StableID

Using multiple instances of the SDK

Override Adapter

Using Persistent Evaluations

Common Targeting Use Cases

Data Adapter

Partial User Matching

Client Event Emitter

Quality & Troubleshooting

Testing

Debugging

Enable Verbose Logging

FAQs

Does the SDK use local storage or cookies?

Can I access the SDK instance globally?

Additional Resources