Skip to content

Node.JS SDK Migration Guide

Amplitude's latest Node.js SDK (@amplitude/analytics-node) features a plugin architecture and built-in type definitions. The latest Node.js SDK isn't backwards compatible with the maintenance Node.js SDK @amplitude/node.

To migrate to @amplitude/analytics-node, update your dependencies and instrumentation.


  • @amplitude/node: Maintenance Node.js SDK
  • @amplitude/analytics-node: Latest Node.js SDK


Update package.json to uninstall the maintenance Node.js SDK and install the latest Node.js SDK.

    "dependencies": {
-    "@amplitude/node": "*",
+    "@amplitude/analytics-node": "^1",

Install @amplitude/analytics-node by npm install @amplitude/analytics-node.


The latest Node.js SDK offers an new API to instrument events. To migrate to it, you need to update a few calls. The following sections detail which calls have changed.


The maintenance Node.js SDK only supports namespace import. The latest Node.js SDK supports namespace import (import * as amplitude from '@amplitude/analytics-node') and named import (import { init } from '@amplitude/analytics-node') as well. We are using named import in the examples of latest Node.js SDK in this documentation.

To initialize the SDK, call init(), with a valid Amplitude API Key and configuration parameters.

- import * as Amplitude from '@amplitude/node'
+ import { init } from '@amplitude/analytics-node';

var options = {};
- const client = Amplitude.init(AMPLITUDE_API_KEY, options);
+ init(API_KEY, options);


The latest Node.js SDK configuration comes in a different shape. Some configurations are no longer supported.

@amplitude/node @amplitude/analytics-node
debug logLevel set to WARN level
logLevel logLevel
maxCachedEvents flushQueueSize
retryTimeouts flushMaxRetries can only be set to a number instead of an array of number as in retryTimeouts
optOut optOut
retryClass Not supported. Retry logic is handled internally by latest Node.js SDK
transportClass transportProvider
serverUrl serverUrl
uploadIntervalInSec flushIntervalMillis is in milliseconds while uploadIntervalInSec is in seconds
minIdLength minIdLength
requestTimeoutMillis Not supported
onRetry Not supported. Retry logic is handled internally by the latest Node.js SDK

Tracking events


The logEvent() API maps to track().

+ import { track } from '@amplitude/analytics-node';

const eventProperties = {
    buttonColor: 'primary',

- client.logEvent({
+ track({
  event_type: 'Button Clicked',
  user_id: '',
  event_properties: eventProperties


The flush() API remains the same.

+ import { flush } from '@amplitude/analytics-node';

- client.flush();
+ flush();

Set user properties


The identify() API is very similar but has a different signature. The maintenance Node.js SDK has a signature (userId: string | null, deviceId: string | null, identify: Identify) while the latest Node.js SDK has a signature (identify: Identify, eventOptions?: EventOptions). Learn more about what EventOptions include here.

+ import { identify, Identify } from '@amplitude/analytics-node';

const identifyObj = new Identify();
identifyObj.set('location', 'LAX');

- client.identify('',null,identifyObj);
+ identify(identifyObj, {
+   user_id: '',
+ });


Middlewares map to plugins in the latest Node.js SDK. Here are two types of plugins, enrichment plugins and destination plugins. To learn more about it. Here is an example of logging event information.

+ import { add } from '@amplitude/analytics-node';
+ import { NodeConfig, EnrichmentPlugin, Event, PluginType } from '@amplitude/analytics-types';

- const loggingMiddleware: Middleware = (payload, next) => {
-   console.log(`[amplitude] event=${payload.event} extra=${payload.extra}`);
-   next(payload);

+ export class AddLogEventPlugin implements EnrichmentPlugin {
+   name = 'log-event';
+   type = PluginType.ENRICHMENT as const;
+   config?: NodeConfig;

+   async setup(config: NodeConfig): Promise<undefined> {
+      this.config = config;
+      return;
+   }

+   async execute(event: Event): Promise<Event> {
+     console.log(`[amplitude] event=${event}`);
+     return event;
+   }
+ }

The addEventMiddleware() API maps to add().

+ import { add } from '@amplitude/analytics-node';

- client.addEventMiddleware(new Middleware())
+ add(new Plugin());


This section provides a comparison between different version of SDKs. This overview provides key insights for developers, identifying areas that have significant changes and need careful consideration.


While there are multiple versions of our SDK available, please use the latest version of the SDKs rather than maintenance SDKs. Maintenance versions only provide support and will eventually be deprecated. The latest SDK adopts an aligned architecture, with no extra dependencies, and offers enhanced stability for optimal performance.

Latest Node SDK Maintenance Node SDK
Package @amplitude/analytics-node @amplitude/node
Configuration Configuration is implemented by Configuration object during initialize amplitude. More configurations. Supports specific setter methods. More configurations.
Logger Provider Amplitude Logger. Fully customizable. Amplitude Logger. Not customizable.
Storage Provider LocalStorage by default. Fully customizable. Local Storage.
Customization Plugins Middleware
Retry Regular retry. Regular retry by default. Also provide offline retry. You are able to customize your retry logic. Fully customizable.
Server Endpoint HTTP V2 API HTTP V2 API
Batch API Supported, with configuration. Not supported.

Was this page helpful?