The `amplitude` package provides a server-side Node.js wrapper for Amplitude's HTTP API, facilitating event tracking and user identification. Currently at stable version 6.0.0, this library integrates with Amplitude's V2 HTTP API for sending analytics data. It supports both individual event tracking and batch submissions, and includes functionality for Amplitude's Identify API to manage user properties without event logging. A notable feature is its built-in handling for Amplitude's past SSL certificate issues, allowing users to configure an alternative endpoint if needed. The package ships with TypeScript type definitions, ensuring type safety for TypeScript projects. While its release cadence isn't extremely rapid, updates address API changes and maintain compatibility with modern Node.js environments.
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Amplitude
✓ import { Amplitude } from 'amplitude';
✗ const Amplitude = require('amplitude').default;
For ESM projects, use named import. The package ships TypeScript types.
Amplitude (CommonJS)
✓ const Amplitude = require('amplitude');
CommonJS syntax for Node.js environments. This is demonstrated in the package's basic initialization.
Amplitude instance
✓ const amplitude = new Amplitude(process.env.AMPLITUDE_API_TOKEN ?? '');
The API token is the only required field for initialization. It's recommended to retrieve it from environment variables.
This quickstart demonstrates how to initialize the Amplitude client, track a single user event, and update user properties using the Identify API. It emphasizes using environment variables for the API token.
import { Amplitude } from 'amplitude';
const AMPLITUDE_API_TOKEN = process.env.AMPLITUDE_API_TOKEN ?? '';
if (!AMPLITUDE_API_TOKEN) {
console.error('AMPLITUDE_API_TOKEN environment variable is not set.');
process.exit(1);
}
const amplitude = new Amplitude(AMPLITUDE_API_TOKEN, {
// Optionally configure a custom endpoint if needed, e.g., for self-hosted proxies or past SSL issues
// tokenEndpoint: 'https://api2.amplitude.com'
});
async function trackUserEvent() {
try {
const eventData = {
event_type: 'User Registered',
user_id: 'user-12345',
event_properties: {
plan: 'premium',
signup_method: 'email'
},
user_properties: {
is_new_user: true
}
};
console.log('Tracking event:', eventData);
const response = await amplitude.track(eventData);
console.log('Amplitude track response:', response.status);
const identifyData = {
user_id: 'user-12345',
user_properties: {
$set: { last_activity: new Date().toISOString() },
$add: { login_count: 1 }
}
};
console.log('Identifying user properties:', identifyData);
const identifyResponse = await amplitude.identify(identifyData);
console.log('Amplitude identify response:', identifyResponse.status);
} catch (error: any) {
console.error('Failed to track event or identify user:', error.message);
}
}
trackUserEvent();
Errors
Common errors & fixes
Amplitude error: user_id and device_id cannot be null or empty and must be 5 or more characters.
The `user_id` or `device_id` provided in the event payload is either missing, empty, or less than 5 characters long, which is a requirement for Amplitude's V2 API.
fixEnsure that every event payload includes either a `user_id` or a `device_id`, and that its value is a string of 5 or more characters. Example: `user_id: 'user-abcde'`.
Amplitude error: Missing required field event_type.
The `event_type` field is mandatory for all events sent to Amplitude's `track` method.
fixAdd an `event_type` string to your event data object, e.g., `{ event_type: 'Product Viewed' }`. TypeError: Amplitude is not a constructor
This typically occurs in ESM contexts when attempting to use `require('amplitude')` directly or in CJS contexts if trying to destructure a non-existent default export.
fixFor ESM, use `import { Amplitude } from 'amplitude';`. For CommonJS, use `const Amplitude = require('amplitude');`. Audit
Dependencies
No dependency data recorded yet.