{"id":12075,"library":"statsig-node","title":"Statsig Node.js SDK","description":"The Statsig Node.js SDK (current stable version 6.5.1) provides robust tools for managing feature gates, dynamic configurations, and A/B testing within multi-user server environments. It enables developers to implement continuous deployment strategies and understand the impact of new features on key performance indicators. The package sees frequent updates, typically releasing bug fixes and minor improvements multiple times a month, as evidenced by recent changelogs. Key differentiators include its comprehensive A/B testing capabilities, detailed analytics, and a focus on server-side performance and data consistency, contrasting with client-side SDKs that handle single-user contexts. It is designed for use cases where server-side evaluation of features is critical for performance and security.","status":"active","version":"6.5.1","language":"javascript","source_language":"en","source_url":"https://github.com/statsig-io/node-js-server-sdk","tags":["javascript","feature gate","feature flag","continuous deployment","ci","ab test","typescript"],"install":[{"cmd":"npm install statsig-node","lang":"bash","label":"npm"},{"cmd":"yarn add statsig-node","lang":"bash","label":"yarn"},{"cmd":"pnpm add statsig-node","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Cryptographic hashing, patched for security vulnerability in v6.4.8.","package":"sha.js","optional":false}],"imports":[{"note":"Main entry point for SDK functionalities. Primarily designed for ESM, though CJS `require` might work for some versions.","wrong":"const Statsig = require('statsig-node');","symbol":"Statsig","correct":"import { Statsig } from 'statsig-node';"},{"note":"Represents a user object for feature evaluation. Always a named import.","wrong":"import StatsigUser from 'statsig-node';","symbol":"StatsigUser","correct":"import { StatsigUser } from 'statsig-node';"},{"note":"The initialization function is asynchronous and must be awaited before using other SDK methods.","wrong":"Statsig.initialize('YOUR_SECRET_KEY');","symbol":"initialize","correct":"await Statsig.initialize('YOUR_SECRET_KEY');"}],"quickstart":{"code":"import { Statsig, StatsigUser } from 'statsig-node';\n\nconst STATSIG_SECRET_KEY = process.env.STATSIG_SERVER_SECRET_KEY ?? '';\n\nasync function runStatsigExample() {\n  if (!STATSIG_SECRET_KEY) {\n    console.error('STATSIG_SERVER_SECRET_KEY environment variable is not set.');\n    return;\n  }\n\n  try {\n    await Statsig.initialize(STATSIG_SECRET_KEY, {\n      localMode: false, // Set to true for local testing without network calls\n      // Additional options like 'environment', 'api' can be passed here\n    });\n\n    const user: StatsigUser = {\n      userID: 'unique-user-id-123',\n      email: 'test@example.com',\n      country: 'US',\n      custom: { membershipTier: 'premium' },\n      // Additional custom properties can be added\n    };\n\n    if (await Statsig.checkGate(user, 'my_new_feature_gate')) {\n      console.log('Feature \"my_new_feature_gate\" is ENABLED for the user!');\n    } else {\n      console.log('Feature \"my_new_feature_gate\" is DISABLED for the user.');\n    }\n\n    const config = await Statsig.getConfig(user, 'product_pricing_config');\n    console.log('Product pricing level:', config.get('priceLevel', 'standard'));\n\n    Statsig.logEvent(user, 'checkout_completed', 99.99, { currency: 'USD', items: 3 });\n\n  } catch (error) {\n    console.error('Statsig initialization or usage failed:', error);\n  } finally {\n    await Statsig.shutdown(); // Important to call shutdown for graceful exit and event flushing\n  }\n}\n\nrunStatsigExample();","lang":"typescript","description":"Initializes the Statsig SDK, checks a feature gate, fetches a dynamic config, logs an event, and gracefully shuts down. Demonstrates core SDK functionality."},"warnings":[{"fix":"Ensure all timestamps passed to Statsig evaluation logic (e.g., in `StatsigUser` custom properties) are consistently in milliseconds or upgrade to v6.5.1+.","message":"Timestamp evaluation for conditions was previously inconsistent, expecting milliseconds but potentially receiving seconds. This was fixed in v6.5.1.","severity":"breaking","affected_versions":"<6.5.1"},{"fix":"Upgrade to `statsig-node` v6.4.7 or later to benefit from memory leak fixes.","message":"Earlier versions (pre-6.4.7) of the SDK had potential memory leaks due to data not being cleaned up regularly in `StatsigFetcher`.","severity":"gotcha","affected_versions":"<6.4.7"},{"fix":"Upgrade `statsig-node` to v6.4.8 or newer to include the patched `sha.js` dependency and mitigate the security risk.","message":"A security vulnerability was identified in the `sha.js` dependency, which `statsig-node` uses for cryptographic operations. This was patched by upgrading `sha.js` to version 2.4.12.","severity":"breaking","affected_versions":"<6.4.8"},{"fix":"Upgrade to `statsig-node` v6.4.3 or later, which includes a workaround for runtimes without `AbortSignal`.","message":"Versions prior to 6.4.3 had build issues or runtime errors in environments lacking native `AbortSignal` support, affecting fetch operations.","severity":"gotcha","affected_versions":"<6.4.3"},{"fix":"Upgrade to `statsig-node` v6.4.5 or later to ensure secret keys are masked in logs during initialization failures.","message":"When initialization failed in versions prior to 6.4.5, the secret key might have been logged unmasked in network logs, posing a security risk.","severity":"gotcha","affected_versions":"<6.4.5"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `await Statsig.initialize('YOUR_SECRET_KEY');` is called and awaited at the start of your application before any other Statsig SDK methods are invoked.","cause":"Attempted to use `Statsig.checkGate`, `getConfig`, or `logEvent` before `Statsig.initialize` has completed.","error":"Error: Statsig.initialize must be called first."},{"fix":"Use ES module `import { Statsig } from 'statsig-node';` syntax. If using CommonJS, ensure your environment and build tools correctly transpile or interpret named exports, or use `const Statsig = require('statsig-node').Statsig;` if available, though direct named imports are preferred.","cause":"Attempting to import Statsig using CommonJS `require` syntax when the package is primarily designed for ES Modules or when using `new Statsig()` instead of directly calling methods on the imported `Statsig` object.","error":"TypeError: Statsig is not a constructor"},{"fix":"Verify that `YOUR_STATSIG_SERVER_SECRET_KEY` is a valid Statsig server secret key (starting with `secret-`) obtained from your Statsig console, and that no leading/trailing whitespace is present.","cause":"The secret key passed to `Statsig.initialize` is incorrect, malformed, or empty.","error":"Error: Invalid Statsig secret key provided."},{"fix":"Ensure your Node.js environment is v18+ (where `fetch` is native) or provide a global `fetch` polyfill (e.g., `node-fetch`) if running on older Node.js versions or restricted environments.","cause":"The SDK relies on the `fetch` API, which might not be globally available in some older Node.js environments or specific serverless runtimes without polyfills.","error":"TypeError: fetch is not a function"}],"ecosystem":"npm"}