Node Core SDK Migration Guide

This guide will help you migrate from the legacy Node JS Server SDK to the new Node JS Core SDK. The Node JS Core SDK offers significant performance improvements and new features, as it's built on a shared Rust core library.

Why Migrate?

• Performance: Node JS Core evaluates faster than the legacy SDK
• New Features: Access to Parameter Stores, CMAB (Contextual Multi-Armed Bandits), observabilityClient, and more
• Future Support: All new features and improvements will only be available in Node JS Core
• Maintenance: The legacy Node JS SDK is in maintenance mode and will only receive critical bug fixes

Installation

New Installation

npm install @statsig/statsig-node-core

Legacy Installation

npm install statsig-node

StatsigUser

New User Creation

import {StatsigUser} from "@statsig/statsig-node-core"
const user = new StatsigUser({
    userID: "user_123",
    email: "user@example.com",
    ip: "192.168.0.1",
    userAgent: "Mozilla/5.0",
    country: "US",
    custom={
    "subscription_level": "premium"
    }
})

Legacy User Creation

import type {StatsigUser} from "statsig-node"
user = {
    userID: "user_123",
    email: "user@example.com",
    ip: "192.168.0.1",
    userAgent: "Mozilla/5.0",
    country: "US",
    custom={
    "subscription_level": "premium"
    }
}

API Changes

Key Package and Class Changes

Feature	Node Core SDK	Legacy Node SDK	Status
Package	statsig-node-core	statsig-node	⚠️ Renamed
Import	import {Statsig} '@statsig/statsig-node-core'	const Statsig = require("statsig-node");	⚠️ Change
Options	StatsigOptions	StatsigOptions	✓ Same
User	StatsigUser	StatsigUser	⚠️ Changed from type to class
Initialize	await statsig.initialize()	await statsig.initialize()	Same
Check Gate	statsig.check_gate()	statsig.check_gate()	✓ Same
Get Config	statsig.get_dynamic_config()	statsig.get_config()	⚠️ Renamed
Get Experiment	statsig.get_experiment()	statsig.get_experiment()	✓ Same
Get Layer	statsig.get_layer()	statsig.get_layer()	✓ Same
Log Event	statsig.log_event()	statsig.log_event()	✓ Same
Shutdown	await statsig.shutdown()	await statsig.shutdown()	Same

For more details on the new API, see Python Core SDK documentation.

Behavioral Changes

User-Agent Parsing

• The SDK now uses a lightweight YAML-based User-Agent parser based on a reduced version of the ua-parser regex definitions.
• This parser supports the following commonly used browsers:
  • Chrome
  • Firefox / Firefox Mobile
  • Safari / Mobile Safari
  • Chrome Mobile
  • Android
  • Edge / Edge Mobile
  • IE Mobile
  • Opera Mobile
• If your use case requires identifying less common browsers, you should parse the User-Agent externally before sending it to Statsig.

Lazy Initialization: User-Agent Parser & Country Lookup

• Country lookup and third-party ua parsersare now lazy-loaded by default to improve SDK initialization performance.
• If your application relies on these features being ready immediately after initialize(), you can opt in by setting:
  • wait_for_user_agent_init
  • wait_for_country_lookup_init
• ⚠️ Enabling these options will increase total initialization time.
• To disable these features entirely, use the following StatsigOptions flags:
  • disable_user_agent_parsing
  • disable_country_lookup

ID List Feature

• The ID List functionality is disabled by default.
• To enable it, set the following in your StatsigOptions:
  • enable_id_lists

Endpoint Changes (v1 → v2)

• The core SDK now fetches configuration specs from a new endpoint:
  • Old: v1/download_config_specs
  • New: v2/download_config_specs
• If you are hosting your own pass-through proxy, ensure it supports and correctly routes the v2 endpoint.
• If you are using the Statsig Forward Proxy (SFP), this endpoint migration is handled automatically.

** New DataStore cache format**

• Old: (Except Node v6+)
  • config_spec cahce key is: statsig.cache
  • IDLists statsig.id_lists
• New
  • config_spec cache key: statsig|/v2/download_config_specs|plain_text|{SHA256HashedBase64(secretkey)}
  • IDLists: We don't support idlist data store.

StatsigOptions Changes

The table below shows the mapping between legacy SDK options and Server Core SDK options:

Old Option	New / Notes
api	Deprecated
idlists_thread_limit, logging_interval, enable_debug_logs, events_flushed_callback	Deprecated
timeout	Deprecated (was only for network)
apiForDownloadConfigSpecs	specsUrl – must complete with endpoint
apiForIdLists	idListsUrl – must complete with endpoint
apiForLogEvent	logEventUrl – must complete with endpoint
initTimeoutMs	initTimeoutMs – applies to overall initialization (suggest adding +1000 ms if enabling UA)
rulesetsSyncIntervalMs	specsSyncIntervalMs (unit: milliseconds)
idListsSyncIntervalMs	idListsSyncIntervalMs (unit: milliseconds)
loggingIntervalMs	eventLoggingFlushIntervalMs
loggingMaxBufferSize	eventLoggingMaxQueuesize
dataAdapter	Still supported but interface changed
initTimeoutMs	Apply to overall initialize timeout
observability_client, sdk_error_callback	Now within observability_client interface
logger	Now OutputLoggerProvider interface
bootstrap_values, evaluation_callback, rules_updated_callback	Not yet supported

Need Help?

If you encounter any issues during migration, please reach out to us:

• Statsig Slack Community
• GitHub Issues