Shopify App Bridge v3: Best Practices for Developers

Building embedded apps for Shopify means your app lives entirely within an iframe inside the Shopify Admin. To facilitate communication between your iframe and the parent Shopify frame, Shopify provides the App Bridge library. With v3 (and the shift toward global script tags), the integration pattern has changed significantly from v2.

1. Global Initialization over NPM Packages

In older versions, you imported @shopify/app-bridge as an NPM dependency and initialized it manually with your API key. In v3, Shopify strongly recommends utilizing the global script tag approach. This guarantees you are always using the most up-to-date, backwards-compatible version of the bridge directly from Shopify's CDN.

<!-- Place this in your app's index or document head -->
<script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
<script>
  window.shopify = shopify.create({
    apiKey: 'YOUR_APP_CLIENT_ID',
    host: new URLSearchParams(location.search).get("host"),
    forceRedirect: true
  });
</script>

This globally exposes the shopify object, making it incredibly easy to trigger modals, toast notifications, and title bar updates from anywhere in your React application without passing down context providers.

2. Session Token Authentication

Embedded apps must not rely on traditional cookies for authentication because modern browsers (like Safari and Chrome) block third-party cookies by default. Instead, you must use Session Tokens.

App Bridge can generate a JWT signed by Shopify that proves the identity of the merchant currently using the app. You must attach this token to every API request made to your Node.js or Laravel backend.

// Example API utility using global App Bridge
export async function authenticatedFetch(url, options = {}) {
  // Get a fresh token from the parent frame
  const sessionToken = await window.shopify.idToken();
  
  const headers = new Headers(options.headers || {});
  headers.append('Authorization', `Bearer ${sessionToken}`);
  
  return fetch(url, { ...options, headers });
}

3. Utilize Native UI Components

To make your app feel like a native extension of Shopify, you should heavily leverage App Bridge's UI features rather than building your own. Use the native Title Bar to control the page title and breadcrumbs, and use native Toast notifications for success/error messages.

// Triggering a native toast notification
window.shopify.toast.show('Settings saved successfully', { duration: 3000 });

// Updating the title bar with a primary action button
window.shopify.titleBar.set({
  title: 'Dashboard',
  buttons: {
    primary: {
      label: 'Create Campaign',
      onAction: () => {
        // Handle click
      }
    }
  }
});

Conclusion

Mastering App Bridge v3 is non-negotiable for building high-quality public Shopify Apps. By embracing session tokens, global initialization, and native UI elements, you ensure your app is secure, resilient against browser cookie policies, and indistinguishable from core Shopify features.