JavaScript SDK Migration Guide

Migrate your RudderStack JavaScript SDK from older versions to the latest version.

This guide lists the steps to update your RudderStack JavaScript SDK from the older versions.

Before migrating, make sure to go through the Breaking Changes in the SDK v3.

Migration considerations

Note the following while migrating your SDK to the latest version:

  • All sites that have the same top-level domain must use the same encryption version (preferably v3). For example, if uses the latest JavaScript SDK and uses a legacy SDK version (v1.1 or below), then you should set the storage load option as follows to avoid corrupting the storage data for any of the sites:
rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  storage: {
    encryption: {
      version: "legacy"
  // other load options
If you have any special needs and have implemented different SDK major versions across your sites, you need to set the encryption version to legacy. This way the SDK will continue to use the same encryption technique as the older SDK versions so that your subdomain sites using those legacy SDK versions are not impacted at all.
  • By default, the new SDK will migrate the existing (older) cookies to the new encryption technique to not interrupt your tracking unless you have:

    • Explicitly configured the storage.migrate load API option to false, and
    • Specified the plugins load API option to exclude the StorageMigrator plugin.
  • As the data encryption technique has changed, you must update your decryption logic if you were previously accessing the data directly from the storage.


Change the SDK installation and loading snippet. Then, replace the write keyThe write key (or source write key) is a unique identifier for your source. RudderStack uses this key to send events from a source to the specified destination. and data plane URLThe data plane URL is the location where events are routed and sent to the RudderStack backend for processing. You can find this URL in the home page of your RudderStack dashboard. with their actual values.


The NPM package based on the latest JavaScript SDK architecture is available here.

The latest SDK uses the @rudderstack/analytics-js package instead of rudder-sdk-js.

You can use any of the following options to update the SDK using NPM:

Questions? Contact us by email or on Slack