> ## Documentation Index
> Fetch the complete documentation index at: https://statsig-4b2ff144-kill-dead-node-pages.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Node Core SDK Migration Guide

> Migrate from the legacy Node JS Server SDK to the new Node JS Core SDK

export const waitForUserAgentInit_0 = "wait_for_user_agent_init"

export const waitForCountryLookupInit_0 = "wait_for_country_lookup_init"

export const disableUserAgentParsing_0 = "disable_user_agent_parsing"

export const disableCountryLookup_0 = "disable_country_lookup"

export const enableIdLists_0 = "enable_id_lists"

export const sdkType_0 = "Node JS"

## Why Migrate?

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

## Installation

<CodeGroup>
  ```bash Node Core theme={null}
  npm install @statsig/statsig-node-core
  ```

  ```bash Node Legacy theme={null}
  npm install statsig-node
  ```
</CodeGroup>

## StatsigUser

In the Node Core SDK, `StatsigUser` is now a class instead of a type interface.

<CodeGroup>
  ```javascript Node Core theme={null}
  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"
      }
  })
  ```

  ```javascript Node Legacy theme={null}
  import type {StatsigUser} from "statsig-node"

  const user = {
      userID: "user_123",
      email: "user@example.com",
      ip: "192.168.0.1",
      userAgent: "Mozilla/5.0",
      country: "US",
      custom: {
          "subscription_level": "premium"
      }
  }
  ```
</CodeGroup>

## API Changes

### Key Package and Class Changes

| Feature        | Node Core SDK                                        | Legacy Node SDK                            | Status                        |
| -------------- | ---------------------------------------------------- | ------------------------------------------ | ----------------------------- |
| Package        | `@statsig/statsig-node-core`                         | `statsig-node`                             | ⚠️ Renamed                    |
| Import         | `import {Statsig} from '@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.checkGate()`                                | `statsig.checkGate()`                      | ✓ Same                        |
| Get Config     | `statsig.getDynamicConfig()`                         | `statsig.getConfig()`                      | ⚠️ Renamed                    |
| Get Experiment | `statsig.getExperiment()`                            | `statsig.getExperiment()`                  | ✓ Same                        |
| Get Layer      | `statsig.getLayer()`                                 | `statsig.getLayer()`                       | ✓ Same                        |
| Log Event      | `statsig.logEvent()`                                 | `statsig.logEvent()`                       | ✓ Same                        |
| Shutdown       | `await statsig.shutdown()`                           | `await statsig.shutdown()`                 | ✓ Same                        |

For more details on the new API, see [Node Core SDK documentation](/server-core/node-core).

## Behavioral Changes

<AccordionGroup>
  <Accordion title="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](https://github.com/statsig-io/statsig-server-core/blob/00ad0e4024ca5d30f21892c8f2f23e836165a509/statsig-rust/resources/ua_parser_regex_lite.yaml#L4).

    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.
  </Accordion>

  <Accordion title="Lazy Initialization: User-Agent Parser & Country Lookup">
    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:

    * {waitForUserAgentInit_0}
    * {waitForCountryLookupInit_0}

    ⚠️ Enabling these options will increase total initialization time.

    To **disable** these features entirely, set the `StatsigOptions` flags {disableUserAgentParsing_0} and {disableCountryLookup_0}.
  </Accordion>

  <Accordion title="ID List Feature">
    The ID List functionality is **disabled by default**.

    To enable it, set the `StatsigOptions` flag {enableIdLists_0}.
  </Accordion>

  <Accordion title="Endpoint Changes (v1 to 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.
  </Accordion>

  <Accordion title="DataStore cache format">
    \*\* 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.
  </Accordion>
</AccordionGroup>

## 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                                                        |
| `observability_client`, `sdk_error_callback`                                               | Now within `observability_client` interface                                                  |
| `logger`                                                                                   | Now `OutputLoggerProvider` interface                                                         |
| `bootstrap_values`, `evaluation_callback`, `rules_updated_callback`                        | Not yet supported                                                                            |

## Recommended Migration Path

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Test Thoroughly">
    * Verify that all of your configs are successfully migrated - run your test suites end-to-end.
  </Step>

  <Step title="Remove old SDK">
    * Remove references to the old SDK, and clean up old initialization and import logic.
  </Step>
</Steps>

## Need Help?

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

* [Statsig Slack Community](https://statsig.com/slack)
* [GitHub Issues](https://github.com/statsig-io/statsig-server-core/issues)