App Home UI extensions

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 extensions, open modals and workflows, and access your app's data.

App Home UI extensions render your app's landing page as a Preact-based extension module, so you can ship App Home alongside your other admin UI extensions from the same app bundle. Shopify hosts the entire extension, so you don't need to run or deploy a web server for the App Home experience.

Use this when you're building a custom app and want the persistent, full-page workspace of App Home without managing your own hosting.

Choose a version:

Anchor to When to use this extension typeWhen to use this extension type

Note

App Home UI extensions can be used only for custom-distribution apps. If you want to build a public app you can distribute through the Shopify App Store, then use the iframe-based App Home solution.

With App Home UI extensions, you can build a custom app without managing your own hosting. Shopify hosts the entire extension, including your JavaScript bundle and static assets, so you can deploy your whole app to Shopify with shopify app deploy. There's no web server to provision, no infrastructure to maintain, and no separate iframe-hosted frontend to ship.

This works well for simple, self-contained apps that fit inside the Remote DOM runtime and don't need their own backend. If your app needs webhooks, background jobs, or other server-side functionality, then you'll still need to host your own backend for those use cases and call it from the extension.

To build a landing page for your app in the App Home surface, you can use an App Home UI extension (described in this reference), or build an iframe-based App Home app. Use App Home UI extensions when you want:

A custom app you can deploy entirely to Shopify, with no hosting of your own.
A persistent, full-page app workspace that's part of your extension bundle rather than a separate iframe-hosted web app.
A single source of truth for your app's primary UI alongside your other admin UI extensions.
The performance and design-system benefits of Polaris web components without hosting a web server for the App Home experience.

Use the iframe-based App Home when your app needs a full backend with server-side rendering, webhooks, or access to browser APIs that aren't available in the Remote DOM runtime. To learn more about the differences between App Home UI extensions and iframe-based App Home apps, see Apps in App Home.

Anchor to Getting startedGetting started

App Home UI extensions are a special type of admin UI extensions that render a landing page for your app as a Preact-based extension module. You configure it the same way as any other admin UI extension, with a shopify.extension.toml configuration file and a TSX or JSX module.

To start building your first App Home UI extension, scaffold it using Shopify CLI. You can either add your extension to an existing app, or create a new extension-only app from scratch.

The command creates a framework for building an extension-only app that includes a basic App Home landing page using the admin.app.home.render target.

shopify app init

# select "Build an extension-only app" when prompted

cd my-app

shopify app generate extension

# select the "App Home UI" extension type when prompted

Scaffold a new app

shopify app init

# select "Build an extension-only app" when prompted

Add to an existing app

cd my-app
shopify app generate extension

# select the "App Home UI" extension type when prompted

Anchor to Building your extensionBuilding your extension

App Home UI extensions render your app's landing page in the App Home surface using the admin.app.home.render target. To build your app, you use target APIs that provide access to data and functionality, and web components to render your app's UI.

Anchor to APIs: Define what your extension doesAPIs: Define what your extension does

Your extension can use APIs to perform actions like launching Shopify admin workflows, querying the GraphQL Admin API, and storing data in browser storage.

When your extension runs, Shopify provides a shopify global object that you use to access data and features. Most APIs for App Home UI extensions are properties on this object. For example, shopify.intents launches Shopify admin workflows, shopify.query runs GraphQL Admin API queries, and shopify.storage stores data in browser storage.

If your app uses ESLint, then update your configuration to include the global shopify object to prevent linting errors.

ReferenceExplore all target APIs

Anchor to Web components: Design your interfaceWeb components: Design your interface

Web components are the UI building blocks that you use to display data and trigger API functions. These components are native UI elements that follow Shopify's design system and are built with remote-dom, Shopify's library for building cross-platform user interfaces.

Use web components to build interfaces that integrate with Shopify's admin design system.

ReferenceExplore all web components

Anchor to ConfigurationConfiguration

Admin UI extensions rely on a shopify.extension.toml file that contains the extension's configuration. This includes the extension name, type, API version, and targeting definitions.

The name value is what displays in the admin interface to merchants, so consider this value carefully. We recommend that the api_version reflects the latest supported API version.

Anchor to PropertiesProperties

App Home UI extensions use the following configuration properties:

api_version required

The version of the API that's being used for the extension. If provided in the [[extensions]] array, then the specified API version is used instead of the root level api_version.

[[extensions]] required

The name of the array that contains all extensions listed in the TOML file. Contains the following properties:

type: required The extension type. For App Home UI extensions, use ui_extension.
name: required The merchant-facing name of the extension. After you generate an extension, you're prompted to provide a name for your extension. The name property is translatable if it starts with a t: and uses a key defined in your translation data.

Limitations:
- 5 characters minimum
- 30 characters maximum
handle: required The unique internal identifier for the extension. After you create a draft version of the extension, or deploy an extension, you can't change the handle value.

Limitations:
- Allowed characters: a-z, A-Z, 0-9, -
- 100 characters maximum
- Must be unique within the app
uid: required The extension user identifier that must be unique within the app. An app-scoped identifier used by shopify app deploy to determine whether an extension is being created, updated, or deleted.
description: optional The merchant-facing description of the extension.

[[extensions.targeting]] required

The name of the array that contains a target and its associated module. Contains the following properties:

target: required

An identifier that specifies where you're injecting your extension into the admin interface. For App Home UI extensions, use admin.app.home.render.
module: required

The path to the JavaScript or TypeScript file that contains your extension code. This file exports the extension function that renders your UI or handles events.
assets:

The path to the directory that contains your extension's static files (such as images and icons). Allowed file extensions are .png, .jpg, .jpeg, .gif, .webp, .avif, .ico, .txt, .md, and .json. SVG files aren't supported in the asset bundle. For per-file and total bundle size limits, see Limits.

