Node.js SDK Migration Guide

SDK Comparison

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

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.

Terminology

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

Dependencies

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.

Instrumentation

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.

Initialization

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);

Configuration

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

Log event

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: 'user@amplitude.com',
  event_properties: eventProperties
});

Flush

The flush() API remains the same.

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

client.flush(); 
flush();

Identify

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('user@amplitude.com',null,identifyObj); 
identify(identifyObj, { 
user_id: 'user@amplitude.com',
});

Middleware

Middlewares map to plugins in the latest Node.js SDK. Here are two types of plugins, enrichment plugins and destination plugins. 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());