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.

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

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

Instrumentation

The latest Node.js SDK offers a new API to instrument events. To migrate to it, 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 both namespace import (import * as amplitude from '@amplitude/analytics-node') and named import (import { init } from '@amplitude/analytics-node'). The examples in this documentation use named import.

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 uses a different configuration shape. The latest Node.js SDK no longer supports some configuration options.

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 uses a different signature. The maintenance Node.js SDK signature is (userId: string | null, deviceId: string | null, identify: Identify). The latest Node.js SDK signature is (identify: Identify, eventOptions?: EventOptions). For details on EventOptions, refer to the EventOptions reference.

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. The latest Node.js SDK supports two plugin types: enrichment plugins and destination plugins. The following example logs 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());