Node SDK v5.x.x to v6.0.0 Upgrade Guide

Summary

Node.js SDK V6.0.0 introduced breaking changes on

• Removed async version of core APIs (checkGate, getConfig..)
• Changed DataAdapter cache keys SDK used to read and write from
• Changed default hashing algorithm used for getClientInitializeResponse() which is being used for bootstrapping client sdk.
• If no environment tier is set for the SDK, the environment defaults to production when evaluating.
• Changed how you should disable exposure logging

Synchronous core APIs

Changes Changed all core apis to be synchronous functions

// All removed
async getFeatureGate(): Promise<FeatureGate> // Removed
getFeatureGate(): FeatureGate // New API

async checkGate(): Promise<bool> // Removed
checkGate(): bool // New API

async getConfig(): Promise<DynamicConfig>
getConfig(): DynamicConfig // New API

async getExperiment(): Promise<DynamicConfig>
getExperiment(): DynamicConfig // New API

Context The original async API design ensured that every evaluation could complete correctly, even when the SDK wasn't compatible, by requesting evaluation from the Statsig server. As the SDK and evaluation rules became more stable, you rarely need this fallback. All APIs are now synchronous to improve performance.

Migration Guide If you're using JavaScript and call a gate like this, a runtime error occurs. Audit and update your usage. If you're using TypeScript, the compiler reports an error instead.

The *Sync() functions (for example, checkGateSync()) are deprecated. Use checkGate() instead.

Statsig.checkGate(user, "gate").then(() => {
  // do somethig
}).catch() // Compile error if you are using typescript. If you are using javascript, there will be runtime error please audit and 

If you're using await like this, Statsig recommends removing it, but it continues to work.

const gate = await Statsig.checkGate(user, "gate")

DataAdapter cache key changes

Context To better support multiple Statsig instances in one runtime and different response formats (for example, download_config_spec_v1 vs download_config_spec_v2), Statsig updated the cache keys the SDK reads and writes from. The new keys avoid cache key collisions. The SDK also embeds the compress encoding format in the key. The SDK stores only the plain-text uncompressed version in cache.

Changes

• Change cache key for config_specs from statsig.cache to

statsig|/v1/download_config_specs|{compressEncoding // plain text for now}|{SHA256HashedBase64(secretkey)}

• Change cache key for get_id_list_sources from statsig.id_lists to be:

statsig|/v1/get_id_lists|{compressEncoding // plain text for now}|{SHA256HashedBase64(secretkey)}

• Change cache key for individual id list to be

statsig|id_list::$\{String(idListName)\}|\{compressEncoding // plain text for now\}|${SHA256HashedBase64(secretKey)}

Migration Guide

1. Update your DataAdapter if you have customized the key, get, or read logic.
2. If you write to cache in other places (instead of relying on the SDK to set the cache), update the call site to use the new key.
3. If a cache miss on the first request is acceptable, you don't need to do anything. The SDK writes to cache with the new key automatically.
4. To avoid a cold cache, write with the new key before deploying to production.

Hash algorithm change on getClientInitializeResponse()

Context To improve evaluation speed on both client and server and reduce payload size, the default hash algorithm for all config names changed from SHA256 to djb2.

Changes The SDK now hashes config names (gates, experiments, layers) with djb2 by default. If you specify a hash algorithm explicitly, this change doesn't affect you.

Migration Guide If you're using a recent client SDK version, client-side support is automatic and you don't need to do anything. To continue using SHA256, set ClientInitializeResponseOptions.hash = 'sha256'.

Default environment is production if no environment is being set when SDK is initialized

Context The environment tier setting caused frequent confusion.

Changes If you don't set an environment tier (for example, StatsigOptions.environment.tier), the SDK now assigns a default value. If you set the SDK key, the SDK uses that; otherwise the SDK defaults to production.

Migration Call sites that don't set an environment tier now fail rules that target non-production environment tiers. Call sites that set an environment tier, or rules that don't set an environment or include the production tier, are unaffected.

Deprecate functions

The WithExposureLoggingDisabled functions are deprecated:

checkGateWithExposureLoggingDisabled()  // DO NOT USE
getFeatureGateWithExposureLoggingDisabled() // DO NOT USE

Use core APIs with options instead:

Statsig.checkGate(user, gate_name, {disableExposureLogging: true})  // Use
Statsig.getFeatureGate(user, gate_name, {disableExposureLogging: true})  // USE