Migrating from the EASDK

Shopify has two other client-side app libraries, the Embedded App SDK (EASDK) and the POS App SDK (POSSDK), that serve a similar function to Shopify App Bridge.

At launch, Shopify App Bridge offers the same functionality as the EASDK. Soon, it will also offer POSSDK functionality in the same library. Shopify App Bridge is designed to eventually replace both of these legacy libraries, to provide a more consistent experience to both developers and merchants.

Using the backwards compatibility layer

Although Shopify App Bridge is intended to replace EASDK and POSSDK, you do not need to rewrite your existing apps. Shopify App Bridge works with a backwards compatibility layer that listens for legacy EASDK and POSSDK methods and translates them to Shopify App Bridge actions. If your app is calling EASDK methods today, these are already passing through Shopify App Bridge’s backwards compatibility layer.

This means that all existing embedded apps, without updating any of their code, get some of the benefits of Shopify App Bridge for free:

  • more consistent cross-platform rendering and functionality
  • access to better developer tools for debugging and better error reporting
  • increased stability
  • tighter integration with Polaris
  • access to some new Shopify features, including the Navigation app extension and a new Resource Picker for products and collections

Using Shopify App Bridge directly

Apps that don’t use the backwards compatibility layer, such as new apps built using Shopify App Bridge actions or apps that choose to upgrade to use Shopify App Bridge actions directly, get a number of additional benefits not available through the backwards compatibility layer:

  • modern front-end development workflows, including modular JavaScript
  • strict versioning using SemVer, for even more stability and predictability
  • more and clearer error messaging than is available through the backwards compatibility layer

Access to new Shopify features and Shopify App Bridge actions that will not be made available through the backwards compatibility layer, including a new Product Variant Resource Picker and new Redirect actions.

In the future, most new features will be added to Shopify App Bridge only, and will not be made available to the EASDK. We recommend that you upgrade to using Shopify App Bridge if you’re building a new app or doing significant upgrades to your existing app.

Migrating your app

The best place to start is the Embedded App SDK (EASDK) documentation, which has been updated with corresponding App Bridge methods. Here are a few additional things to keep in mind when migrating an existing app from EASDK to Shopify App Bridge.

Deprecated features

Shopify.API.Modal.input

Input modals are not supported in Shopify App Bridge.

You can use an iFrame modal instead.

Shopify.API.Modal.setHeight

Modal size is set in increments in App Bridge.

Modals will not accept URLs from outside of your app’s origin.

To embed content from another domain, create an iFrame modal and embed the content there.

Tertiary modal buttons

Because Shopify App Bridge gives you full control over button styling, primary and secondary buttons can now cover all use cases.

App icon

Setting an app icon via ShopifyApp.Bar.setIcon or ShopifyApp.Bar.initialize with an icon param has been deprecated.

You can now set your app icon on the App setup page in the Partners Dashboard.

ShopifyApp.init with debug option

Calling init with the debug option is not supported in App Bridge.

We recommend using the Redux DevTools instead.

Pagination

Since App Bridge allows you to fully customize titlebar buttons, adding pagination to the title bar using ShopifyApp.Bar.initialize and ShopifyApp.Bar.setPagination has been deprecated.

protocol URL parameter

Since all embedded apps must use HTTPS, the protocol parameter is no longer relevant.

Keeping the frame URL in sync

The EASDK initialize function automatically updates the Shopify admin URL. Since Shopify App Bridge is designed to accomodate a broader range of uses, it can’t make this assumption. It’s only aware of navigation using History and Redirect actions.

If your app uses links or server-side redirects for navigation, you can keep the URL in sync by dispatching a History.Action.PUSH action wherever you called EASDK’s initialize method (for example, after createApp()).

Using modular JavaScript:

import createApp from '@shopify/app-bridge';
import {History} from '@shopify/app-bridge/actions';

function initializeApp() {
  const app = createApp({
    apiKey: 'API key from Shopify Partner Dashboard',
    shopOrigin: shopOrigin,
  });

  const history = History.create(app);
  history.dispatch(History.Action.PUSH, `${window.location.pathname}`);

  return app;
}

Using ES5 and the CDN-hosted version:

var AppBridge = window['app-bridge'];
var createApp = AppBridge.default;
var actions = AppBridge.actions;
var History = actions.History;

function initializeApp() {
  var app = createApp({
    apiKey: 'API key from Shopify Partner Dashboard',
    shopOrigin: shopOrigin,
  });

  var history = History.create(app);
  history.dispatch(History.Action.PUSH, window.location.pathname);

  return app;
}

Sign up for a Partner account to get started.

Sign up