Migration Guide: JavaScript Elements to Web Elements

This guide will help you migrate from the deprecated JavaScript Elements SDK to the new Web Elements SDK. The migration process is straightforward as the core functionality remains similar, with most changes focused on package names and initialization.

Quick Migration Checklist

1. Update package dependencies
2. Change import statements
3. Update initialization code
4. Review and update element creation (if needed)
5. Test your implementation

Package Installation

npm

- npm install --save @basis-theory/basis-theory-js
+ npm install --save @basis-theory/web-elements

yarn

- yarn add @basis-theory/basis-theory-js
+ yarn add @basis-theory/web-elements

CDN

- <script src="https://js.basistheory.com"></script>
+ <script src="https://js.basistheory.com/web-elements/<version>/index.js" integrity="<integrity>" crossorigin="anonymous"></script>

Our web-elements loader includes a robust hash verification mechanism to ensure code integrity. If your version includes a hash, you can verify its authenticity by visiting: https://js.basistheory.com/sri/?version=<YOUR VERSION>. For a complete list of published hashes, please refer to our Github repository.

Initialization Changes

The most significant change is how you initialize the SDK:

ES Module

- import { BasisTheory } from "@basis-theory/basis-theory-js";
+ import { basistheory } from "@basis-theory/web-elements";

- const bt = await new BasisTheory().init("<API_KEY>");
+ const bt = await basistheory("<API_KEY>");

CDN

<script>
  window.addEventListener("load", async () => {
    try {
-     await BasisTheory.init("<API_KEY>");
-     // use BasisTheory instance globally
+     const bt = await basistheory("<API_KEY>");
      // use bt instance
    } catch (e) {
      // handle errors
    }
  });
</script>

Note that in the Web Elements SDK, basistheory is a function rather than a class, and returns a promise that resolves to the instance.

Element Creation and Lifecycle

The core Element lifecycle methods remain the same:

// Create an element - identical in both SDKs
const cardElement = bt.createElement('card', options);

// Mount an element - identical in both SDKs
cardElement.mount('#container');

// Update an element - identical in both SDKs
cardElement.update(options);

// Unmount an element - identical in both SDKs
cardElement.unmount();

Event Handling

Event handling is functionally identical between both SDKs:

// Both SDKs support this pattern
element.on('change', (event) => {
  // handle change event
});

Tokenization

The tokenization process remains the same:

// Tokenizing with elements is the same in both SDKs
const { token } = await bt.tokenize({
  card: cardElement
});

// Or with individual elements
const { token } = await bt.tokenize({
  card: {
    number: cardNumberElement,
    expiration_date: cardExpirationElement,
    cvc: cardCvcElement
  }
});

Browser Support

Web Elements supports the same browsers as JavaScript Elements:

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Troubleshooting

If you encounter issues during migration, refer to our troubleshooting guide, which covers common migration problems and their solutions.

If you encounter any issues during migration that aren't covered in our documentation, please contact support@basistheory.com for assistance.