Important
When you upload assets, the content must comply with Shopify's API Terms of Service. Don't upload personally identifiable information (PII), and ensure you have the rights to all assets you upload.

Anchor to Direct API accessDirect API access

Use direct API access when your extension needs to query or modify Shopify data in real-time. For example, you might want to update product metafields, fetch detailed order information, or modify inventory levels.

You can make GraphQL Admin API requests directly from your extension using the query method in the Standard API or the standard web fetch API. Any fetch() calls from your extension to the GraphQL Admin API are automatically authenticated by default.

You must declare all required access scopes in your app's TOML file.

Note

Direct API can't be used to manage storefront access tokens.

Query Shopify data directly

import {render} from 'preact';

export default async () => {

const products = await getProducts();

render(<Extension products={products} />, document.body);

};

async function getProducts() {

const res = await fetch('shopify:admin/api/graphql.json', {

method: 'POST',

body: JSON.stringify({

query: `

query GetProducts {

products(first: 5) {

nodes {

title

}

}),

});

const {data} = await res.json();

return data.products.nodes;

}

function Extension({products}) {

return (

<s-page heading="Product overview">

<s-section heading="Recent products">

<s-stack direction="block">

{products.map((product) => (

<s-text key={product.id}>{product.title}</s-text>

))}

</s-stack>

</s-section>

</s-page>

);

}

import {render} from 'preact';

export default async () => {

const {

data: {products},

} = await shopify.query(

query GetProducts {

products(first: 5) {

nodes {

title

}

);

render(<Extension products={products.nodes} />, document.body);

};

function Extension({products}) {

return (

<s-page heading="Product overview">

<s-section heading="Recent products">

<s-stack direction="block">

{products.map((product) => (

<s-text key={product.id}>{product.title}</s-text>

))}

</s-stack>

</s-section>

</s-page>

);

}

Using fetch

import {render} from 'preact';

export default async () => {
  const products = await getProducts();
  render(<Extension products={products} />, document.body);
};

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

function Extension({products}) {
  return (
    <s-page heading="Product overview">
      <s-section heading="Recent products">
        <s-stack direction="block">
          {products.map((product) => (
            <s-text key={product.id}>{product.title}</s-text>
          ))}
        </s-stack>
      </s-section>
    </s-page>
  );
}

Using shopify.query

import {render} from 'preact';

export default async () => {
  const {
    data: {products},
  } = await shopify.query(
    `
    query GetProducts {
      products(first: 5) {
        nodes {
          id
          title
        }
      }
    }
  `,
  );
  render(<Extension products={products.nodes} />, document.body);
};

function Extension({products}) {
  return (
    <s-page heading="Product overview">
      <s-section heading="Recent products">
        <s-stack direction="block">
          {products.map((product) => (
            <s-text key={product.id}>{product.title}</s-text>
          ))}
        </s-stack>
      </s-section>
    </s-page>
  );
}

Anchor to Custom protocolsCustom protocols

Custom protocols make it easier to navigate to common locations and construct URLs within your extensions.

Anchor to Shopify protocolShopify protocol

Use the shopify:admin protocol when you want to construct a URL with a root of the Shopify admin.

Shopify protocol

<s-link href="shopify:admin/products/1234567890">Link to Product Page</s-link>;

fetch('shopify:admin/api/graphql.json', {

method: 'POST',

body: JSON.stringify(simpleProductQuery),

});

Link to product page

<s-link href="shopify:admin/products/1234567890">Link to Product Page</s-link>;

Fetch data

fetch('shopify:admin/api/graphql.json', {
  method: 'POST',
  body: JSON.stringify(simpleProductQuery),
});

Anchor to App protocolApp protocol

Use the app: protocol to construct a URL for your app. Shopify handles constructing the base URL for your app. This works for both apps rendered in the Shopify admin and standalone apps.

Anchor to Relative URLsRelative URLs

Relative urls are relative to your app and are useful when you want to link to a route within your app. This works for both apps rendered in the Shopify admin and standalone apps.

Anchor to LimitsLimits

Keep these limits in mind when you design your App Home UI extension. They apply at deployment, so your bundle won't upload if it exceeds them.

Compiled bundle size: 64 KB compressed. Shopify enforces this at deployment to keep load times fast. See analyze your bundle size for help staying under the limit.
Static asset file size: Each asset file can be up to 1 MB.
Static asset bundle: Your bundle can include up to 500 files, with a total size of 50 MB.
Targets per app: Each app can have only one admin.app.home.render target.

Anchor to Testing and deploymentTesting and deployment

After you've built your extension, test it thoroughly and deploy it to production.

Anchor to Local testingLocal testing

Info

As of API version 2026-04, you can write unit tests for admin UI extensions using @shopify/ui-extensions-tester. Check out the example test suite to get started.

To run your extension locally during development, start a dev server using Shopify CLI. The dev command creates a preview of your extension on your chosen dev store. If your extension is built on an app with a backend, then this command also serves your backend locally using a Cloudflare tunnel.

The dev server automatically reloads your extension when you make changes to your code, so you can test updates in real-time.

Anchor to DeploymentDeployment

Deploy your extension to production using Shopify CLI.

The Shopify CLI deploy command builds your extension bundle and uploads everything to Shopify.

Anchor to VersioningVersioning

Polaris reference docs follow Shopify's API versioning policy. Each stable version is supported for a minimum of 12 months. Older versions continue to work, they just won't have dedicated docs on Shopify.dev. Shopify CLI already prevents deploys targeting API versions older than 12 months, so we recommend keeping your extensions on a supported version.

Was this page helpful?