Version:

JavaScript SDK

Track event data and send it your specified destinations using the RudderStack JavaScript SDK.

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).


Key features

  • Fast, reliable, and less vulnerable to ad blockers.
  • Load specific SDK features on demand using plugins.
  • Lightweight storage data footprint with improved encryption.
  • Complete control over the persistent data storage strategy.
  • ITP (Intelligent Tracking Prevention) compliant as it implements server-side cookies.
  • Smaller SDK of around 25KB (size reduction of approximately 30% from the previous version).

Get started

info

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).

Core tasks

Find instructions for specific goals and common implementation tasks related to the JavaScript SDK:

GuideDescription
QuickstartSet up and use the JavaScript SDK on your website in no time.
Install the JavaScript SDKInstall the JavaScript SDK via CDN or NPM.
Load the SDKUnderstand the different options for loading the SDK snippet.
Track event dataUse the SDK’s API calls (identify, track, page, etc.) to send data.
Configure data persistenceCustomize how the SDK stores user information and preferences.
Use server-side cookiesImplement server-side cookies for improved tracking and ITP compliance.
Filter eventsControl which events are sent to specific destinations.
Implement consent managementConfigure the various consent management options in JavaScript SDK.
Detect Ad-blocked pagesIdentify when the SDK might be blocked by ad blockers.
Use the service worker SDKImplement tracking in service worker environments.
Use JavaScript SDK in Chrome extensionsIntegrate the SDK within a Chrome browser extension.
Harden JavaScript SDKConfigure a hardened version of the JavaScript SDK for added security.

Understand concepts

See FAQs for answers to the commonly-asked questions about the JavaScript SDK.



Questions? Contact us by email or on Slack