Statsig Edge Config Adapter for Node.js

Common errors

• Error: Missing Edge Config connection string. Make sure to set EDGE_CONFIG_CONNECTION_STRING in your environment variables.

  cause The `@vercel/edge-config` client could not be initialized because the `EDGE_CONFIG_CONNECTION_STRING` environment variable was not found.
  fix Set the `EDGE_CONFIG_CONNECTION_STRING` environment variable in your Vercel project or local development environment. This string is provided by Vercel for your Edge Config.

• Statsig data not found in Edge Config for key: [YOUR_ITEM_KEY]

  cause The `EdgeConfigDataAdapter` was initialized with an `edgeConfigItemKey` that does not correspond to any valid Statsig data item within your Vercel Edge Config.
  fix Verify that the `edgeConfigItemKey` passed to `EdgeConfigDataAdapter` is correct and that the Statsig Vercel Integration has been successfully installed and populated data into your Edge Config instance.

• TypeError: Cannot read properties of undefined (reading 'initialize')

  cause The `statsig` object was undefined, indicating the `statsig-node` SDK was not correctly imported or initialized before being used.
  fix Ensure `import statsig from 'statsig-node';` is at the top of your file and that `await statsig.initialize()` is called before any other Statsig functions.

Warnings

• breaking The `0.4.0` release removed the need for manual JSON stringification/parsing. Previously, users might have manually `JSON.stringify` values before passing them to the adapter or `JSON.parse` values received. This is no longer necessary, as the adapter now directly passes object values.
  Fix: Remove any manual `JSON.stringify` or `JSON.parse` calls when interacting with data fetched via `EdgeConfigDataAdapter`. The adapter handles object serialization/deserialization automatically.
• gotcha When using `EdgeConfigDataAdapter`, it is recommended to set `initStrategyForIDLists: 'none'` and `disableIdListsSync: true` in the Statsig SDK initialization options. Omitting these will cause a blocking network call to fetch ID lists during initialization, potentially impacting cold start performance.
  Fix: Ensure `initStrategyForIDLists: 'none'` and `disableIdListsSync: true` are included in the Statsig initialization options. If immediate ID list evaluation is critical on startup, consider the performance implications or pre-warm your Edge Config.
• gotcha The `edgeConfigItemKey` is a crucial identifier linking your adapter to the correct item in Vercel Edge Config. A misconfigured key will result in the adapter failing to fetch Statsig data.
  Fix: Double-check that the `edgeConfigItemKey` provided to `EdgeConfigDataAdapter` precisely matches the key generated during the Statsig Vercel Integration installation in your Vercel project settings (e.g., 'statsig-5FSfBpWM9kUPqeKRlZPkod').

Install

• npm install statsig-node-vercel npm
• yarn add statsig-node-vercel yarn
• pnpm add statsig-node-vercel pnpm

Imports

• EdgeConfigDataAdapter
  wrong:

  const { EdgeConfigDataAdapter } = require('statsig-node-vercel');

  correct:

  import { EdgeConfigDataAdapter } from 'statsig-node-vercel';

  Primarily designed for ESM environments; CommonJS `require` might work with transpilation but isn't the idiomatic import.
• createClient
  wrong:

  const { createClient } = require('@vercel/edge-config');

  correct:

  import { createClient } from '@vercel/edge-config';

  This is an import from the peer dependency `@vercel/edge-config`, crucial for initializing the Edge Config client.
• StatsigServer
  wrong:

  import { StatsigServer } from 'statsig-node';

  correct:

  import statsig from 'statsig-node';

  The main Statsig SDK is typically imported as a default export `statsig` (or `Statsig` if using a different casing convention).

Quickstart

This quickstart demonstrates how to initialize the Statsig Node.js SDK using the Vercel Edge Config adapter, showing setup, environment variable usage, and a basic feature gate check.

import { EdgeConfigDataAdapter } from 'statsig-node-vercel';
import { createClient } from '@vercel/edge-config';
import statsig from 'statsig-node';

async function initializeStatsigWithVercel() {
  const edgeConfigClient = createClient(process.env.EDGE_CONFIG_CONNECTION_STRING ?? '');
  
  if (!process.env.EDGE_CONFIG_CONNECTION_STRING) {
    console.error('EDGE_CONFIG_CONNECTION_STRING is not set. Please configure your Vercel Edge Config.');
    return;
  }

  const dataAdapter = new EdgeConfigDataAdapter({
    edgeConfigClient: edgeConfigClient,
    edgeConfigItemKey: process.env.STATSIG_EDGE_CONFIG_ITEM_KEY ?? 'statsig-ITEM_KEY',
  });

  if (!process.env.STATSIG_SERVER_SECRET_KEY) {
    console.error('STATSIG_SERVER_SECRET_KEY is not set. Please provide your Statsig server secret key.');
    return;
  }

  await statsig.initialize(process.env.STATSIG_SERVER_SECRET_KEY, {
    dataAdapter: dataAdapter,
    // These options are recommended for optimal performance with Edge Config
    // to avoid blocking network calls for ID Lists on initialization.
    // Omit if you need ID list evaluation immediately on init.
    initStrategyForIDLists: 'none',
    disableIdListsSync: true
  });

  console.log('Statsig initialized successfully with Vercel Edge Config!');

  // Example: Check a feature gate
  const user = { userID: 'test-user-123' };
  const gateResult = await statsig.checkGate(user, 'a_feature_gate');
  console.log(`Feature gate 'a_feature_gate' for user ${user.userID}: ${gateResult}`);

  statsig.shutdown();
}

initializeStatsigWithVercel().catch(console.error);