All Tutorials

Migrate your app from Shopify App Bridge 1.x to Shopify App Bridge 2.0

All Tutorials

Migrate your app from Shopify App Bridge 1.x to Shopify App Bridge 2.0

Migrate your app from Shopify App Bridge 1.x to Shopify App Bridge 2.0

Migrating from Shopify App Bridge 1.x to App Bridge 2.0 will ensure that your app is aligned with the future of Shopify. This new release of App Bridge also includes a more streamlined interface for actions and an improved architecture for tree-shaking.


To use this migration guide your app must meet the following requirements:

  • Your app must be currently be running on App Bridge 1.x

Modify your app to use the host parameter

A new query parameter named host has been introduced with the release of App Bridge 2.0. The base64-encoded host parameter represents the domain that is currently hosting your embedded app.

In the Shopify admin

The Shopify admin provides the host parameter as part of the app URL when loading your embedded app.{hmac}&host={base64_encoded_hostname}&session={session}&shop={shop_origin}&timestamp=1409617544

After the OAuth flow

The host query parameter is also available to the app as part of the GET request made to the allow-listed redirect URL specified. To learn more about host, refer to Getting and storing the shop origin.{authorization_code}&hmac=da9d83c171400a41f8db91a950508985&host={base64_encoded_hostname}&shop={shop_origin}&state={nonce}&timestamp=1409617544

You will need to store the host parameter for use with the updated createApp method.

const app = createApp({
  apiKey: apiKey,
  host: host

Modify your app to use Action property instead of ActionType

To streamline the library and simplify the interface we have removed the ActionType enum from App Bridge Actions. The Action enum will now be used exclusively. If you need to change your code for this update, it will be on action subscriptions.


// Right
app.subscribe(Error.Action.INVALID_ACTION, (data) => {});
app.subscribe(Loading.Action.START, () => {});
app.subscribe(History.Action.REPLACE, (payload: History.Payload) => {});

// Wrong
app.subscribe(Error.ActionType.INVALID_ACTION, (data) => {});
app.subscribe(Loading.ActionType.START, () => {});
app.subscribe(History.ActionType.REPLACE, (payload: History.Payload) => {});

Remove any helpers and types previously marked deprecated

The following helpers and type definitions have been marked to be deprecated in 1.0. In App Bridge 2.0, they are fully removed:

  • HandlerData type definition
  • getShopOrigin helper method
  • getUrlParams helper method

If your code imports and use any of the helper methods or type definitions above, please create your own versions.