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

Dependency¶

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.

Tracking events¶

logEvent()¶

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

Set user properties¶

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

Comparison¶

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.