This package provides React hooks and components for use with Shopify embedded app development with Gadget.
Features
For Shopify app development, setting up and understanding the Shopify App Bridge is essential.
This package significantly simplifies this process by automating the OAuth authentication and App Bridge initialization.
The Provider takes charge of these complex steps, enabling developers to focus on developing their app's core functionalities. By handling the OAuth flow and initializing the App Bridge, this package removes the intricate setup tasks from the developer's workload. Once the setup is complete, developers can access the initialized App Bridge instance through the appBridge key provided by the useGadget hook, facilitating seamless integration and utilization of the App Bridge's comprehensive features within their Shopify apps.
Automatically starts the OAuth process with new users of the application using Gadget, escaping Shopify's iframe if necessary.
Establishes an iframe-safe secure session with the Gadget backend using Gadget OAuth PKCE.
Sets up the correct React context for making backend calls to Gadget using @gadgetinc/react.
Installation
If you select the Shopify template upon app creation in Gadget, @gadgetinc/react-shopify-app-bridge is already installed.
This is a companion package to the JavaScript client package generated for your Gadget app. You must first install the JS client for your app, and then install this package.
To install the JS client for your app, you must set up the Gadget NPM registry, and then install the client:
terminal
npm config set @gadget-client:registry https://registry.gadget.dev/npm
yarn add @gadget-client/my-app-slug
# or
npm install @gadget-client/my-app-slug
Once you have your JS client installed, you can install the React hooks library and the Shopify App bridge library with yarn or npm:
3// import the Gadget<->Shopify bindings that manage the auth process with Shopify
4import{
5AppType,
6ProviderasGadgetProvider,
7 useGadget,
8}from"@gadgetinc/react-shopify-app-bridge";
9import{TitleBar}from"@shopify/app-bridge-react";
10importReactfrom"react";
11// import the instance of the Gadget API client for this app constructed in the other file
12import{ api }from"./api";
13
14exportdefaultfunctionApp(){
15return(
16// Wrap our main application's react components in the `<GadgetProvider/>` component to interface with Shopify
17// This wrapper sets up the Shopify App Bridge, and will automatically redirect to perform the OAuth authentication if the shopify shop doesn't yet have the store installed.
18<GadgetProvider
19type={AppType.Embedded}
20shopifyApiKey="REPLACE ME with api key from Shopify partners dashboard"
21api={api}
22>
23<ProductManager/>
24</GadgetProvider>
25);
26}
27
28// An example component that uses the Gadget React hooks to work with data in the Shopify backend
@shopify/app-bridge-react allows you to specify a custom router configuration to manage client-side routing. Similarly, the Gadget provider will allow you to specify a custom router which will be forwarded to the App Bridge.
JavaScript
1// import Gadget's react hooks for accessing data from your Gadget app
38// Wrap our main application's react components in the `<GadgetProvider/>` component to interface with Shopify
39// This wrapper sets up the Shopify App Bridge, and will automatically redirect to perform the OAuth authentication if the Shopify shop doesn't yet have the store installed.
40<GadgetProvider
41type={AppType.Embedded}
42shopifyApiKey="REPLACE ME with api key from Shopify partners dashboard"
43api={api}
44>
45<AuthenticatedApp/>
46</GadgetProvider>
47);
48}
49
50exportdefaultfunctionAppWrapper(){
51return(
52<BrowserRouter>
53<App/>
54</BrowserRouter>
55);
56}
Breaking changes when upgrading to version 0.14.0
Because @gadgetinc/react-shopify-app-bridge version 0.14.0 supports App Bridge V4, this requires you to migrate to your app from App Bridge V3.
Otherwise, you will experience many breaking changes to your app, this also means you will have to update any hooks or components that aren't supported by V4. To upgrade your Gadget application to support App Bridge V4, check out our guide here.