amplitude-js

library8.21.10jsnpmunverified

The `amplitude-js` library is the original JavaScript SDK for integrating web applications with Amplitude Analytics, enabling developers to track user events, user properties, and revenue data. Currently at version 8.21.10, this SDK primarily receives maintenance updates, with new feature development and a TypeScript-first approach now concentrated in the newer `@amplitude/analytics-browser` package. While `amplitude-js` continues to be functional for existing projects, it is no longer recommended for new browser-based instrumentations and has deprecated support for React Native since version 8.0.0, advising migration to `@amplitude/react-native` for cross-platform applications and `@amplitude/node` for server-side environments. Its release cadence has slowed significantly, focusing on bug fixes and dependency upgrades. It differentiates itself as the foundational Amplitude SDK before the introduction of more specialized and modern alternatives.

observability data

npm install amplitude-js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AMPLITUDE-JS

amplitude-js

observabilityjavascriptv8.21.10

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

amplitude (global)

✓  <script type="text/javascript"> amplitude.getInstance().init('YOUR_API_KEY'); </script>

For browser environments, `amplitude-js` is often loaded via a script tag, exposing `amplitude` as a global variable. This is the most common way to use it in traditional web pages.

amplitude (CommonJS)

✓ const amplitude = require('amplitude-js');

✗ import amplitude from 'amplitude-js'; // Incorrect for older Node.js/CommonJS setups

When used in a CommonJS environment (e.g., older Node.js projects or bundlers configured for CJS), the package exports the main Amplitude instance. While modern environments often support ESM, `require` is still a common pattern for this specific SDK due to its legacy nature.

amplitude (ESM)

✓ import amplitude from 'amplitude-js';

✗ const amplitude = require('amplitude-js'); // While technically works in some ESM contexts, prefer 'import'

For modern JavaScript environments with ESM support, the SDK can be imported as a default export. However, developers are strongly encouraged to consider the newer `@amplitude/analytics-browser` for new browser projects, which is TypeScript-first and designed for modern module systems.

This quickstart demonstrates how to initialize the Amplitude SDK, set a user ID and properties, and log two different events with associated properties. It showcases basic event tracking functionality in a browser context.

import amplitude from 'amplitude-js'; // Or const amplitude = require('amplitude-js'); // Initialize Amplitude with your API key // Replace 'YOUR_API_KEY' with your actual Amplitude Project API Key amplitude.getInstance().init('YOUR_API_KEY', null, { includeReferrer: true, includeUtm: true, saveEvents: true, logLevel: 'WARN', // Optional: Configure event upload interval (default is 10 seconds) uploadIntervalMillis: 5000, // Optional: Set the server zone if your project is in the EU // serverZone: 'EU' }); // Set a user ID after initialization amplitude.getInstance().setUserId('user_12345'); // Set user properties amplitude.getInstance().setUserProperties({ plan: 'premium', signup_date: new Date().toISOString(), country: 'USA', }); // Log an event amplitude.getInstance().logEvent('Button Clicked', { button_name: 'Submit Form', form_id: 'contact_form_1', page: window.location.pathname, }); // Log another event after some user interaction setTimeout(() => { amplitude.getInstance().logEvent('Page Viewed', { page_name: 'Product Details', product_id: 'SKU789', category: 'Electronics', }); console.log('Amplitude initialized and events logged. Check your Amplitude dashboard.'); }, 2000);

Debug

Known issues

breakingThe cookie format changed in v6.0 to be more compact. If you use the same Amplitude project across multiple applications and track anonymous users, all `amplitude-js` instances across those applications must be updated simultaneously. Failure to do so will result in anonymous users having different device IDs across your applications, leading to broken user journeys and inaccurate analytics.

fix

Upgrade all instances of `amplitude-js` to version 6.0.0 or higher across all related applications concurrently. Consider using the `cookieForceUpgrade` option if necessary to force all browsers to upgrade and delete old cookies.

affects: >=6.0.0

