Migrate your app to Shopify App Bridge React 4.x.x

• react and react-dom version 18 or higher
• A Node.js package manager: either npm, Yarn 1.x, or pnpm

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:

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.

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.

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.

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.

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.

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.

Install or upgrade the @shopify/app-bridge-react dependency with your package manager.

In 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:

The following components and props have been refactored, renamed, or removed. Review and update the following components as described:

• Modal
  • Updated props:
    • size
    • message
    • title
    • onClose
    • primaryAction and secondaryActions props
  • setupModalAutoSizing utility
  • Communication with the parent page
• TitleBar
  • Updated props:
    • primaryAction, secondaryActions, and actionGroups
    • breadcrumbs
• NavigationMenu

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.

The Modal component no longer accepts a message prop. Instead, it now accepts React elements as children.

The Modal component no longer accepts a title prop, Instead, now uses the TitleBar component to control the modal title.

The onClose prop has been renamed to onHide in the new Modal component to standardize the props with the admin extensions components library.

The 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.

In 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.

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.

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.

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.

The TitleBar component no longer accepts the primaryAction, secondaryActions, and actionGroups props. Instead, to provide title bar actions, add button elements as children.

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.

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.

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:

The following hooks have been refactored, renamed, or removed. Review and update the following components as described:

The 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.

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: