Migrate your app to Shopify App Bridge React 4.x.x
If you have an app that uses components and hooks from Shopify App Bridge React 3.x.x, then you can follow this guide to upgrade your components and hooks to the latest version.
Anchor to RequirementsRequirements
Anchor to Benefits of migrationBenefits of migration
When you migrate your app to use Shopify App Bridge React 4.x.x, you can take advantage of the following improvements to the developer experience:
Anchor to Simplified configurationSimplified configuration
Shopify App Bridge React 4.x.x simplifies the configuration process. Apps no longer need to use a React Provider 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 the new Modal component from Shopify App Bridge React. This enables you to create rich modal experiences that render directly in the Shopify admin without having to handle separate routes. 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
app-bridge.js
script tagInclude 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
Anchor to Step 2: Upgrade your ,[object Object], dependencyStep 2: Upgrade your @shopify/app-bridge-react
dependency
@shopify/app-bridge-react
dependencyInstall or upgrade the @shopify/app-bridge-react
dependency with your package manager.
Terminal
npm install @shopify/app-bridge-react@latest
yarn add @shopify/app-bridge-react@latest
pnpm add @shopify/app-bridge-react@latest
Anchor to Step 3: Remove the ,[object Object], setupStep 3: Remove the Provider
setup
Provider
setupIn previous versions of App Bridge React, you needed to set up a context provider to enable component and hook usage. 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 Provider
import statements and usages from @shopify/app-bridge-react
in your app:
Provider setup
3.x.x
4.x.x
Anchor to Step 4: Update componentsStep 4: Update components
The following components and props have been refactored, renamed, or removed. Review and update the following components as described:
- Modal
- TitleBar
- Updated props:
- NavigationMenu
Anchor to ModalModal
The Modal
component allows you to display an overlay that prevents interaction with the rest of the app until dismissed. The following updates have been made to the Modal
component's behaviour and props.
The size
prop has been renamed variant
to more accurately describe it's purpose. The variant
prop accepts plain strings rather than constants.
size > variant
3.x.x
4.x.x
The Modal
component has a new variant called max
. Refer to the max
modal example for more details.
Anchor to [object Object], prop removedmessage
prop removed
message
prop removedThe Modal
component no longer accepts a message
prop. Instead, it now accepts React elements as children.
message prop removed
3.x.x
4.x.x
Anchor to [object Object], prop removedtitle
prop removed
title
prop removedThe Modal
component no longer accepts a title
prop, Instead, now uses the TitleBar
component to control the modal title.
title prop removed
3.x.x
4.x.x
The onClose
prop has been renamed to onHide
in the new Modal
component to standardize the props with the admin extensions components library.
onClose > onHide
3.x.x
4.x.x
Anchor to [object Object], and ,[object Object], props removedprimaryAction
and secondaryActions
props removed
primaryAction
and secondaryActions
props removedThe Modal
component no longer accepts the primaryAction
and secondaryActions
props. It now uses the TitleBar
component to control the modal action buttons.
A TitleBar
component in a Modal
component accepts only one secondary action.
primaryAction and secondaryActions props removed
3.x.x
4.x.x
Anchor to [object Object], utilitysetupModalAutoSizing
utility
setupModalAutoSizing
utilityIn previous versions, you needed to set up modal auto-sizing to allow your modal to update its height to fit the page content. This is no longer needed, because auto-sizing is set automatically.
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. There are now two ways to communicate between the modal and the parent page.
If you're using a modal with custom content, you can use the Broadcast Channel Web API to communicate with the parent page.
Communication with the parent page
3.x.x
4.x.x
If you're using a modal with a src
prop, you can use the postMessage API to communicate with the parent page. You can access postMessage
through the window.opener
object in the modal and through the modal.contentWindow
object in the parent page.
Communication with the parent page
3.x.x
4.x.x
Anchor to TitleBarTitle Bar
The TitleBar
component allows you to populate a standardized title bar with button actions and navigation breadcrumbs. It can now also be used inside a Modal
component to control the title and footer content to reduce the number of APIs that you need to learn. The following updates have been made to the title bar component's behaviour and props.
Anchor to [object Object],, ,[object Object],, and ,[object Object], props removedprimaryAction
, secondaryActions
, and actionGroups
props removed
primaryAction
, secondaryActions
, and actionGroups
props removedThe TitleBar
component no longer accepts the primaryAction
, secondaryActions
, and actionGroups
props. Instead, to provide title bar actions, add button
elements as children.
primaryAction
3.x.x
4.x.x
The TitleBar
component no longer accepts the breadcrumbs
prop. Instead, a breadcrumb can be added to the title bar using a child a
or button
element with the variant="breadcrumb"
attribute set.
breadcrumbs prop removed
3.x.x
4.x.x
The NavMenu
component creates a navigation menu for your app. This component was called NavigationMenu
in previous versions of Shopify App Bridge. It was renamed to NavMenu
to more closely match the HTML nav
element. The following updates have been made to the navigation menu component's behaviour and props.
The navigation menu component no longer accepts the navigationLinks
and matcher
props. Instead, to provide menu links, add a
elements as children of the NavMenu
component. The active link is automatically matched.
The first element of the NavMenu
component is required and used to configure the home route of the app. It is not rendered as a link. It needs to have rel="home"
set along with the href
set to the root path of your app.
navigationLinks and matcher props removed
3.x.x
4.x.x
Anchor to Other componentsOther components
All other React components from previous versions have been removed, and replaced by new APIs provided through the shopify
global variable. Refer to the following table to learn about the API replacement for each component:
| Component | New API |
|---|---|---|
| ContextualSaveBar
| Contextual Save Bar API |
| Loading
| Loading API |
| unstable_Picker
| Picker API |
| ResourcePicker
| ResourcePicker API |
| Toast
| Toast API |
Anchor to Step 5: Update hooksStep 5: Update hooks
The following hooks have been refactored, renamed, or removed. Review and update the following components as described:
Anchor to [object Object], hookuseAppBridge
hook
useAppBridge
hookThe useAppBridge
hook included in the most recent version of Shopify App Bridge functions differently than the previous useAppBridge
hook. Instead of returning the App Bridge app
instance, it returns the shopify
global variable, which is used to access App Bridge APIs such as toast
and resourcePicker
. As the shopify
variable is only available in a browser context, the useAppBridge
hook throws helpful error messages when used in a server context or in a misconfigured app.
You no longer need to use the app
reference returned from old uses of the useAppBridge
hook as App Bridge handles configuration for you.
4.x.x
Anchor to Other hooksOther hooks
All other React hooks from previous versions have been removed, and replaced by new APIs provided through the shopify
global variable. In most cases, you can use the useAppBridge
hook in place of these hooks, and access the corresponding API through the returned shopify
global variable.
Refer to the following table to learn about the API replacement for each hook:
Hook | Replacement |
---|---|
useAppBridgeState | This functionality has been spread out across a few APIs. For example, to retrieve the current staffMember , use the User API. |
useAuthenticatedFetch | This hook is no longer needed, because App Bridge injects automatic authorization into the global fetch function. For more information, refer to Resource Fetching. |
useContextualSaveBar | The contextual save bar is now automatically configured when you provide the data-save-bar attribute to a form element. For more information, refer to Contextual Save Bar. |
useNavigate | Navigation API |
useNavigationHistory | Navigation API |
useToast | Toast API |