JavaScript SDK Migration Guide

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

Pre-migration checklist

1. Go through the Breaking Changes in the JavaScript SDK v3 to understand potential impacts on your implementation.
2. If you have implemented the JavaScript SDK in multiple sites sharing the same top-level domain and cookies and have different major SDK versions across these sites, then RudderStack recommends the following actions:

• Consider upgrading all sites to the latest v3 SDK version at once.
• If that is not possible, then upgrade the older sites to the latest version of SDK v1.1.
• If any of the above actions are not possible, then set the storage.encryption.version parameter to legacy for all the sites.

For example, if shop.example.com uses the latest JavaScript SDK (v3) and docs.example.com uses a legacy SDK version (v1.1 or below), then set the encryption version to legacy in the shop.example.com site to avoid corrupting the RudderStack storage data:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  storage: {
    encryption: {
      version: "legacy"
    }
  },
  // Other load options
});

RudderStack stores all its cookies in the top-level domain of your site by default unless you’ve configured to change the domain.

3. Decide on storage migration. By default, the new SDK will migrate existing cookies to the new encryption technique. To prevent this, you can:

• Set storage.migrate load API option to false, or
• Exclude the StorageMigrator plugin in the plugins load API option.

4. If you directly access data from storage (not recommended by RudderStack), update your decryption logic to match the new encryption technique as the data encryption technique has changed.

See Data Persistence in JavaScript SDK for more information on the storage and encryption features.

CDN

Change the SDK installation 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 at the top of the Connections page in your RudderStack dashboard. with their actual values.

For more information, see the following guides:

• CDN installation method for installing the SDK snippet.
• Setup for serving Javascript SDK if you are using your own domain to proxy the SDK or route the events.

NPM

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

The latest SDK’s NPM package is published as @rudderstack/analytics-js instead of rudder-sdk-js.

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

npm i @rudderstack/analytics-js

"dependencies": {
  "@rudderstack/analytics-js": "^3.x.x"
}