RudderStack’s JavaScript SDK lets you track customer event data from your website and send it to your specified destinations. It is written in TypeScript and offers significant improvements in performance, size, and features compared to its predecessor.
This documentation covers the latest JavaScript SDK v3 (@rudderstack/analytics-js on npm).
Migrating from older versions?
If you are upgrading from a version prior to v3, review these guides before getting started:
- Migration guide: Step-by-step instructions for updating your SDK implementation.
- Breaking changes: Understand the compatibility differences introduced in v3.
Learn about the benefits of upgrading to JavaScript SDK v3.
If you’re using npm module in your browser-side code, following code snippet will import the RudderStack JavaScript SDK and send its first page event.
// Step 1: Install the SDK - `npm i @rudderstack/analytics-js`
// Step 2: Initalize the SDK
import { RudderAnalytics } from '@rudderstack/analytics-js';
const rudderAnalytics = new RudderAnalytics();
rudderAnalytics.load(process.env.WRITE_KEY, process.env.DATA_PLANE_URL, {});
// Q: How to generate your WRITE_KEY and DATA_PLANE_URL?
// A: Create a new JavaScript source at https://app.rudderstack.com
export { rudderAnalytics };
// Step 3: Call event tracking methods such as `page`, `track`, `identify`, etc. as needed
rudderAnalytics.page();
// NOTICE: This code works only if you have set up your browser-side code to use `npm` modules. Follow the quickstart guide otherwise.
// https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/quickstart/
Follow the JavaScript SDK Quickstart to quickly start using RudderStack JavaScript SDK with any of your preferred methods (Using CDN, npm (ESM or CJS), or for single-page applications).
Find instructions for specific goals and common implementation tasks related to the JavaScript SDK:
| Guide | Description |
|---|---|
| Quickstart | Set up and use the JavaScript SDK on your website in no time. |
| Install the JavaScript SDK | Install the JavaScript SDK via CDN or NPM. |
| Load the SDK | Understand the different options for loading the SDK snippet. |
| Pre-load API buffering | Understand how calls made before a valid load are buffered and replayed in order after the SDK loads. |
| Track event data | Use the SDK’s API calls (identify, track, page, etc.) to send data. |
| Set custom context | Attach enrichment data once and apply it to subsequent events during the current page load. |
| Configure data persistence | Customize how the SDK stores user information and preferences. |
| Use server-side cookies | Implement server-side cookies for improved tracking and ITP compliance. |
| Filter events | Control which events are sent to specific destinations. |
| Implement consent management | Configure the various consent management options in JavaScript SDK. |
| Detect Ad-blocked pages | Identify when the SDK might be blocked by ad blockers. |
| Use the service worker SDK | Implement tracking in service worker environments. |
| Use JavaScript SDK in Chrome extensions | Integrate the SDK within a Chrome browser extension. |
| Harden JavaScript SDK | Configure a hardened version of the JavaScript SDK for added security. |
See FAQs for answers to the commonly-asked questions about the JavaScript SDK.