statsig-io · brock-statsig · Oct 18, 2025 · Oct 18, 2025
diff --git a/docs/server-core/MigrationGuideTemplates/_GlobalChanges.mdx b/docs/server-core/MigrationGuideTemplates/_GlobalChanges.mdx
@@ -16,7 +16,7 @@
 
 **Lazy Initialization: User-Agent Parser & Country Lookup**
 
-- User-Agent parsing and country lookup are now **lazy-loaded by default** to improve SDK initialization performance.
+- 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:
   - <code>{props.waitForUserAgentInit || 'wait_for_user_agent_init'}</code>
   - <code>{props.waitForCountryLookupInit || 'wait_for_country_lookup_init'}</code>
@@ -37,4 +37,12 @@
   - **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.
+- 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. 
diff --git a/docs/server-core/node-core.mdx b/docs/server-core/node-core.mdx
@@ -26,6 +26,7 @@ import {
   FieldsNeededMethods,
   ClientInitResponse,
   EventSubscriptions,
+  MigrationGuide,
 } from "./Templates/index.mdx";
 
 import Preamble from "./_preamble.mdx";
@@ -71,6 +72,13 @@ export const Builder = SDKDocsBuilder({
         initialize: <Initialize />,
       },
     ],
+    [
+      MigrationGuide,
+      {
+        link: "/server-core/node/migration-guide",
+        sdkType: "Node",
+      },
+    ],
     [
       WorkingWith,
       {

diff --git a/docs/server-core/node/migration-guide/_api_changes.mdx b/docs/server-core/node/migration-guide/_api_changes.mdx
@@ -0,0 +1,20 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+### 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](/server-core/python-core).
diff --git a/docs/server-core/node/migration-guide/_statsig_options.mdx b/docs/server-core/node/migration-guide/_statsig_options.mdx
@@ -0,0 +1,18 @@
+| 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                                                                            |
diff --git a/docs/server-core/node/migration-guide/_user_creation.mdx b/docs/server-core/node/migration-guide/_user_creation.mdx
@@ -0,0 +1,39 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+User creation is still the same in the new python core SDK.
+
+<Tabs>
+  <TabItem value="new" label="New User Creation" default>
+    ```python
+    from statsig_python_core import *
+
+    user = StatsigUser(
+        user_id="user_123",
+        email="user@example.com",
+        ip="192.168.0.1",
+        user_agent="Mozilla/5.0",
+        country="US",
+        custom={
+            "subscription_level": "premium"
+        }
+    )
+    ```
+  </TabItem>
+  <TabItem value="legacy" label="Legacy User Creation">
+    ```python
+    from statsig import StatsigUser
+
+    user = StatsigUser(
+        user_id="user_123",
+        email="user@example.com",
+        ip="192.168.0.1",
+        user_agent="Mozilla/5.0",
+        country="US",
+        custom={
+            "subscription_level": "premium"
+        }
+    )
+    ```
+  </TabItem>
+</Tabs>
diff --git a/docs/server-core/node/migration-guide/index.mdx b/docs/server-core/node/migration-guide/index.mdx
@@ -0,0 +1,104 @@
+---
+title: Node Core SDK Migration Guide
+displayed_sidebar: api
+---
+
+import CodeBlock from '@theme/CodeBlock';
+import {
+  SDKDocsBuilder,
+} from "../../../sdks/_SDKDocsBuilder.mdx";
+
+import {
+    APIChanges,
+    GlobalChanges,
+    Installation,
+    MigrationHelp,
+    StatsigOptions,
+    UserCreation,
+    NeedHelp,
+    Troubleshooting,
+    Intro,
+} from "../../MigrationGuideTemplates/index.mdx";
+import NodeAPIChanges from "./_api_changes.mdx";
+import NodeUserCreation from "./_user_creation.mdx";
+import NodeStatsigOptions from "./_statsig_options.mdx";
+
+export const Builder = SDKDocsBuilder({
+  sections: [
+    [
+      Intro,
+      {
+        sdkType: "Node JS",
+      },
+    ],
+
+    [
+      Installation,
+      {
+        legacyInstall: <CodeBlock>npm install statsig-node</CodeBlock>,
+        install: <CodeBlock>npm install @statsig/statsig-node-core</CodeBlock>,
+      },
+    ],
+    [
+      UserCreation,
+      {
+        newUserCreation: <CodeBlock language="nodejs">
+{`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"
+    }
+})
+`}</CodeBlock>,
+        legacyUserCreation: <CodeBlock language="python">
+{`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"
+    }
+}
+`}</CodeBlock>,
+}
+],
+[
+APIChanges,
+{
+apiChanges: <NodeAPIChanges />
+}
+],
+[
+GlobalChanges,
+{
+waitForUserAgentInit: "wait_for_user_agent_init",
+waitForCountryLookupInit: "wait_for_country_lookup_init",
+disableUserAgentParsing: "disable_user_agent_parsing",
+disableCountryLookup: "disable_country_lookup",
+enableIdLists: "enable_id_lists"
+},
+],
+[
+StatsigOptions,
+{
+optionsMapping: <NodeStatsigOptions />
+}
+],
+[
+NeedHelp,
+{}
+],
+]
+})
+
+export const toc = Builder.toc;
+
+<>{Builder.result}</>