--- title: Migrate your app to Shopify App Bridge description: Learn how to migrate your app to the latest version of Shopify App Bridge. api_name: app-bridge source_url: html: 'https://shopify.dev/docs/api/app-bridge/migration-guide' md: 'https://shopify.dev/docs/api/app-bridge/migration-guide.md' --- ExpandOn this page * [Requirements](https://shopify.dev/docs/api/app-bridge/migration-guide.md#requirements) * [Benefits of migration](https://shopify.dev/docs/api/app-bridge/migration-guide.md#benefits-of-migration) * [Step 1: Add the app-bridge.​js script tag](https://shopify.dev/docs/api/app-bridge/migration-guide.md#step-1-add-the-app-bridgejs-script-tag) * [Step 2: Upgrade your Shopify App Bridge dependency](https://shopify.dev/docs/api/app-bridge/migration-guide.md#step-2-upgrade-your-shopify-app-bridge-dependency) * [Step 3: Remove the initialization setup](https://shopify.dev/docs/api/app-bridge/migration-guide.md#step-3-remove-the-initialization-setup) * [Step 4: Update App Bridge APIs](https://shopify.dev/docs/api/app-bridge/migration-guide.md#step-4-update-app-bridge-apis) * [Step 5: Update API usage](https://shopify.dev/docs/api/app-bridge/migration-guide.md#step-5-update-api-usage) # Migrate your app to Shopify App Bridge If you have an app that uses a previous version of Shopify App Bridge (3.x.x or earlier), this guide explains how to upgrade to the latest Shopify App Bridge. The most significant change in Shopify App Bridge is how you access APIs. Using React? If you're using React components and hooks from `@shopify/app-bridge-react`, refer to the [React migration guide](https://shopify.dev/docs/api/app-bridge/migration-guide-react) for framework-specific instructions. *** ## Requirements * A Node.js package manager: either [npm](https://www.npmjs.com/get-npm), [Yarn 1.x](https://classic.yarnpkg.com/lang/en/docs/install), or [pnpm](https://pnpm.io/installation) *** ## Benefits of migration When you migrate your app to use Shopify App Bridge, you can take advantage of the following improvements to the developer experience: ### Simplified configuration Shopify App Bridge simplifies the configuration process. Apps no longer need complex initialization or the `host` config. Instead, they only need to provide their API key to the `app-bridge.js` script. ### Automatic updates The `app-bridge.js` script automatically keeps itself up to date, so you can access new Shopify App Bridge APIs as soon as they're released. ### Use web standards The latest version of Shopify App Bridge embraces the web platform and web standards, so you can use web APIs you're already familiar with. For more information about the motivation behind App Bridge, refer to [Shopify's platform is the Web platform](https://shopify.engineering/shopifys-platform-is-the-web-platform). ### Direct API access Take advantage of the new Direct API access feature. You can make requests to the Admin API directly from your app using the standard [web fetch API](https://developer.mozilla.org/en-US/docs/Web/API/fetch). For more information about Direct API access, refer to the [documentation](https://shopify.dev/docs/api/app-home#direct-api-access). ### Modals with custom content Add modals to your app with custom content using web components or React components from Shopify App Bridge. This enables you to create rich modal experiences that render directly in the Shopify admin. These modals are fast too, because they're preloaded. *** ## Step 1: Add the `app-bridge.js` script tag Include the `app-bridge.js` script tag in your app. Replace `%SHOPIFY_API_KEY%` with your app's [client ID](https://shopify.dev/docs/apps/build/authentication-authorization/client-secrets#retrieve-your-apps-client-credentials). This configures your app to use Shopify App Bridge. The `app-bridge.js` script is CDN-hosted, so your app always gets the latest version of it. ## index.html ```html ``` *** ## Step 2: Upgrade your Shopify App Bridge dependency Install or upgrade the Shopify App Bridge dependency for your framework with your package manager. ## Terminal ```terminal npm install @shopify/app-bridge@latest ``` ```terminal yarn add @shopify/app-bridge@latest ``` ```terminal pnpm add @shopify/app-bridge@latest ``` ##### npm ``` npm install @shopify/app-bridge@latest ``` ##### Yarn ``` yarn add @shopify/app-bridge@latest ``` ##### pnpm ``` pnpm add @shopify/app-bridge@latest ``` Framework-specific packages If you're using a framework-specific package like `@shopify/app-bridge-react`, upgrade that package to the latest version as well. *** ## Step 3: Remove the initialization setup In previous versions of App Bridge, you needed to manually initialize and configure App Bridge. This is no longer needed, as all the setup for Shopify App Bridge is done through the `app-bridge.js` script tag that you added in [step 1](https://shopify.dev/docs/api/app-bridge/migration-guide#step-1-add-the-app-bridge-js-script-tag). Remove all manual App Bridge initialization code from your app: ## Initialization setup ## 3.x.x ```js import createApp from '@shopify/app-bridge'; const config = { apiKey: 'YOUR_API_KEY', host: 'YOUR_HOST', forceRedirect: true }; const app = createApp(config); ``` ## Current ```js // No initialization needed - handled by app-bridge.js script // Access App Bridge APIs through the shopify global variable ``` *** ## Step 4: Update App Bridge APIs The following App Bridge APIs have been refactored or replaced. Review and update your code as described: * [Modal](#modal) * [Modal configuration changes](#modal-configuration-changes) * [Communication with the parent page](#communication-with-the-parent-page) * [TitleBar](#titlebar) * [Navigation](#navigation) ### Modal The Modal API allows you to display an overlay that prevents interaction with the rest of the app until dismissed. Shopify App Bridge now uses Polaris web components: `` for inline content and `` for modals with separate routes. #### Modal configuration changes The modal implementation has been simplified. Here are the key changes: * **Web component based**: Modals now use `` for inline content or `` for src-based modals instead of imperative APIs. * **Size configuration**: Use the `size` attribute with values like 'small', 'large', or 'full-width'. * **Title and content**: Use the `heading` attribute for the modal title and add content as children. * **Actions**: Modal actions are handled through standard HTML buttons with `slot` attributes. * **Auto-sizing**: Modal auto-sizing is now automatic - no manual setup required. ## Modal configuration ## 3.x.x ```js import {Modal} from '@shopify/app-bridge/actions'; const modalOptions = { title: 'My modal', message: 'Hello world!', size: Modal.Size.Large, primaryAction: { content: 'Add Instagram', onAction: handleChange }, secondaryActions: [{ content: 'Learn more', onAction: handleChange }] }; const myModal = Modal.create(app, modalOptions); myModal.dispatch(Modal.Action.OPEN); ``` ## Current ```html Hello world! Add Instagram Learn more Open Modal ``` ## Current (with src) ```html Open Modal ``` #### Communication with the parent page In previous versions, you needed to use the `Modal.Action.DATA` action to communicate between the parent page and the modal. **For inline content modals**: Since these render within your app's iframe, no special communication mechanism is needed - you can directly access your app's JavaScript context. **For src modals**: Use the [postMessage API](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) to communicate with the parent page. Access `postMessage` through `window.opener` in the modal and through the modal's `contentWindow` in the parent page. ## Communication with src modals ## 3.x.x ```js import {Modal} from '@shopify/app-bridge/actions'; // In modal page (loaded via src) function sendMessageFromModal() { app.dispatch(Modal.data({message: 'Hi, this is the modal!'})); } // In parent page app.subscribe(Modal.Action.DATA, (data) => { console.log('Received message from modal: ', data.message); }); ``` ## Current ```html Open Modal ``` ## Current (modal page) ```html ``` ### Title​Bar The TitleBar API allows you to populate a standardized title bar with button actions and navigation breadcrumbs. Title bars are now configured using the `` component's title and action slots. ## TitleBar configuration ## 3.x.x ```js import {TitleBar} from '@shopify/app-bridge/actions'; const titleBar = TitleBar.create(app, { title: 'Hello world!', primaryAction: { content: 'Foo', onAction: handleFooClick }, secondaryActions: [{ content: 'Bar', onAction: handleBarClick }], actionGroups: [{ title: 'More actions', actions: [{ content: 'First grouped button', onAction: handleFirstGroupedButtonClick }] }] }); ``` ## Current ```html Foo Bar ``` ## Breadcrumbs configuration ## 3.x.x ```js import {TitleBar} from '@shopify/app-bridge/actions'; const titleBar = TitleBar.create(app, { title: 'Hello world!', breadcrumbs: [{ content: 'Breadcrumb', url: '/breadcrumb' }] }); ``` ## Current ```html Breadcrumb ``` ### Navigation The Navigation creates a navigation menu for your app. The navigation now uses the `` Polaris web component. ## Navigation configuration ## 3.x.x ```js import {NavigationMenu} from '@shopify/app-bridge/actions'; const navigationMenu = NavigationMenu.create(app, { items: [ { label: 'Home', destination: '/' }, { label: 'Templates', destination: '/templates' }, { label: 'Settings', destination: '/settings' } ], active: navigationMenu.items[0] }); ``` ## Current ```html Home Templates Settings ``` The active link is automatically matched based on the current URL. ### Other APIs that we've replaced All other App Bridge actions from previous versions have been replaced by new APIs provided through the [`shopify` global variable](https://shopify.dev/docs/api/app-home#shopify-global-variable). Refer to the following table to learn about the API replacement: | Previous Action | New API | | - | - | | `ContextualSaveBar` | [Contextual Save Bar API](https://shopify.dev/docs/api/app-home/apis/save-bar) | | `Loading` | [Loading API](https://shopify.dev/docs/api/app-home/apis/loading) | | `Picker` | [Picker API](https://shopify.dev/docs/api/app-home/apis/picker) | | `ResourcePicker` | [ResourcePicker API](https://shopify.dev/docs/api/app-home/apis/resource-picker) | | `Toast` | [Toast API](https://shopify.dev/docs/api/app-home/apis/toast) | | `Features` | [Features API](https://shopify.dev/docs/api/app-home/apis/features) | | `Cart` | [Cart API](https://shopify.dev/docs/api/app-home/apis/cart) | | `Client` | Use the `shopify` global variable directly | *** ## Step 5: Update API usage After migrating your imports and configuration, you'll need to update how you interact with App Bridge APIs. Most App Bridge functionality now uses the `shopify` global variable for imperative APIs (like Toast, ResourcePicker) and web components for UI elements (like Modal, TitleBar). ### Accessing App Bridge APIs The most significant change in Shopify App Bridge is how you access APIs. Instead of creating an app instance and dispatching actions, you now use web components for UI elements and the `shopify` global variable for imperative APIs: ## Accessing APIs ## 3.x.x ```js import createApp from '@shopify/app-bridge'; import {Toast} from '@shopify/app-bridge/actions'; const app = createApp(config); const toastOptions = { message: 'Product saved', duration: 5000 }; const toastNotice = Toast.create(app, toastOptions); toastNotice.dispatch(Toast.Action.SHOW); ``` ## Current ```js // The shopify global variable is automatically available // after including the app-bridge.js script await shopify.toast.show('Product saved', { duration: 5000 }); ``` ### API replacements The following table shows how to replace previous App Bridge actions with new APIs: | Previous use | New API | | - | - | | `app.getState()` | Various APIs , for example `shopify.user()` for user info | | `app.dispatch()` | Direct method calls on `shopify` object | | `app.subscribe()` | Event listeners on specific APIs | | Authenticated fetch | Global `fetch` automatically includes auth headers | | `History.Action.PUSH` | `shopify.navigation.navigate()` | | `Redirect.Action.APP` | `shopify.navigation.navigate()` | | `Redirect.Action.REMOTE` | `window.open()` or `window.location.href` | ### Framework-specific considerations If you're using a framework-specific package like `@shopify/app-bridge-react`, refer to that package's migration guide for framework-specific updates. The core concepts remain the same: 1. Remove manual initialization 2. Access APIs through the `shopify` global variable 3. Use web standards where possible 4. Let App Bridge handle authentication automatically *** * [Requirements](https://shopify.dev/docs/api/app-bridge/migration-guide.md#requirements) * [Benefits of migration](https://shopify.dev/docs/api/app-bridge/migration-guide.md#benefits-of-migration) * [Step 1: Add the app-bridge.​js script tag](https://shopify.dev/docs/api/app-bridge/migration-guide.md#step-1-add-the-app-bridgejs-script-tag) * [Step 2: Upgrade your Shopify App Bridge dependency](https://shopify.dev/docs/api/app-bridge/migration-guide.md#step-2-upgrade-your-shopify-app-bridge-dependency) * [Step 3: Remove the initialization setup](https://shopify.dev/docs/api/app-bridge/migration-guide.md#step-3-remove-the-initialization-setup) * [Step 4: Update App Bridge APIs](https://shopify.dev/docs/api/app-bridge/migration-guide.md#step-4-update-app-bridge-apis) * [Step 5: Update API usage](https://shopify.dev/docs/api/app-bridge/migration-guide.md#step-5-update-api-usage)