deprecatedSupport for React Native was removed from `amplitude-js` in version 8.0.0. The SDK is no longer maintained for React Native projects, and using it in such environments will lead to unexpected behavior and missing features.

fix

Migrate your React Native projects to the dedicated `@amplitude/react-native` SDK. Refer to the official Amplitude migration guide for detailed steps.

affects: >=8.0.0

gotchaThe `amplitude-js` library is in maintenance mode, and new feature development is focused on the `@amplitude/analytics-browser` (TypeScript) SDK for web environments. Using `amplitude-js` for new projects means you will miss out on new features, improved developer experience, and better TypeScript support.

fix

For all new browser-based Amplitude instrumentations, use the `@amplitude/analytics-browser` SDK. If you are starting a new React Native project, use `@amplitude/react-native`. For Node.js environments, use `@amplitude/node`.

affects: >=8.0.0

gotchaSetting `flushIntervalMillis` to `0` was previously being overwritten by a default value of 10 seconds due to a bug. This could lead to unexpected delays in event transmission even when immediate flushing was desired.

fix

Upgrade to `amplitude-js` version 8.21.9 or higher to ensure `flushIntervalMillis=0` correctly disables the flush interval and allows for immediate event processing.

affects: <8.21.9

gotchaWhen initiating `amplitude.init()` in `_app.js` within a Next.js application, it can cause 500 errors on pages that use `getServerSideProps` due to potential incompatibilities with Server-Side Rendering.

fix

Avoid calling `amplitude.init()` directly in `_app.js` when using `getServerSideProps`. Instead, initialize the SDK client-side or consider dynamic imports and conditional initialization to ensure it only runs in the browser context for such pages. The `@amplitude/analytics-browser` SDK may offer more robust SSR solutions.

affects: All versions

Errors

Common errors & fixes

Events not showing in Amplitude dashboard

Common causes include incorrect API key during `init()`, network connectivity issues, ad blockers preventing event transmission, or events being queued and not yet flushed to the server.

fix

Verify your API key is correct during `amplitude.getInstance().init()`. Ensure events are being sent (e.g., `uploadIntervalMillis` configuration or `flushQueueSize`). Check browser console for errors or network requests to Amplitude. Use Amplitude's Chrome extension for real-time debugging.

Uncaught TypeError: amplitude.getInstance is not a function

This typically occurs if the Amplitude SDK script has not been loaded or has loaded incorrectly before `amplitude.getInstance()` is called. It can also happen in module environments if `amplitude` is not correctly imported.

fix

Ensure the Amplitude SDK script tag is placed correctly in your HTML (ideally at the end of `<body>` or using `defer`). If using modules, verify `import amplitude from 'amplitude-js';` or `const amplitude = require('amplitude-js');` is at the top of your file and the module resolution is correct.

TypeError: undefined is not an object (evaluating 'e._q.push')

This error, often seen in environments with multiple SDKs or complex bundling, suggests an issue with Amplitude's internal queue mechanism, possibly due to conflicting snippets or incorrect initialization of the global `amplitude` object.

fix

Check for multiple Amplitude snippets loaded on the page. Ensure the Amplitude snippet is loaded only once and initialized correctly. If using the snippet, ensure it's not being overridden. Consider consolidating to a single, consistent loading mechanism (e.g., npm package) if possible.

Amplitude cookie format changed, resulting in new device IDs for returning users.

This is a known breaking change introduced in `amplitude-js` v6.0. If applications using the same Amplitude project are not updated simultaneously, older SDK versions will write cookies in the old format, leading to new device IDs being generated for returning users once they encounter an application with the updated SDK.

fix

Upgrade all client-side applications that share the same Amplitude API key to `amplitude-js` v6.0.0 or newer at the same time to ensure consistent cookie handling. Refer to the migration guide for additional options like `cookieForceUpgrade`.

Upgrade

Version history

8.21.10latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

52 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/amplitude/amplitude-javascript ↗

packagehttps://www.npmjs.com/package/amplitude-js ↗

homepagehttps://amplitude.com ↗