Shopify App Bridge Skill

[!NOTE] This skill focuses on Shopify App Bridge v3 (NPM package) and App Bridge CDN (v4) patterns. ALWAYS check which version the project is using. The latest standard is often typically App Bridge v4 (CDN-based /

overview

script) but many React apps still use

@shopify/app-bridge-react

(v3/v4 wrapper).

Core Concepts

• Host: The Shopify Admin (web or mobile).
• Client: Your embedded app.
• Actions: Messages sent to the host to trigger UI elements (Toast, Modal) or navigation.

Setup & Initialization

Using CDN (App Bridge v4 - Recommended)

shopify

<script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
<script>
  shopify.config = {
    apiKey: 'YOUR_API_KEY',
    host: new URLSearchParams(location.search).get("host"),
    forceRedirect: true,
  };
</script>

debugging & Exploration

shopify

[!TIP] Explore functionality:

1. Open Chrome Developer Console in the Shopify Admin.
2. Switch the frame context to your app's iframe.
3. Type

   shopify

   to see all available methods and configurations.

Using

@shopify/app-bridge-react

(Legacy/Specific Use Cases)

import { Provider } from '@shopify/app-bridge-react';
// ... configuration setup

Common Actions

Toast

shopify.toast.show('Product saved');

Modal

const modal = await shopify.modal.show({
  title: 'My Modal',
  message: 'Hello world',
  footer: {
    buttons: [
      { label: 'Ok', primary: true, id: 'ok-btn' }
    ]
  }
});

modal.addEventListener('action', (event) => {
    if (event.detail.id === 'ok-btn') {
        modal.hide();
    }
});

Resource Picker

const selected = await shopify.resourcePicker({
  type: 'product', // 'product', 'variant', 'collection'
  multiple: true,
});

const selected = await shopify.resourcePicker({
  type: 'product',
  selectionIds: [
    { id: 'gid://shopify/Product/12345', variants: [{ id: 'gid://shopify/ProductVariant/67890' }] }
  ]
});

const selected = await shopify.resourcePicker({
  type: 'product',
  filter: {
    query: 'Sweater', // Initial search query
    variants: false, // Hide variants
    draft: false,   // Hide draft products
  }
});

if (selected) {
    console.log(selected);
    // Returns array of selected resources
} else {
    console.log('User cancelled picker');
}

Navigation / Redirect

// Redirect to Admin Section
open('shopify:admin/products', '_top');

// Redirect to internal app route
open('shopify:app/my-route', '_top');

Contextual Save Bar

shopify.saveBar.show();

shopify.saveBar.addEventListener('save', async () => {
    // Perform save...
    shopify.saveBar.hide();
    shopify.toast.show('Saved');
});

shopify.saveBar.addEventListener('discard', () => {
    shopify.saveBar.hide();
});

Best Practices

[!IMPORTANT] Authentication: Ensure your app handles the OAuth flow and generates a session token. Requests to your backend MUST include the session token (Bearer token) if you rely on Shopify authentication. App Bridge handles fetching this token automatically in many configurations.

[!TIP] Navigation: When building a Remix app, use the

@shopify/shopify-app-remix

helpers to handle headers and bridging automatically where possible.

[!WARNING] Host Parameter: The

host

parameter is CRITICAL for App Bridge to work. It must be present in the URL or passed to the config. It is a base64 encoded string provided by Shopify.

References

• Modal Max - Full-screen modal dialogs for complex multi-step flows, editors, and wizards
• Save Bar - Contextual save bar for indicating unsaved form changes