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.

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.

1{
2  "dependencies": {
-    "@amplitude/node": "*", 
+    "@amplitude/analytics-node": "^1", 
5  }
6}

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'; 
3 
4var 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.

Log event

The logEvent() API maps to track().

 +import { track } from '@amplitude/analytics-node'; 
 2 
 3const eventProperties = {
 4    buttonColor: 'primary',
 5};
 6 
 -client.logEvent({ 
 +track({ 
 +  event_type: 'Button Clicked',
 +  user_id: 'user@amplitude.com',
 +  event_properties: eventProperties
12});

Flush

The flush() API remains the same.

+import { flush } from '@amplitude/analytics-node'; 
2 
-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'; 
2 
3const identifyObj = new Identify();
4identifyObj.set('location', 'LAX');
5 
-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';
 3 
 -- const loggingMiddleware: Middleware = (payload, next) => { 
 -- console.log(`[amplitude] event=${payload.event} extra=${payload.extra}`);
 -- next(payload);
 7}
 8 
 ++ export class AddLogEventPlugin implements EnrichmentPlugin { 
 ++ name = 'log-event';
 ++ type = PluginType.ENRICHMENT as const;
 ++ config?: NodeConfig;
13 
 ++ async setup(config: NodeConfig): Promise<undefined> { 
 ++ this.config = config;
 ++ return;
 ++ }
18 
 ++ 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'; 
2 
-- client.addEventMiddleware(new Middleware()) 
++ add(new Plugin());