{"id":17494,"library":"amplitude","title":"Amplitude Node.js Wrapper","description":"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.","status":"active","version":"6.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/geoffdutton/amplitude","tags":["javascript","analytics","amplitude","typescript"],"install":[{"cmd":"npm install amplitude","lang":"bash","label":"npm"},{"cmd":"yarn add amplitude","lang":"bash","label":"yarn"},{"cmd":"pnpm add amplitude","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For ESM projects, use named import. The package ships TypeScript types.","wrong":"const Amplitude = require('amplitude').default;","symbol":"Amplitude","correct":"import { Amplitude } from 'amplitude';"},{"note":"CommonJS syntax for Node.js environments. This is demonstrated in the package's basic initialization.","symbol":"Amplitude (CommonJS)","correct":"const Amplitude = require('amplitude');"},{"note":"The API token is the only required field for initialization. It's recommended to retrieve it from environment variables.","symbol":"Amplitude instance","correct":"const amplitude = new Amplitude(process.env.AMPLITUDE_API_TOKEN ?? '');"}],"quickstart":{"code":"import { Amplitude } from 'amplitude';\n\nconst AMPLITUDE_API_TOKEN = process.env.AMPLITUDE_API_TOKEN ?? '';\n\nif (!AMPLITUDE_API_TOKEN) {\n  console.error('AMPLITUDE_API_TOKEN environment variable is not set.');\n  process.exit(1);\n}\n\nconst amplitude = new Amplitude(AMPLITUDE_API_TOKEN, {\n  // Optionally configure a custom endpoint if needed, e.g., for self-hosted proxies or past SSL issues\n  // tokenEndpoint: 'https://api2.amplitude.com'\n});\n\nasync function trackUserEvent() {\n  try {\n    const eventData = {\n      event_type: 'User Registered',\n      user_id: 'user-12345',\n      event_properties: {\n        plan: 'premium',\n        signup_method: 'email'\n      },\n      user_properties: {\n        is_new_user: true\n      }\n    };\n    console.log('Tracking event:', eventData);\n    const response = await amplitude.track(eventData);\n    console.log('Amplitude track response:', response.status);\n\n    const identifyData = {\n      user_id: 'user-12345',\n      user_properties: {\n        $set: { last_activity: new Date().toISOString() },\n        $add: { login_count: 1 }\n      }\n    };\n    console.log('Identifying user properties:', identifyData);\n    const identifyResponse = await amplitude.identify(identifyData);\n    console.log('Amplitude identify response:', identifyResponse.status);\n\n  } catch (error: any) {\n    console.error('Failed to track event or identify user:', error.message);\n  }\n}\n\ntrackUserEvent();","lang":"typescript","description":"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."},"warnings":[{"fix":"Consult Amplitude's HTTP API V2 documentation for required fields and data format. Specifically, ensure `event_type` and either `user_id` or `device_id` are present.","message":"Version 5.0.0 and above of this package migrated to Amplitude's V2 HTTP API. This change might require reviewing and updating event payload structures to conform to the V2 specification, especially regarding required fields and data types.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Ensure all `user_id` and `device_id` values passed to `amplitude.track()` or `amplitude.identify()` are at least 5 characters long.","message":"Since version 5.0.0, both `user_id` and `device_id` fields, when provided in an event payload, must contain a minimum of 5 characters. Events with shorter IDs will be rejected by the Amplitude API.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"If encountering connection issues, particularly SSL-related, try setting `AMPLITUDE_TOKEN_ENDPOINT='https://api2.amplitude.com'` environment variable or passing `{ tokenEndpoint: 'https://api2.amplitude.com' }` to the `Amplitude` constructor.","message":"In 2020, Amplitude experienced SSL certificate issues affecting some clients. While Amplitude likely resolved this on their end, the package provides a `tokenEndpoint` configuration option or `AMPLITUDE_TOKEN_ENDPOINT` environment variable to use an alternative endpoint (`https://api2.amplitude.com`). This is useful for specific network configurations or if similar issues re-emerge.","severity":"gotcha","affected_versions":">=5.1.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure 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'`.","cause":"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.","error":"Amplitude error: user_id and device_id cannot be null or empty and must be 5 or more characters."},{"fix":"Add an `event_type` string to your event data object, e.g., `{ event_type: 'Product Viewed' }`.","cause":"The `event_type` field is mandatory for all events sent to Amplitude's `track` method.","error":"Amplitude error: Missing required field event_type."},{"fix":"For ESM, use `import { Amplitude } from 'amplitude';`. For CommonJS, use `const Amplitude = require('amplitude');`.","cause":"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.","error":"TypeError: Amplitude is not a constructor"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}