{"id":10501,"library":"amplitude-js","title":"Amplitude JavaScript SDK (Legacy)","description":"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.","status":"maintenance","version":"8.21.10","language":"javascript","source_language":"en","source_url":"https://github.com/amplitude/amplitude-javascript","tags":["javascript","analytics","amplitude"],"install":[{"cmd":"npm install amplitude-js","lang":"bash","label":"npm"},{"cmd":"yarn add amplitude-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add amplitude-js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","symbol":"amplitude (global)","correct":"<!-- loaded via script tag -->\n<script type=\"text/javascript\">\n  amplitude.getInstance().init('YOUR_API_KEY');\n</script>"},{"note":"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.","wrong":"import amplitude from 'amplitude-js'; // Incorrect for older Node.js/CommonJS setups","symbol":"amplitude (CommonJS)","correct":"const amplitude = require('amplitude-js');"},{"note":"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.","wrong":"const amplitude = require('amplitude-js'); // While technically works in some ESM contexts, prefer 'import'","symbol":"amplitude (ESM)","correct":"import amplitude from 'amplitude-js';"}],"quickstart":{"code":"import amplitude from 'amplitude-js'; // Or const amplitude = require('amplitude-js');\n\n// Initialize Amplitude with your API key\n// Replace 'YOUR_API_KEY' with your actual Amplitude Project API Key\namplitude.getInstance().init('YOUR_API_KEY', null, {\n  includeReferrer: true,\n  includeUtm: true,\n  saveEvents: true,\n  logLevel: 'WARN',\n  // Optional: Configure event upload interval (default is 10 seconds)\n  uploadIntervalMillis: 5000,\n  // Optional: Set the server zone if your project is in the EU\n  // serverZone: 'EU'\n});\n\n// Set a user ID after initialization\namplitude.getInstance().setUserId('user_12345');\n\n// Set user properties\namplitude.getInstance().setUserProperties({\n  plan: 'premium',\n  signup_date: new Date().toISOString(),\n  country: 'USA',\n});\n\n// Log an event\namplitude.getInstance().logEvent('Button Clicked', {\n  button_name: 'Submit Form',\n  form_id: 'contact_form_1',\n  page: window.location.pathname,\n});\n\n// Log another event after some user interaction\nsetTimeout(() => {\n  amplitude.getInstance().logEvent('Page Viewed', {\n    page_name: 'Product Details',\n    product_id: 'SKU789',\n    category: 'Electronics',\n  });\n  console.log('Amplitude initialized and events logged. Check your Amplitude dashboard.');\n}, 2000);","lang":"javascript","description":"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."},"warnings":[{"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.","message":"The 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.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Migrate your React Native projects to the dedicated `@amplitude/react-native` SDK. Refer to the official Amplitude migration guide for detailed steps.","message":"Support 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.","severity":"deprecated","affected_versions":">=8.0.0"},{"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`.","message":"The `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.","severity":"gotcha","affected_versions":">=8.0.0"},{"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.","message":"Setting `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.","severity":"gotcha","affected_versions":"<8.21.9"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"Events not showing in Amplitude dashboard"},{"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.","cause":"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.","error":"Uncaught TypeError: amplitude.getInstance is not a function"},{"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.","cause":"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.","error":"TypeError: undefined is not an object (evaluating 'e._q.push')"},{"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`.","cause":"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.","error":"Amplitude cookie format changed, resulting in new device IDs for returning users."}],"ecosystem":"npm"}