Skip to main content

​
Why Migrate?

  • Performance: 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 Core
  • Maintenance: The legacy SDK is in maintenance mode and will only receive critical bug fixes

​
Installation

npm install @statsig/statsig-node-core

​
StatsigUser

In the Node Core SDK, StatsigUser is now a class instead of a type interface. 
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"
    }
})

​
API Changes

​
Key Package and Class Changes

FeatureNode Core SDKLegacy Node SDKStatus
Package@statsig/statsig-node-corestatsig-node⚠️ Renamed
Importimport {Statsig} from '@statsig/statsig-node-core'const Statsig = require("statsig-node");⚠️ Change
OptionsStatsigOptionsStatsigOptions✓ Same
UserStatsigUserStatsigUser⚠️ Changed from type to class
Initializeawait statsig.initialize()await statsig.initialize()✓ Same
Check Gatestatsig.checkGate()statsig.checkGate()✓ Same
Get Configstatsig.getDynamicConfig()statsig.getConfig()⚠️ Renamed
Get Experimentstatsig.getExperiment()statsig.getExperiment()✓ Same
Get Layerstatsig.getLayer()statsig.getLayer()✓ Same
Log Eventstatsig.logEvent()statsig.logEvent()✓ Same
Shutdownawait statsig.shutdown()await statsig.shutdown()✓ Same
For more details on the new API, see Node Core SDK documentation.

​
Behavioral Changes

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.
User-Agent parsing and country lookup are 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:⚠️ Enabling these options will increase total initialization time.To disable these features entirely, set the StatsigOptions flags and .
The ID List functionality is disabled by default.To enable it, set the StatsigOptions flag .
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 cache 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 OptionNew / Notes
apiDeprecated
idlists_thread_limit, logging_interval, enable_debug_logs, events_flushed_callbackDeprecated
timeoutDeprecated (was only for network)
apiForDownloadConfigSpecsspecsUrl – must complete with endpoint
apiForIdListsidListsUrl – must complete with endpoint
apiForLogEventlogEventUrl – must complete with endpoint
initTimeoutMsinitTimeoutMs – applies to overall initialization (suggest adding +1000 ms if enabling UA)
rulesetsSyncIntervalMsspecsSyncIntervalMs (unit: milliseconds)
idListsSyncIntervalMsidListsSyncIntervalMs (unit: milliseconds)
loggingIntervalMseventLoggingFlushIntervalMs
loggingMaxBufferSizeeventLoggingMaxQueuesize
dataAdapterStill supported but interface changed
observability_client, sdk_error_callbackNow within observability_client interface
loggerNow OutputLoggerProvider interface
bootstrap_values, evaluation_callback, rules_updated_callbackNot yet supported
1

Add the new Dependencies

  • Add the new SDK package/module and any required platform-specific dependencies for your environment.
  • Update import or require statements to reference the new SDK namespace or module.
  • For now - keep the old package in-place, it can be helpful to have both running in parallel momentarily during local testing for your upgrade. If needed (language dependent), you may want to alias the new package.
2

Update Initialization

  • Switch to the new initialization syntax. New SDK keys aren’t needed - if you choose to update them, ensure they have the same target apps.
  • If needed, use the appropriate builder or configuration pattern for setting options, and ensure you migrate the StatsigOptions you use, as some were renamed.
3

Update User Creation

  • Migrate to the new format for creating user objects.
  • If needed, use the builder pattern or updated constructor to set user properties.
4

Update Method Calls

  • Starting with a few calls, switch your config checks from the new to old SDK, replacing oldStatsig.getExperiment() with newStatsig.getExperiment()
  • As you change the package usage, conduct some testing of your service locally or with existing test patterns, to build confidence in the new SDK’s operation.
  • As you migrate additional calls, update method names if they’ve changed (notably, get_config() to get_dynamic_config)
  • Once comfortable with the operation of the new SDK from call-by-call migration, consider the use of refactoring tools to migrate the bulk of your remaining calls.
5

Test Thoroughly

  • Verify that all of your configs are successfully migrated - run your test suites end-to-end.
6

Remove old SDK

  • Remove references to the old SDK, and clean up old initialization and import logic.

​
Need Help?

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