Migrate your app from legacy SDKs to Shopify App Bridge
Shopify has two other client-side app libraries, the Embedded App SDK (EASDK) and the POS App SDK, that serve a similar function to Shopify App Bridge.
Shopify App Bridge offers the same functionality as the EASDK and POS App SDK. Shopify App Bridge is designed to replace both of these legacy libraries, providing a consistent experience to both developers and merchants.
Using the backwards compatibility layer
Although Shopify App Bridge is intended to replace EASDK and POS App SDK, you do not need to rewrite your existing apps. Shopify App Bridge works with a backwards compatibility layer that listens for legacy EASDK and POS App SDK methods and translates them to Shopify App Bridge actions. If your app is calling EASDK methods today, then 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
- support for session tokens to manage embedded app sessions
- access to some new Shopify features, including the Navigation app extension and Resource Pickers 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 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 EASDK 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, and can automatically fit to the modal contents.
Modal URL
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 debugging using the Redux DevTools instead. You don’t need to know Redux.
Pagination
Adding pagination to the title bar using ShopifyApp.Bar.initialize
and ShopifyApp.Bar.setPagination
has been deprecated. We recommend implenting pagination within your app’s UI. If you’re using Polaris, you can use the pagination controls provided by the Polaris Page component.
If you prefer to keep pagination in your app’s titlebar, you can use Shopify App Bridge to add pagination buttons to the titlebar.
Use Shopify App Bridge to add pagination buttons to the title bar
Learn more about the TitleBar action set.
import createApp from '@shopify/app-bridge';
import { TitleBar, Button } from '@shopify/app-bridge/actions';
const app = createApp({
apiKey: '12345',
shopOrigin: shopOrigin,
});
const paginationPreviousButton = Button.create(app, { label: '←' })
paginationPreviousButton.subscribe(Button.Action.CLICK, function() {
// pagination previous action
})
const paginationNextButton = Button.create(app, { label: '→' })
paginationNextButton.subscribe(Button.Action.CLICK, function() {
// pagination next action
})
const titleBarOptions = {
buttons: {
secondary: [paginationPreviousButton, paginationNextButton],
}
};
const myAppTitleBar = TitleBar.create(app, titleBarOptions);
Use the Polaris Page component pagination controls
Learn more about the Polaris Page component.
import React, {useCallback} from 'react';
import {Page} from '@shopify/polaris';
function myApp() {
const paginationPrevious = useCallback(() => {
// pagination previous action
}, []);
const paginationNext = useCallback(() => {
// pagination next action
}, []);
const paginationOptions = {
hasNext: true,
hasPrevious: true,
onNext: paginationNext,
onPrevious: paginationPrevious
};
return (
<Page title="My App" pagination={paginationOptions}>
App
</Page>
);
}
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()
).
Migrating your POS App SDK app
The POS App SDK documentation has been updated with corresponding Shopify App Bridge methods. Here are a few more things to keep in mind when migrating an existing app to Shopify App Bridge.
Cart actions
All cart-related functionality is handled by the Cart
action set in Shopify App Bridge.
There are three steps to dispatch a cart action.
- Create the
Cart
action group instance:
import { Cart } from '@shopify/app-bridge/actions';
var app = createApp({
apiKey: '12345',
shopOrigin
});
var cart = Cart.create(app);
- Subscribe to the cart update action, which returns an unsubscribe function:
var unsubscribe = cart.subscribe(Cart.Action.UPDATE, function(payload) {
console.log(payload);
});
- Dispatch the desired cart action. Depending on the action, you may need to construct the action using a method from
Cart
.
- A simple cart action, passing the action type to
dispatch
:
cart.dispatch(Cart.Action.FETCH);
- A more complex cart action, using an action constructor method:
var customerPayload = { id: 123 };
cart.dispatch(Cart.setCustomer(customerPayload));
Fetching user and location data
In the POS App SDK, user and location data were fetched using dedicated methods.
In Shopify App Bridge, this data is accessed using app.getState()
.
import createApp from '@shopify/app-bridge';
var app = createApp({
apiKey: 'API key from Shopify Partner Dashboard',
shopOrigin: shopOrigin
});
app.getState('pos').then(function(pos) {
console.log('POS location data:', pos.location);
console.log('POS user data:', pos.user);
});
Deprecated features
POS Close Modal
There is no equivalent action in Shopify App Bridge.