wikis / Shopify (Developer Platform) / wiki / concepts / app-bridge.md view as markdown report a mistake

Definition

App Home is the dedicated area in the Shopify admin where your app renders its landing page and UI, and the main surface through which merchants use your app. Your app communicates with other parts of the Shopify admin using a JavaScript SDK called App Bridge, and renders its UI inside an iframe using web components. There are two ways to build for App Home: iframe-based apps (covered here) and App Home UI extensions.

How It Works

The App Home area is implemented as an iframe. To interact with admin components outside this iframe, apps use the App Bridge JavaScript SDK. You use App Bridge APIs to communicate with the admin, and App Bridge web components to add UI (title bars, navigation menus) to the admin outside your app's iframe.

To start, scaffold an app with Shopify CLI and select Build a React Router app. The command creates a framework that includes all of the App Bridge and Polaris libraries you need:

cd my-app
shopify app init

Apps scaffolded with Shopify CLI already include the App Bridge script, so you don't need to add it manually. When the App Bridge script is included, you don't need to set up or configure any additional authentication to use the APIs: your app runs inside an authenticated session in the admin, so you don't manage tokens or headers yourself.

The App Bridge APIs are exposed through the shopify global variable. They let you read information from the admin, launch workflows (creating products, editing orders), and provide feedback through toasts and modals.

Key Parameters

Loading the libraries (CDN + types). Loading App Bridge from cdn.shopify.com/shopifycloud/app-bridge.js installs the latest version of the library; for TypeScript, add @shopify/app-bridge-types@latest to package.json. Polaris web components load from cdn.shopify.com/shopifycloud/polaris.js (latest version); pair with @shopify/polaris-types@latest. Polaris components are built on the Web Components standard, so they work like native HTML elements in any framework or vanilla JavaScript.

Rendering a page with Polaris web components:

export default function App() {
  return (
    <s-page heading="My App">
      <s-section heading="Welcome">
        <s-paragraph>
          Welcome to your Shopify app! Start building the main interface here.
        </s-paragraph>
      </s-section>
    </s-page>
  );
}

Title bar and navigation menu outside the iframe use App Bridge web components from @shopify/app-bridge-react:

import {TitleBar, NavMenu} from '@shopify/app-bridge-react';


export default function App() {
  return (
    <>
      <TitleBar title="Product Details" subtitle="SKU: ABC-123" />
      <NavMenu>
        <a href="/">Home</a>
        <a href="/products">Products</a>
        <a href="/settings">Settings</a>
      </NavMenu>
    </>
  );
}

Authenticating with your backend. Retrieve a session token with shopify.idToken() and send it as a bearer token:

export default function App() {
  const syncProducts = async () => {
    const token = await shopify.idToken();


    await fetch('/api/sync-products', {
      method: 'POST',
      headers: { Authorization: `Bearer ${token}` },
    });
  };


  return (
    <button onClick={syncProducts}>Sync products</button>
  );
}

Direct API access. Your app can query the Admin GraphQL API directly from front-end code using fetch(). App Bridge automatically authenticates these requests; use the shopify:admin/api/graphql.json URL:

async function getProducts() {
  const response = await fetch('shopify:admin/api/graphql.json', {
    method: 'POST',
    body: JSON.stringify({
      query: `
        query {
          products(first: 10) {
            edges {
              node {
                id
                title
              }
            }
          }
        }
      `,
    }),
  });
  const { data } = await response.json();
  return data.products.edges;
}

Configuration. App configuration lives in shopify.app.toml. To enable direct API access, set embedded_app_direct_api_access = true and control token mode with direct_api_mode (online = current user session; offline = persists for background jobs). You must declare the access scopes your app needs; merchants approve them on install.

# Add these settings to shopify.app.toml to control API access and scopes
[access_scopes]
scopes = "read_products,write_products"


[access.admin]
embedded_app_direct_api_access = true
direct_api_mode = "online"

When To Use

Use App Bridge for embedded, iframe-based apps that render in the admin and need to reach admin surfaces outside their iframe (navigation, title bars, resource workflows, toasts, modals) or to call the Admin GraphQL API directly. For simple extension-only apps with no backend, prefer an App Home UI extension instead. See Building apps for scaffolding and the app surface picker.

Risks & Pitfalls

• App Home apps run inside an iframe; UI added outside the iframe must go through App Bridge web components.
• Request only the access scopes your app actually needs.
• Loading libraries from the CDN pulls the latest version; keep the paired @latest type packages in step to avoid type drift.

Related Concepts

• Building apps
• App extensions
• Admin GraphQL API
• Authentication and access
• Shopify CLI

Sources

• raw/web_community-app-bridge-md.md
• raw/web_community-app-bridge-library-md.md