App home
App Home is a dedicated area in Shopify admin for your app to render its landing page and UI. Merchants use the UI in this space to navigate to your app's other pages, open modals and workflows, and access your app's data.
Your app communicates with other parts of Shopify admin using a JavaScript SDK called App Bridge and renders UI using web components. By using App Bridge together with the web components from Shopify's Polaris design system, you can build performant apps using familiar web technologies.
Anchor to Getting startedGetting started
To start building your first app in App Home, scaffold an app using the Shopify CLI. When prompted to choose the type of app you want to build, select Build a React Router app.
The command creates an app framework that includes all of the Shopify App Bridge and Polaris libraries you need to build your own Shopify app in App Home.
Anchor to Building your appBuilding your app
When you open your app, its landing page is rendered in the App Home area of the Shopify admin. For merchants to use your app's features, you provide UI elements on this landing page like buttons, menus, and forms.
To add these UI elements inside the App Home, we recommend you use Polaris web components. Using Polaris ensures that your app looks and behaves like the rest of the Shopify admin. If you want to build your own UI elements, you can also use any framework and custom HTML elements you want, including vanilla JavaScript, React, or Vue.
The App Home area in Shopify admin is implemented as an iframe. To interact with other Shopify admin components outside this iframe, apps in App Home use Shopify's App Bridge JavaScript SDK.
Use App Bridge APIs to communicate with Shopify admin, and App Bridge web components to add UI elements such as title bars and navigation menus to other parts of Shopify admin outside the app's iframe.
Anchor to Web componentsWeb components
You add UI to your app using web components. Shopify provides a set of components which match the Shopify design system in its Polaris library. With these native UI elements, you can create consistent, accessible, and performant user interfaces that match the rest of the Shopify admin.
Because Polaris components are built on the Web Components standard, they work like native HTML elements. You can use them in any framework or with vanilla JavaScript, just like you would a <button> or <input>.
Anchor to APIsAPIs
Your app uses APIs to read information from Shopify admin, launch workflows like creating products or editing orders, and provide feedback to merchants through toasts and modals. The APIs in Shopify's App Bridge library provide provide this functionality through the shopify global variable.
When the App Bridge script is included in your app, you don't need to set up or configure any additional authentication to use these APIs. Your app runs inside an authenticated session in Shopify admin, so you don't need to manage tokens or headers yourself.
Apps scaffolded with Shopify CLI already include the App Bridge script, so you don't need to add it manually.
Anchor to App Bridge web componentsApp Bridge web components
With App Bridge web components you can add UI elements like title bars and navigation menus to the main Shopify admin area outside of your app's iframe.
Anchor to Page patternsPage patterns
We've created page templates for common patterns like landing pages and settings pages, so your app looks and behaves consistently with the Shopify admin and meets Built for Shopify standards.
We've also created UI compositions (combinations of Polaris web components and APIs) you can add to your app's pages for common needs like data tables, empty states, and setup flows.
Anchor to Direct API accessDirect API access
Your app can query the Shopify Admin GraphQL API directly from its front-end code using the standard fetch() API.
For example, you can use direct API access to load product or order data when a merchant navigates to a page, or to display real-time inventory levels in your app's UI.
App Bridge automatically authenticates these requests, so you don't need to manage tokens or headers yourself. Use the shopify:admin/api/graphql.json URL to make authenticated requests to the Admin GraphQL API.
Anchor to ConfigurationConfiguration
You define your app's configuration in the shopify.app.toml file. This file controls how your app authenticates, what data it can access, and how it integrates with Shopify admin.
When you scaffold your app using Shopify CLI, a shopify.app.toml configuration file with some basic settings is created for you. You can give your app permissions to access Shopify data and to make direct calls to the Admin GraphQL API by editing this file.
Anchor to Access scopesAccess scopes
Access scopes define what Shopify data your app can read or write using the Admin GraphQL API. You must declare the scopes your app needs before you can query the Admin API.
When merchants install your app, they're prompted to approve these permissions. Request only the scopes your app actually needs.
Anchor to Direct API accessDirect API access
For your app to make direct calls to the Admin GraphQL API, you need to enable direct API access in your configuration file using the embedded_app_direct_api_access property.
Direct API access can use either online or offline access tokens. Online tokens are tied to the current user session, while offline tokens persist and work for background jobs.
Use the direct_api_mode property in your configuration to control which mode your app uses.
Anchor to Testing and deploymentTesting and deployment
Shopify CLI provides a set of tools to help you test and deploy your app.
Anchor to Local developmentLocal development
To run your app locally during development, start a dev server using Shopify CLI. This command creates a tunnel so Shopify can reach your local app.
Your app opens in your development store where you can test changes in real time. The CLI watches for file changes and automatically reloads your app.
Anchor to DeploymentDeployment
When you're ready to go live, deploy your app, and then sync your app to Shopify using Shopify CLI.
Deploy your app to a hosting service like Google Cloud Run, Fly.io, or Render. This is where your app runs and handles requests from Shopify.
Using the Shopify CLI deploy command then syncs your app configuration and extensions to Shopify so that merchants can install your app.
