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.

```json
{
  "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.

```js
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.

| @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. The latest Node.js SDK handles retry logic internally                              |
| `transportClass`       | `transportProvider`                                                                               |
| `serverUrl`            | `serverUrl`                                                                                       |
| `uploadIntervalInSec`  | `flushIntervalMillis` is in milliseconds while `uploadIntervalInSec` is in seconds                |
| `minIdLength`          | `minIdLength`                                                                                     |
| `requestTimeoutMillis` | Not supported                                                                                     |
| `onRetry`              | Not supported. The latest Node.js SDK handles retry logic internally                              |

### Log event

The `logEvent()` API maps to `track()`.

```js
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.

```js
import { flush } from "@amplitude/analytics-node";

client.flush();
flush();
```

### Identify

The `identify()` API uses a different signature. The [maintenance Node.js SDK](https://github.com/amplitude/Amplitude-Node/blob/2ef295e1fb698286d606ea4a2ccbbfdc4ba3fdc8/packages/node/src/nodeClient.ts#L142) signature is `(userId: string | null, deviceId: string | null, identify: Identify)`. The [latest Node.js SDK](https://github.com/amplitude/Amplitude-TypeScript/blob/8f4ea010279fb21190a2c0595d4ae8a7d9e987ce/packages/analytics-core/src/core-client.ts#L62) signature is `(identify: Identify, eventOptions?: EventOptions)`. For details on `EventOptions`, refer to the [EventOptions reference](https://amplitude.github.io/Amplitude-TypeScript/interfaces/_amplitude_analytics_node.Types.EventOptions.html).

```js
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](/docs/sdks/analytics/node/node-js-sdk#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.

```js
+ 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()`.

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

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