Skip to main content

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 makes sure that your app is performant, flexible, and has the latest features. App Bridge 2.0 includes a more streamlined interface for actions and an improved architecture for tree-shaking.

Anchor to RequirementsRequirements

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

Anchor to Modify your app to use the ,[object Object], parameterModify 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.

Anchor to In the Shopify adminIn the Shopify admin

The Shopify admin provides the host parameter as part of the app URL when loading your embedded app:

https://example.org/?hmac={hmac}&host={base64_encoded_hostname}&session={session}&shop={shop_origin}&timestamp=1409617544

Anchor to After the OAuth flowAfter 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.

https://example.org/some/redirect/uri?code={authorization_code}&hmac=da9d83c171400a41f8db91a950508985&host={base64_encoded_hostname}&shop={shop_origin}&state={nonce}&timestamp=1409617544

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

const app = createApp({
apiKey: apiKey,
host: host
});

Anchor to Modify your app to use the ,[object Object], enum instead of ,[object Object]Modify your app to use the Action enum instead of ActionType

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

Anchor to ExamplesExamples

// 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) => {});

Anchor to Remove any helpers and types previously marked ,[object Object]Remove any helpers and types previously marked deprecated

The following helpers and type definitions have been marked as deprecated in App Bridge 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 uses any of the helper methods or type definitions above, then you should create your own versions.

Anchor to Next stepsNext steps

Was this page helpful?