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 for framework-specific instructions.

Anchor to RequirementsRequirements

A Node.js package manager: either npm, Yarn 1.x, or pnpm

Anchor to Benefits of migrationBenefits of migration

When you migrate your app to use Shopify App Bridge, you can take advantage of the following improvements to the developer experience:

Anchor to Simplified configurationSimplified 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.

Anchor to Automatic updatesAutomatic 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.

Anchor to Use web standardsUse 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.

Anchor to Direct API accessDirect 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. For more information about Direct API access, refer to the documentation.

Anchor to Modals with custom contentModals 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.

Anchor to Step 1: Add the ,[object Object], script tagStep 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. 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

<head>

</head>

Anchor to Step 2: Upgrade your Shopify App Bridge dependencyStep 2: Upgrade your Shopify App Bridge dependency

Install or upgrade the Shopify App Bridge dependency for your framework with your package manager.

Terminal

npm install @shopify/app-bridge@latest

yarn add @shopify/app-bridge@latest

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.

Anchor to Step 3: Remove the initialization setupStep 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.

Remove all manual App Bridge initialization code from your app:

Initialization setup

3.x.x

import createApp from '@shopify/app-bridge';

const config = {

apiKey: 'YOUR_API_KEY',

host: 'YOUR_HOST',

forceRedirect: true

};

const app = createApp(config);

Current

// No initialization needed - handled by app-bridge.js script

// Access App Bridge APIs through the shopify global variable

Anchor to Step 4: Update App Bridge APIsStep 4: Update App Bridge APIs

The following App Bridge APIs have been refactored or replaced. Review and update your code as described:

Modal
- Modal configuration changes
- Communication with the parent page
TitleBar
Navigation

Anchor to ModalModal

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: <s-modal> for inline content and <s-app-window> for modals with separate routes.

Anchor to Modal configuration changesModal configuration changes

The modal implementation has been simplified. Here are the key changes:

Web component based: Modals now use <s-modal> for inline content or <s-app-window> 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

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

<s-modal id="my-modal" heading="My modal" size="large">

<s-text>Hello world!</s-text>

<s-button variant="primary" slot="primary-action" onclick="handleChange()">

Add Instagram

</s-button>

<s-button slot="secondary-actions" onclick="handleChange()">

Learn more

</s-button>

</s-modal>

<s-button command="--show" commandFor="my-modal">Open Modal</s-button>

Current (with src)

<s-app-window id="my-modal" src="/modal-content">

</s-app-window>

<s-button command="--show" commandFor="my-modal">Open Modal</s-button>

Anchor to Communication with the parent pageCommunication 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 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

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

<s-app-window id="my-app-window" src="/modal-page">

</s-app-window>

<s-button command="--show" commandFor="my-app-window">Open Modal</s-button>

// Listen for messages from modal

window.addEventListener('message', (ev) => {

console.log('Message received from modal:', ev.data);

});

// Send message to modal

function sendMessageToModal() {

const modal = document.getElementById('my-app-window');

modal.contentWindow.postMessage('Hi, this is the main app!', location.origin);

}

</script>

Current (modal page)

function sendMessageFromModal() {

window.opener.postMessage('Hi, this is the modal!', location.origin);

}

// Listen for messages from parent

window.addEventListener('message', (ev) => {

console.log('Message received in modal:', ev.data);

});

</script>

Anchor to TitleBarTitleBar

The TitleBar API allows you to populate a standardized title bar with button actions and navigation breadcrumbs. Title bars are now configured using the <s-page> component's title and action slots.

TitleBar configuration

3.x.x

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

<s-page title="Hello world!">

<s-button variant="primary" slot="primary-action" onclick="handleFooClick()">

Foo

</s-button>

<s-button slot="secondary-actions" onclick="handleBarClick()">

Bar

</s-button>

</s-page>

Breadcrumbs configuration

3.x.x

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

const titleBar = TitleBar.create(app, {

title: 'Hello world!',

breadcrumbs: [{

content: 'Breadcrumb',

url: '/breadcrumb'

}]

});

Current

<s-page title="Hello world!">

<s-link slot="breadcrumb-actions" href="/breadcrumb">Breadcrumb</s-link>

</s-page>

Anchor to NavigationNavigation

The Navigation creates a navigation menu for your app. The navigation now uses the <s-app-nav> Polaris web component.

Navigation configuration

3.x.x

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

<s-app-nav>

<s-link href="/">Home</s-link>

<s-link href="/templates">Templates</s-link>

<s-link href="/settings">Settings</s-link>

</s-app-nav>

The active link is automatically matched based on the current URL.

Anchor to Other APIs that we've replacedOther 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. Refer to the following table to learn about the API replacement:

Previous Action	New API
`ContextualSaveBar`	Contextual Save Bar API
`Loading`	Loading API
`Picker`	Picker API
`ResourcePicker`	ResourcePicker API
`Toast`	Toast API
`Features`	Features API
`Cart`	Cart API
`Client`	Use the `shopify` global variable directly

Anchor to Step 5: Update API usageStep 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).

Anchor to Accessing App Bridge APIsAccessing 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

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

// The shopify global variable is automatically available

// after including the app-bridge.js script

await shopify.toast.show('Product saved', {

duration: 5000

});

Anchor to API replacementsAPI 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`

Anchor to Framework-specific considerationsFramework-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:

Remove manual initialization
Access APIs through the shopify global variable
Use web standards where possible
Let App Bridge handle authentication automatically

Was this page helpful?

Migrate your app to Shopify App Bridge

Anchor to RequirementsRequirements

Anchor to Benefits of migrationBenefits of migration

Anchor to Simplified configurationSimplified configuration

Anchor to Automatic updatesAutomatic updates

Anchor to Use web standardsUse web standards

Anchor to Direct API accessDirect API access

Anchor to Modals with custom contentModals with custom content

Anchor to Step 1: Add the ,[object Object], script tagStep 1: Add the app-bridge.js script tag

Anchor to Step 2: Upgrade your Shopify App Bridge dependencyStep 2: Upgrade your Shopify App Bridge dependency

npm

Yarn

pnpm

Anchor to Step 3: Remove the initialization setupStep 3: Remove the initialization setup

Anchor to Step 4: Update App Bridge APIsStep 4: Update App Bridge APIs

Anchor to ModalModal

Anchor to Modal configuration changesModal configuration changes

Anchor to Communication with the parent pageCommunication with the parent page

Anchor to TitleBarTitleBar

Anchor to NavigationNavigation

Anchor to Other APIs that we've replacedOther APIs that we've replaced

Anchor to Step 5: Update API usageStep 5: Update API usage

Anchor to Accessing App Bridge APIsAccessing App Bridge APIs

Anchor to API replacementsAPI replacements

Anchor to Framework-specific considerationsFramework-specific considerations

Anchor to Step 1: Add the ,[object Object], script tagStep 1: Add the `app-bridge.js` script tag