App home

The app home is the primary surface merchants use to interact with your app. It displays your app's interface in the Shopify admin and provides access to merchant data using Shopify's APIs. With Polaris components and App Bridge, you can build performant apps using familiar web technologies.

Anchor to Getting startedGetting started

To build for the App Home we recommend adding App Bridge and the Polaris Web Components to your application.

Polaris web components provide a consistent UI experience that matches the Shopify Admin while leveraging standard web platform features. To use these components in your app, you need to include the Polaris script in your application.

Apps that use these components can also include pre-built UI patterns that are implemented using Polaris web components. These patterns help you quickly build consistent, familiar experiences for merchants that follow Shopify's design guidelines.

New React Router Application

Start building your app fast with the Shopify CLI and the Shopify React Router App template. The CLI will set up App Bridge and the Polaris Web Components for you.

You will need to select:

Select Build a React Router app (recommended)
Select JavaScript OR TypeScript.

Existing Remix Application

Add the Polaris Web Components script tag to your app/root.tsx file's <head>.

To use the Remix router you will need to control the custom event shopify:navigate and push that into useNavigate.

Build your own way

When building your own way add the script tag right after the existing App Bridge script tag in your HTML head.

Setup

shopify app init

Setup

import {useNavigate} from '@remix-run/react';

export default function App() {

const navigate = useNavigate();

useEffect(() => {

const handleNavigate = (event) => {

const href = event.target.getAttribute('href');

if (href) navigate(href);

};

document.addEventListener('shopify:navigate', handleNavigate);

return () => {

document.removeEventListener('shopify:navigate', handleNavigate);

};

}, [navigate]);

return (

<html>

<head>

...

</head>

...

</html>

);

}

Anchor to ResourcesResources

Polaris web components

View all available components

Patterns

Common app home patterns

Storybook

Explore component examples

App Design Guidelines

Follow our UX guidelines when you're designing your app to ensure that they're predictable and easy to use.

Shopify CLI and Tools forum

Visit our Shopify CLI and Tools forum if you need help using Shopify App Bridge.

Figma Kit

Download the Figma Kit

Anchor to Your first API callYour first API call

The following example uses Resource Picker to open a UI component that enables users to browse, find, and select products from their store using a familiar experiences.

Anchor to TypeScriptTypeScript

Shopify App Bridge provides a companion npm library for TypeScript types, available at @shopify/app-bridge-types.

If you're using the React library, then the types package is already included.

Additionally, Shopify provides a companion npm library for Polaris web components types, available at @shopify/polaris-types.

App Bridge Installation

The @shopify/app-bridge-types package can be installed using yarn or npm.

App Bridge Configuration

Adding the @shopify/app-bridge-types package to your tsconfig.json file will enable type checking for all files in your project.

Polaris Web Components Installation

The @shopify/polaris-types package can be installed using yarn or npm. Specify latest in package.json if using https://cdn.shopify.com/shopifycloud/polaris.js.

Polaris Web Components Configuration

Adding the @shopify/polaris-types package to your tsconfig.json file will enable type checking for all files in your project.

Installation

npm install --save-dev @shopify/app-bridge-types

yarn add --dev @shopify/app-bridge-types

Installation

npm install --save-dev @shopify/polaris-types

yarn add --dev @shopify/polaris-types

{

"devDependencies": {

"@shopify/polaris-types": "latest"

}

Anchor to Global variableGlobal variable

After App Bridge is set up in your app, you have access to the shopify global variable. This variable exposes various App Bridge functionalities, such as displaying toast notifications or retrieving app configuration details.

To explore all the functionality available on the shopify global variable:

Open the Chrome developer console while in the Shopify admin.
Switch the frame context to your app's iframe.
Enter shopify in the console.

Anchor to Direct API accessDirect API access

You can make requests to the Admin API directly from your app using the standard web fetch API!

Any fetch() calls from your app to Shopify's Admin GraphQL API are automatically authenticated by default. These calls are fast too, because Shopify handles requests directly.

Direct API access is disabled by default. It can be enabled in your app TOML file, along with whether you want to use direct API access with online access or offline access mode.

Learn more about API access modesConfiguration guide

Anchor to MigrationMigration

If you have an app that uses components and hooks from Shopify App Bridge React 3.x.x, then you can follow the migration guide to upgrade your components and hooks to the latest version.

Anchor to Next stepsNext steps

Now that you've initialized your app, you can use any Shopify App Bridge features.

Support

If you need help using Shopify App Bridge, please visit our App Bridge community forum. It is the best place to discuss libraries and get support.

Was this page helpful?