---
title: "Shopify App Bridge and App Home"
type: concept
tags: [app-bridge, app-home, embedded-apps, polaris, session-token]
created: 2026-07-07
updated: 2026-07-07
sources: ["raw/web_community-app-bridge-md.md", "raw/web_community-app-bridge-library-md.md"]
source_url: "https://shopify.dev/docs/api/app-home"
confidence: high
---

## 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 [[concepts/shopify-cli|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:

```terminal
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:

```jsx
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`:

```jsx
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:

```jsx
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
[[concepts/admin-graphql-api|Admin GraphQL API]] directly from front-end code using
`fetch()`. App Bridge automatically authenticates these requests; use the
`shopify:admin/api/graphql.json` URL:

```jsx
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.

```toml
# 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
[[concepts/building-apps|Building apps]] for scaffolding and
[[syntheses/app-surface-picker|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

- [[concepts/building-apps|Building apps]]
- [[concepts/app-extensions|App extensions]]
- [[concepts/admin-graphql-api|Admin GraphQL API]]
- [[concepts/authentication-and-access|Authentication and access]]
- [[concepts/shopify-cli|Shopify CLI]]

## Sources

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