# Legacy Node.js Server SDK

> For AI agents: a documentation index is available at [/llms.txt](/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

- **Package:** `statsig-node` ([npm](https://www.npmjs.com/package/statsig-node))
- **Latest version:** 6.5.2
- **Repository:** [node-js-server-sdk](https://github.com/statsig-io/node-js-server-sdk)

## Setup the SDK

1. **Install the SDK**

   Statsig hosts the Node.js SDK on [npm](https://www.npmjs.com/package/statsig-node). You can install the SDK using NPM or Yarn:

   #### npm

   ```bash
   npm install statsig-node
   ```

   #### yarn

   ```bash
   yarn add statsig-node
   ```
2. **Initialize the SDK**

   After installation, initialize the SDK using a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).

   > **Warning:**
   >
   > Don't embed your Server Secret Key in client-side applications, or expose it in any external-facing documents. However, if you accidentally expose it, you can create a new one in the Statsig console.

   ```javascript
   const Statsig = require("statsig-node");

   await Statsig.initialize(
     "server-secret-key",
     { environment: { tier: "staging" } } // optional, if not set, for >v6.0.0, sdk will default to be production  
   );
   ```

   `initialize` performs a network request. After `initialize` completes, virtually all SDK operations are synchronous (refer to [Evaluating Feature Gates in the Statsig SDK](https://blog.statsig.com/evaluating-feature-gates-in-the-statsig-sdk-a6f8881a1ad8)). The SDK fetches updates from Statsig in the background, independently of API calls.

## Working with the SDK

## Checking a Feature Flag/Gate

After you initialize the SDK, you can check a [**Feature Gate**](https://docs.statsig.com/feature-flags/overview). Feature Gates create logic branches in code that you can roll out to different users from the Statsig Console. Gates are always **CLOSED** or **OFF** (`return false;`) by default.

All APIs require you to specify the user (refer to [Statsig user](#statsig-user)) associated with the request. For example, to check a gate for a user:

```javascript
const user = {
  userID: '12345',
  email: '12345@gmail.com',
  ...
};

const showNewDesign = Statsig.checkGate(user, 'new_homepage_design');
if (showNewDesign) {
  // show new design here
} else {
  // show old design here
}
```

## Reading a Dynamic Config

Feature Gates work well for simple on/off switches with optional user targeting. To send a different set of values (strings, numbers, and so on) to clients based on specific user attributes such as country, use [**Dynamic Configs**](https://docs.statsig.com/dynamic-config/overview). The Dynamic Config API is similar to Feature Gates, but returns a full JSON object configured on the server, from which you can fetch typed parameters.

```javascript
const config = Statsig.getConfig(user, "awesome_product_details");

// The 2nd parameter is the default value to be used in case the given parameter name does not exist on
// the Dynamic Config object. This can happen when there is a typo, or when the user is offline and the
// value has not been cached on the client.
const itemName = config.get("product_name", "Awesome Product v1");
const price = config.get("price", 10.0);
const shouldDiscount = config.get("discount", false);
```

## Getting a Layer/Experiment

Use **Layers/Experiments** to run A/B/n experiments. Two APIs are available, but Statsig recommends [layers](https://docs.statsig.com/experiments/layers-overview) for faster iterations with parameter reuse.

```javascript
// Values via getLayer

const layer = Statsig.getLayer(user, "user_promo_experiments");
const promoTitle = layer.get("title", "Welcome to Statsig!");
const discount = layer.get("discount", 0.1);

// or, via getExperiment

const promoExperiment = Statsig.getExperiment(user, "new_user_promo");

const promoTitle = promoExperiment.get("title", "Welcome to Statsig!");
const discount = promoExperiment.get("discount", 0.1);

...

const price = msrp * (1 - discount);
```

## Retrieving Feature Gate Metadata

When you need more than a boolean value from a gate evaluation, use the Get Feature Gate API, which returns a FeatureGate object with additional evaluation metadata:

```javascript
const gate = Statsig.getFeatureGate(user, 'new_homepage_design');
console.log(gate.name); // 'new_homepage_design'
console.log(gate.value); // true or false
console.log(gate.ruleID); // rule ID that was evaluated
console.log(gate.evaluationDetails); // evaluation metadata
```

## Logging an Event

To track custom events and measure how features or experiment groups affect those events, call the Log Event API. Specify the user and event name to log, and optionally provide a value and metadata object:

```javascript
Statsig.logEvent(user, "add_to_cart", "SKU_12345", {
  price: "9.99",
  item_name: "diet_coke_48_pack",
});
```

For more about identifying users, group analytics, and best practices, go to the [logging events guide](https://docs.statsig.com/guides/logging-events).

## Statsig User

When calling APIs that require a user, pass as much information as possible. More user information enables advanced gate and config conditions (like country or OS/browser level checks), and lets Statsig accurately measure the impact of your experiments on your metrics and events. Statsig requires at least one identifier (userID or customID) to provide a consistent experience for a given user. Refer to [userID requirements](https://docs.statsig.com/sdks/user#why-is-an-id-always-required-for-server-sdks) for more detail.

In addition to `userID`, the top-level fields on StatsigUser are `email`, `ip`, `userAgent`, `country`, `locale`, and `appVersion`. You can also pass any key-value pairs in an object/dictionary to the `custom` field to create targeting based on them.

Typing on the `StatsigUser` object is lenient: you can pass numbers, strings, arrays, objects, and even enums or classes. However, evaluation operators only work on primitive types, mostly strings and numbers. The SDK attempts to cast custom field types to match the operator, but Statsig doesn't guarantee evaluation results for other types. For example, the SDK compares an array set as a custom field only as a string: there's no operator to match a value within that array.

### Private Attributes

To keep sensitive user PII data out of logs, use the `privateAttributes` field on the StatsigUser object. This field accepts an object/dictionary of private user attributes. The SDK uses any attribute set in `privateAttributes` only for evaluation/targeting and removes it from all logs before Statsig sends them to its servers.

For example, if a feature gate should only pass for users with emails ending in "@statsig.com", but you don't want to log email addresses to Statsig, add the key-value pair `{ email: "my_user@statsig.com" }` to `privateAttributes` on the user.

## Statsig Options

`initialize()` takes an optional `options` parameter in addition to the secret key to customize the Statsig client:

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| api | string | No | — | The base url to use for all network requests. Defaults to the statsig API. |

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| environment | StatsigEnvironment | No | — | An object you can use to set environment variables that apply to all your users in the same session, for targeting purposes.The most common usage is to set the environment tier ('production', 'staging' or 'development'), e.g. `{ tier: 'staging' }`, and have feature gates pass/fail for specific environments. Since v6.0.0 the default environment tier is production. |

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| bootstrapValues | string | No | — | A string that represents all rules for all feature gates, dynamic configs and experiments. Provide it to bootstrap the Statsig server SDK at initialization in case your server runs into network issue or Statsig server is down temporarily. |

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| rulesUpdatedCallback | function | No | — | A callback function the SDK calls whenever the rules update. The SDK calls it with a JSON string (used as is for the `bootstrapValues` parameter) and a timestamp, like this:```plaintext options.rulesUpdatedCallback(specsString, timeStamp) ``` |

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| logger | LoggerInterface | No | — | The logger interface to use for printing to stdout/stderr |

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| localMode | boolean | No | — | Disables all network access, so the SDK only returns default (or overridden) values. Useful in testing. |

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| initTimeoutMs | number | No | — | Sets a maximum time to wait for the config download network request to resolve before considering the SDK initialized and resolving the call to `initialize()` |

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| dataAdapter | IDataAdapter | No | — | An adapter with custom storage behavior for config specs. Use it to bootstrap Statsig server (takes priority over `bootstrapValues`). You can also use it to continuously fetch updates in place of the Statsig network. Refer to [Data Stores](https://docs.statsig.com/server/concepts/data_store).For example, go to the 1P implementation using Redis [statsig-node-redis](https://github.com/statsig-io/node-js-server-sdk-redis). |

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| UserPersistentStorage | IUserPersistentStorage | No | — | A persistent storage adapter for running sticky experiments. Refer to [examples](https://docs.statsig.com/server/nodejsServerSDK#user-persistent-storage). |

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| rulesetsSyncIntervalMs | number | No | — | Sets the polling interval for the SDK to ask Statsig backend for changes on the rulesets. |

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| idListsSyncIntervalMs | number | No | — | Sets the polling interval for the SDK to ask Statsig backend for changes on the ID Lists. |

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| loggingIntervalMs | number | No | — | Sets the interval for the SDK to periodically flush all logging events to Statsig backend. |

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| loggingMaxBufferSize | number | No | — | Sets the maximum number of events the SDK's logger batches before flushing them all to Statsig backend. |

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| disableDiagnostics | boolean | No | — | Disables diagnostics events from being logged and sent to Statsig |

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| initStrategyForIP3Country | 'await' | 'lazy' | 'none' | No | — | Method of initializing IP to country lookup on `statsig.initialize()`. |

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| initStrategyForIDLists | 'await' | 'lazy' | 'none' | No | — | Method of initializing ID lists on `statsig.initialize()`. |

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| postLogsRetryLimit | number | No | — | The maximum number of retry attempts when sending `/log_event` requests to Statsig server |

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| postLogsRetryBackoff | number | (retry: number) => number | No | — | A fixed number or callback on the retry attempt number to configure the time in ms to wait between each `/log_event` retry.If using a fixed number, a 10x multiplier applies on each subsequent retry. |

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| evaluationCallbacks | EvaluationCallbacks | No | — | Provides callback functions for handling custom logic during evaluations of gates, dynamic configs, experiments, or layers. You can provide specific callbacks for each evaluation type to perform tasks such as custom logging (if you prefer not to use Statsig's default logging), or side effects.To turn off Statsig's default logging, set `disableExposureLogging: true` when making checks.Available callbacks:```plaintext gateCallback?: (gate: FeatureGate, user: StatsigUser, event: LogEvent) => void; dynamicConfigCallback?: (config: DynamicConfig, user: StatsigUser, event: LogEvent) => void; experimentCallback?: (config: DynamicConfig, user: StatsigUser, event: LogEvent) => void; layerCallback?: (layer: Layer, user: StatsigUser) => void; layerParamCallback?: (layer: Layer, paramName: string, user: StatsigUser, event: LogEvent) => void; ``` |

## Shutdown

To gracefully shutdown the SDK and flush all events:

```javascript
statsig.shutdown();
```

## Flush

To manually flush logged events:

```javascript
await statsig.flush();
```

## Client SDK bootstrapping

The Statsig server SDK can generate the initialization values for a client SDK. This is useful for server-side rendering (SSR) or when you want to pre-fetch values for a client.

```typescript
const values = Statsig.getClientInitializeResponse(user); // Record<string, unknown> | null

if (values != null) {
  // Bootstrap the Statsig React Client SDK
  return <StatsigSynchronousProvider initializeValues={values} ... />;
}
```

## Local Overrides

You can override the values the SDK returns for testing purposes, which is useful for local development when testing specific scenarios.

#### TypeScript

```typescript
// Overrides the given gate to the specified value
Statsig.overrideGate("a_gate_name", true, "a_user_id");
	
// Overrides the given config (dynamic config or experiment) to the provided value
Statsig.overrideConfig("a_config_or_experiment_name", { key: "value" }, "a_user_id");
	
// Overrides the given layer to the provided value
Statsig.overrideLayer("a_layer_name", { key: "value" }, "a_user_id");
```

#### JavaScript

```javascript
// Overrides the given gate to the specified value
Statsig.overrideGate("a_gate_name", true, "a_user_id");
	
// Overrides the given config (dynamic config or experiment) to the provided value
Statsig.overrideConfig("a_config_or_experiment_name", { key: "value" }, "a_user_id");
	
// Overrides the given layer to the provided value
Statsig.overrideLayer("a_layer_name", { key: "value" }, "a_user_id");
```

Use these to set an override for a specific user, or for all users (by not providing a specific user ID). Override experiments/Autotune with the `overrideConfig` API.

### Overriding in getClientInitializeResponse

You can also override feature gates, dynamic configs, experiments, and layers when calling `getClientInitializeResponse`. This is useful when you need to provide specific values to the client SDK.

#### TypeScript

```typescript
// Get client initialize response with overrides
const response = Statsig.getClientInitializeResponse(user, clientSDKKey, {
  overrides: {
    // Override feature gates
    featureGates: {
      'my_gate': true,  // Override gate value to true
    },
    
    // Override dynamic configs and experiments
    dynamicConfigs: {
      // Override config value directly
      'price_config': {
        value: { price: 9.99 }
      },
      
      // Override experiment by setting the group assignment
      'color_experiment': {
        groupName: 'Control'  // Uses the value for the Control group
      },
      
      // Override both value and group assignment
      'spacing_experiment': {
        value: { spacing: 64 },
        groupName: 'Variant_B'
      }
    },
    
    // Override layers
    layers: {
      'my_layer': {
        value: { param: 123 }
      }
    }
  }
});
```

#### JavaScript

```javascript
// Get client initialize response with overrides
const response = Statsig.getClientInitializeResponse(user, clientSDKKey, {
  overrides: {
    // Override feature gates
    featureGates: {
      'my_gate': true,  // Override gate value to true
    },
    
    // Override dynamic configs and experiments
    dynamicConfigs: {
      // Override config value directly
      'price_config': {
        value: { price: 9.99 }
      },
      
      // Override experiment by setting the group assignment
      'color_experiment': {
        groupName: 'Control'  // Uses the value for the Control group
      },
      
      // Override both value and group assignment
      'spacing_experiment': {
        value: { spacing: 64 },
        groupName: 'Variant_B'
      }
    },
    
    // Override layers
    layers: {
      'my_layer': {
        value: { param: 123 }
      }
    }
  }
});
```

For experiments, you can override them in two ways:

1. By setting a `value` override on their dynamic config to directly specify the parameter values
2. By setting the `groupName` assignment to use the value for that group name (e.g., "Control" or "Test")

You can also combine both approaches to override both the group assignment and the parameter values.

## Manual Exposures

Statsig SDKs automatically log an exposure event every time you check a gate/experiment/config. In some scenarios, you may want to control when to log an exposure.

You can disable the automatic logging like this:

### Gates

```javascript
const result = Statsig.checkGate(aUser, 'a_gate_name', {disableExposureLogging: true});
```

Then, to manually log the exposure:

```javascript
Statsig.manuallyLogGateExposure(aUser, 'a_gate_name');
```

### Dynamic Configs

```javascript
const config = Statsig.getConfigWithExposureLoggingDisabledSync(aUser, 'a_dynamic_config_name');
```

Then, to manually log the exposure:

```javascript
Statsig.manuallyLogConfigExposure(aUser, 'a_dynamic_config_name');
```

### Experiments

```javascript
const experiment = Statsig.getExperimentWithExposureLoggingDisabledSync(aUser, 'an_experiment_name');
```

Then, to manually log the exposure:

```javascript
Statsig.manuallyLogExperimentExposure(aUser, 'an_experiment_name');
```

### Layers

```javascript
const layer = Statsig.getLayerWithExposureLoggingDisabledSync(aUser, 'a_layer_name');
const paramValue = layer.get('a_param_name', 'fallback_value');
```

Then, to manually log the layer parameter exposure:

```javascript
Statsig.manuallyLogLayerParameterExposure(aUser, 'a_layer_name', 'a_param_name');
```

## Cloudflare Workers setup

### Polling for updates

The SDK can't poll for updates across requests since Cloudflare doesn't allow for timers.

To solve for this, Statsig provides a manual sync API for independently updating the SDK internal store.

```javascript
if (env.lastSyncTime < Date.now() - env.syncInterval) {
  env.lastSyncTime = Date.now();
  context.waitUntil(Statsig.syncConfigSpecs());
}
```

### Flushing events

The SDK enqueues logged events and flushes them in batches. To ensure the SDK properly flushes events, call `flush` using [`context.waitUntil`](https://developers.cloudflare.com/workers/runtime-apis/handlers/fetch/#contextwaituntil). This keeps the request handler alive until the SDK flushes events, without blocking the response.

```javascript
context.waitUntil(Statsig.flush());
```

### Node.JS Compatibility

You can access many native JavaScript API and Node standard libraries in Cloudflare through the [`nodejs_compat`](https://developers.cloudflare.com/workers/runtime-apis/nodejs/) compatibility flag.

The SDK is now compatible with `nodejs_compat` (since v5.16.0). In older versions, you need manual polyfilling.

## User persistent storage

User Persistent Storage is a storage adapter for running sticky experiments. It allows you to persist user assignments across sessions.

### Interface

```typescript
export interface IUserPersistentStorage {
  /**
   * Returns the full map of persisted values for a specific user key
   * @param key user key
   */
  load(key: string): UserPersistedValues;

  /**
   * Save the persisted values of a config given a specific user key
   * @param key user key
   * @param configName Name of the config/experiment
   * @param data Object representing the persistent assignment to store for the given user-config
   */
  save(key: string, configName: string, data: StickyValues): void;

  /**
   * Delete the persisted values of a config given a specific user key
   * @param key user key
   * @param configName Name of the config/experiment
   */
  delete(key: string, configName: string): void;
}
```

### Example Implementation

```typescript
class UserPersistentStorageExample implements IUserPersistentStorage {
  public store: Record<string, UserPersistedValues> = {};
  load(key: string): UserPersistedValues {
    return this.store[key];
  }
  save(key: string, configName: string, data: StickyValues): void {
    if (!(key in this.store)) {
      this.store[key] = {};
    }
    this.store[key][configName] = data;
  }
  delete(key: string, configName: string): void {
    delete this.store[key][configName];
  }
}
```

## Multi-instance usage

To create multiple independent instances of the Statsig SDK (for example, to use different API keys or configurations), use the instance-based approach:

```javascript
// Statsig.initialize becomes:
const sdkInstance = new StatsigServer(secretKey, options);
await sdkInstance.initializeAsync();
```

## Forward proxy configuration

You can configure the SDK to use a forward proxy for network requests:

```javascript
const proxyAddress = "0.0.0.0:50051"
const options = {
      proxyConfigs: {
        'download_config_specs': {
          "proxyAddress": proxyAddress,
          "protocol": "grpc_websocket" as NetworkProtocol
        }
      }
    }
await Statsig.initialize(secretKey, options)
```

## FAQs

### How can I use the node SDK for server side rendering

Refer to [Client SDK Bootstrapping | SSR](#bootstrap).

### How can I mock Statsig for testing

Refer to [LocalOverrides](#local-overrides).

## Reference

### Type StatsigUser

```typescript
export type StatsigUser =
  // at least one of userID or customIDs must be provided
  ({ userID: string } | { customIDs: Record<string, string> }) & {
    userID?: string;
    customIDs?: Record<string, string>;
    email?: string;
    ip?: string;
    userAgent?: string;
    country?: string;
    locale?: string;
    appVersion?: string;
    custom?: Record<
      string,
      string | number | boolean | Array<string> | undefined
    >;
    privateAttributes?: Record<
      string,
      string | number | boolean | Array<string> | undefined
    > | null;
    statsigEnvironment?: StatsigEnvironment;
  }
```

### Type StatsigOptions

```typescript
export type StatsigOptions = {
  api: string;
  apiForDownloadConfigSpecs: string;
  apiForGetIdLists: string;
  bootstrapValues: string | null;
  environment: StatsigEnvironment | null;
  rulesUpdatedCallback: RulesUpdatedCallback | null;
  logger: LoggerInterface;
  localMode: boolean;
  initTimeoutMs: number;
  dataAdapter: IDataAdapter | null;
  rulesetsSyncIntervalMs: number;
  idListsSyncIntervalMs: number;
  loggingIntervalMs: number;
  loggingMaxBufferSize: number;
  disableDiagnostics: boolean;
  initStrategyForIP3Country: InitStrategy;
  initStrategyForIDLists: InitStrategy;
  postLogsRetryLimit: number;
  postLogsRetryBackoff: RetryBackoffFunc | number;
  disableRulesetsSync: boolean;
  disableIdListsSync: boolean;
  disableAllLogging: boolean;
};

export type RulesUpdatedCallback = (rulesJSON: string, time: number) => void;
export type RetryBackoffFunc = (retriesRemaining: number) => number;

export type StatsigEnvironment = {
  tier?: 'production' | 'staging' | 'development' | string;
  [key: string]: string | undefined;
};

export type InitStrategy = 'await' | 'lazy' | 'none';

export interface LoggerInterface {
  debug?(message?: any, ...optionalParams: any[]): void;
  info?(message?: any, ...optionalParams: any[]): void;
  warn(message?: any, ...optionalParams: any[]): void;
  error(message?: any, ...optionalParams: any[]): void;
  logLevel: 'none' | 'debug' | 'info' | 'warn' | 'error';
}
```

### Type FeatureGate

```typescript
export type FeatureGate = {
  readonly name: string;
  readonly ruleID: string;
  readonly idType: string | null;
  readonly value: boolean;
  readonly evaluationDetails: EvaluationDetails | null;
  readonly groupName: null; // deprecated
};
```

### Type DynamicConfig

```typescript
export default class DynamicConfig {
  name: string;
  value: Record<string, unknown>;
  get<T>(
    key: string,
    defaultValue: T,
    typeGuard: ((value: unknown) => value is T | null) | null = null,
  ): T;
  getValue(
    key: string,
    defaultValue?: boolean | number | string | object | Array<any> | null,
  ): unknown | null;
  getRuleID(): string;
  getGroupName(): string | null;
  getIDType(): string | null;
  getEvaluationDetails(): EvaluationDetails | null;
```

### Type Layer

```typescript
export default class Layer {
  name: string;
  public get<T>(
    key: string,
    defaultValue: T,
    typeGuard: ((value: unknown) => value is T) | null = null,
  ): T;
  getValue(
    key: string,
    defaultValue?: boolean | number | string | object | Array<any> | null,
  ): unknown | null;
  getRuleID(): string;
  getGroupName(): string | null;
  getAllocatedExperimentName(): string | null;
  getEvaluationDetails(): EvaluationDetails | null;
```

### DataAdapter

```typescript
export interface IDataAdapter {
  get(key: string): Promise<AdapterResponse>;
  set(key: string, value: string, time?: number): Promise<void>;
  initialize(): Promise<void>;
  shutdown(): Promise<void>;
  supportsPollingUpdatesFor(key: DataAdapterKey): boolean;
}
```

### EvaluationDetails

```typescript
export class EvaluationDetails {
  readonly configSyncTime: number;
  readonly initTime: number;
  readonly serverTime: number;
  readonly reason: EvaluationReason;
}
```

### EvaluationReason

```typescript
export type EvaluationReason =
  | 'Network'
  | 'LocalOverride'
  | 'Unrecognized'
  | 'Uninitialized'
  | 'Bootstrap'
  | 'DataAdapter'
  | 'Unsupported';
```