Skip to main content
Back to changelog

Build App Home as a UI extension

App Home UI extensions let custom-distribution apps build a Shopify-hosted App Home page with Preact, Polaris web components, and the admin.app.home.render target.

App Home UI extensions are available for custom-distribution apps starting in API version 2026-07. They let you build your app's App Home page as a Shopify-hosted Preact UI extension using the admin.app.home.render target, so lightweight apps can ship a primary admin workspace without hosting a separate web app.

The iframe model remains recommended for most apps, especially public apps and apps that need server-side logic. App Home UI extensions give extension-only apps a simpler path when they fit the runtime constraints.

Anchor to App Home todayApp Home today

Every Shopify app has a main experience inside the Shopify admin called App Home. This is where merchants go to configure settings, view data, and manage workflows in your app.

Historically, apps have built App Home with the developer-hosted iframe model. You scaffold an app with Shopify CLI, build it with your preferred web framework, host the app yourself, and Shopify embeds that app inside the admin.

That model is still the right default for most apps because it gives you the full web platform:

  • Use any web framework.
  • Host server-side logic and backend routes.
  • Use full browser APIs.
  • Build multi-page and full-stack app experiences.
  • Use App Bridge APIs, App Bridge web components, Polaris web components, and the GraphQL Admin API.
  • Ship through public or custom distribution.

For many apps, that flexibility is exactly what App Home needs.

Anchor to Where the iframe model can be more than you needWhere the iframe model can be more than you need

Some apps don't need a full developer-hosted web app just to render their primary admin workspace. A custom-distribution app might be mostly extension-based. An internal workflow app might have a simple dashboard, setup flow, or resource manager. An extension-only app might not need server-side rendering, webhooks, or a separate backend at all.

In those cases, the iframe model can add infrastructure that isn't central to the app's workflow. You still need a hosted web surface for App Home, even when the app's main UI could run in the same extension model as the rest of the app.

App Home UI extensions give those apps another option.

Anchor to Introducing App Home UI extensionsIntroducing App Home UI extensions

App Home UI extensions are a Shopify-hosted way to build an App Home page. Instead of hosting an iframe-based web app for the primary workspace, you build a Preact UI extension that targets admin.app.home.render.

The extension is configured in shopify.extension.toml:

api_version = "2026-07"

[[extensions]]
name = "t:name"
type = "ui_extension"

[[extensions.targeting]]
module = "./src/AppHome.jsx"
target = "admin.app.home.render"

With this model, your App Home page runs in the admin extension runtime, renders with Polaris web components, and deploys as part of an app version. Shopify hosts the extension, so there's no separate App Home web server to deploy or maintain.

Anchor to How it worksHow it works

App Home UI extensions don't replace iframe-based App Home for every app. They give custom-distribution apps a focused path when the extension runtime is enough for the app's main workspace.

  1. App Home becomes an extension target: The admin.app.home.render target renders your extension in the App Home area of Shopify admin. Your extension entry module points to a Preact file, such as extensions/app-home/src/AppHome.jsx. The generated template can use client-side routing for simple multi-page flows. For example, a single App Home UI extension can render a home page, a detail page, and a not-found page from the same entry module.

  2. Your UI ships with the extension bundle: App Home UI extensions live alongside your other app extensions. Shopify CLI creates an extensions/app-home/ folder that contains the extension configuration and source files. This means your app's primary UI can share the same extension-based workflow as the rest of the app. You can preview it with shopify app dev and deploy it with shopify app deploy as part of an app version.

  3. Shopify hosts the App Home surface: Because Shopify hosts the extension, you don't need a separate hosting step for the App Home page. This is useful when your app's main workspace is a lightweight dashboard, configuration page, resource manager, or guided workflow that can run entirely in the extension runtime.

  4. The runtime has constraints: App Home UI extensions are intentionally more constrained than the iframe model. Use this model only when those constraints fit your app:

  • App Home UI extensions are for custom-distribution apps.

  • The runtime uses Preact.

  • UI is built with Polaris web components.

  • Browser APIs are limited compared to a developer-hosted web app.

  • The compressed bundle size limit is 64 KB.

  • If you outgrow the runtime, you reauthor the App Home experience as an iframe app.

    If your app needs public distribution, server-side logic, webhooks, unrestricted browser APIs, or the full flexibility of a web framework, continue using the iframe model.

Anchor to Get startedGet started

You can scaffold a new extension-only app with an App Home UI extension using Shopify CLI:

  1. Run shopify app init.
  2. Select Build an extension-only app when prompted.
  3. Open extensions/app-home/shopify.extension.toml and confirm that the extension targets admin.app.home.render.
  4. Run shopify app dev and select your development store.
  5. Press p to open the preview URL and test the App Home page in Shopify admin.
  6. Deploy the extension as part of an app version with shopify app deploy.

You can also add an App Home UI extension to an existing app by running shopify app generate extension and selecting App home when prompted.

Anchor to Related docsRelated docs

Was this page helpful?