## Setup the SDK

{% steps %}
{% step title="Install the SDK" %}
The Node.js SDK is hosted [here](https://www.npmjs.com/package/statsig-node). You can install the SDK using NPM or Yarn:

{% codetabs %}
```bash npm
npm install statsig-node
```

```bash yarn
yarn add statsig-node
```
{% /codetabs %}
{% /step %}

{% step title="Initialize the SDK" %}
After installation, initialize the SDK using a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).

{% callout type="warning" %}
Do NOT 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.
{% /callout %}

```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.
{% /step %}
{% /steps %}

## Working with the SDK

## Checking a Feature Flag/Gate

After the SDK is initialized, you can check a [**Feature Gate**](/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**](/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](/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](/guides/logging-events).

## Statsig User

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

In addition to `userID`, `email`, `ip`, `userAgent`, `country`, `locale`, and `appVersion` are available as top-level fields on StatsigUser. 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 evaluation results for other types are not guaranteed. For example, an array set as a custom field is only compared as a string: there is 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. Any attribute set in `privateAttributes` is used only for evaluation/targeting and is removed 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:

{% parameter name="api" type="string" %}
The base url to use for all network requests. Defaults to the statsig API.
{% /parameter %}

{% parameter name="environment" type="StatsigEnvironment" %}
An object you can use to set environment variables that apply to all your users in the same session, used 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.
{% /parameter %}

{% parameter name="bootstrapValues" type="string" %}
A string that represents all rules for all feature gates, dynamic configs and experiments. It can be provided to bootstrap the Statsig server SDK at initialization in case your server runs into network issue or Statsig server is down temporarily.
{% /parameter %}

{% parameter name="rulesUpdatedCallback" type="function" %}
A callback function that's called whenever the rules update; it's called with a JSON string (used as is for `bootstrapValues` mentioned above) and a timestamp, like below:

```
options.rulesUpdatedCallback(specsString, timeStamp)
```
{% /parameter %}

{% parameter name="logger" type="LoggerInterface" %}
The logger interface to use for printing to stdout/stderr
{% /parameter %}

{% parameter name="localMode" type="boolean" %}
Disables all network access, so the SDK will only return default (or overridden) values. Useful in testing.
{% /parameter %}

{% parameter name="initTimeoutMs" type="number" %}
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()`
{% /parameter %}

{% parameter name="dataAdapter" type="IDataAdapter" %}
An adapter with custom storage behavior for config specs. Can be used to bootstrap Statsig server (takes priority over `bootstrapValues`). Can also be used to continuously fetch updates in place of the Statsig network. Refer to [Data Stores](/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).
{% /parameter %}

{% parameter name="UserPersistentStorage" type="IUserPersistentStorage" %}
A persistent storage adapter for running sticky experiments. Refer to [examples](/server/nodejsServerSDK#user-persistent-storage).
{% /parameter %}

{% parameter name="rulesetsSyncIntervalMs" type="number" %}
Sets the polling interval for the SDK to ask Statsig backend for changes on the rulesets.
{% /parameter %}

{% parameter name="idListsSyncIntervalMs" type="number" %}
Sets the polling interval for the SDK to ask Statsig backend for changes on the ID Lists.
{% /parameter %}

{% parameter name="loggingIntervalMs" type="number" %}
Sets the interval for the SDK to periodically flush all logging events to Statsig backend.
{% /parameter %}

{% parameter name="loggingMaxBufferSize" type="number" %}
Sets the maximum number of events the SDK's logger will batch before flushing them all to Statsig backend.
{% /parameter %}

{% parameter name="disableDiagnostics" type="boolean" %}
Disables diagnostics events from being logged and sent to Statsig
{% /parameter %}

{% parameter name="initStrategyForIP3Country" type="'await' | 'lazy' | 'none'" %}
Method of initializing IP to country lookup on `statsig.initialize()`.
{% /parameter %}

{% parameter name="initStrategyForIDLists" type="'await' | 'lazy' | 'none'" %}
Method of initializing ID lists on `statsig.initialize()`.
{% /parameter %}

{% parameter name="postLogsRetryLimit" type="number" %}
The maximum number of retry attempts when sending `/log_event` requests to Statsig server
{% /parameter %}

{% parameter name="postLogsRetryBackoff" type="number | (retry: number) => number" %}
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.
{% /parameter %}

{% parameter name="evaluationCallbacks" type="EvaluationCallbacks" %}
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:

```
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;
```
{% /parameter %}

## Shutdown

To gracefully shutdown the SDK and ensure all events are flushed:

```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 returned by the SDK for testing purposes, which is useful for local development when testing specific scenarios.

{% codetabs %}
```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");
```
{% /codetabs %}

These can be used to set an override for a specific user, or for all users (by not providing a specific user ID). Experiments/Autotune are overridden 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.

{% codetabs %}
```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 }
      }
    }
  }
});
```
{% /codetabs %}

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 a gate/experiment/config is checked. 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, a manual sync API is available 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 events are properly flushed, call `flush` using [`context.waitUntil`](https://developers.cloudflare.com/workers/runtime-apis/handlers/fetch/#contextwaituntil).
This keeps the request handler alive until events are flushed without blocking the response.

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

### Node.JS Compatibility

Many native JavaScript API and Node standard libraries can be accessed 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, manual polyfilling is required.

## 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';
```