App Home UI extensions

App Home UI extensions are a Shopify-hosted alternative to the developer-hosted iframe model. You build your app's main page as a Preact UI extension that renders in the App Home area of Shopify admin, with no backend server to host or maintain. This path is for custom-distribution apps that don't need server-side logic. For most apps, the iframe model with React Router is still the recommended path.

To learn more about which option is right for your use case, see the Apps in App Home page.

Anchor to What you'll learnWhat you'll learn

In this tutorial, you'll learn how to do the following tasks:

• Scaffold an extension-only app with an App Home UI extension using Shopify CLI.
• Run your extension in a dev store and preview your changes.
• Deploy the extension as part of an app version.

Anchor to RequirementsRequirements

• You're a user with app development permissions and have created a dev store.

• You're using the latest version of Shopify CLI.
• You're using the latest version of Chrome or Firefox.

Anchor to Step 1: Scaffold an extension-only appStep 1: Scaffold an extension-only app

Scaffold a new app and select the extension-only template. The template includes an App Home UI extension by default, so the scaffolded app already has a templated app with a landing page.

1. Navigate to the directory where you want to create your app.

2. Run the following command:

   Terminal

   Copy

   $

   $

   shopify app init

3. When prompted, enter a name for your app and select Build an extension-only app.

   Shopify CLI creates a new app with an extensions/app-home/ folder containing the configuration and source files for your App Home UI extension.

Anchor to Step 2: Examine the generated extensionStep 2: Examine the generated extension

Open the new app in your editor and look at the files that Shopify CLI generated for the extension.

1. Open extensions/app-home/shopify.extension.toml.

   The file declares a UI extension that targets admin.app.home.render. The module property points to the Preact entry file that renders the page.

   extensions/app-home/shopify.extension.toml

   Copy

   99

   1

   2

   3

   4

   5

   6

   7

   8

   9

   10

   11

   12

   13

   14

   15

   16

   17

   api_version = "2026-07"

   
   

   [[extensions]]

   # Change the merchant-facing name of the extension in locales/en.default.json

   name = "t:name"

   handle = "app-home"

   uid = "83247469-d4a8-2612-c903-5468f6914aaa918849e8"

   type = "ui_extension"

   
   

   # Only 1 target can be specified for each Admin block extension

   [[extensions.targeting]]

   module = "./src/AppHome.jsx"

   target = "admin.app.home.render"

   
   

   [access_scopes]

   # Learn more at https://shopify.dev/docs/apps/tools/cli/configuration#access_scopes

   scopes = "write_metaobject_definitions,write_metaobjects,write_products"

   For the full set of configurable properties, see Configuring app extensions.

2. Open extensions/app-home/src/AppHome.jsx.

   This is the entry module for the extension. It provides a single-page app skeleton that uses client-side routing to serve multiple pages in the Shopify admin.

   extensions/app-home/src/AppHome.jsx

   Copy

   99

   1

   2

   3

   4

   5

   6

   7

   8

   9

   10

   11

   12

   13

   14

   15

   16

   17

   18

   19

   20

   21

   22

   23

   24

   import {render} from 'preact';

   import {LocationProvider, ErrorBoundary, Router, Route} from 'preact-iso';

   
   

   import HomePage from './pages/HomePage.jsx';

   import FaqPage from './pages/FaqPage.jsx';

   import NotFoundPage from './pages/NotFoundPage.jsx';

   
   

   export default async () => {

   render(<App />, document.body);

   };

   
   

   function App() {

   return (

   <LocationProvider>

   <ErrorBoundary>

   <Router>

   <Route path="/" component={HomePage} />

   <Route path="/faq/:id" component={FaqPage} />

   <Route default component={NotFoundPage} />

   </Router>

   </ErrorBoundary>

   </LocationProvider>

   );

   }

   The home page for your app is defined in extensions/app-home/src/pages/HomePage.jsx. The HomePage serves as the index view for an FAQ-manager app and displays either an empty state or a table listing all the app's FAQs. FaqPage.jsx handles both creation (/faq/new) and editing (/faq/:id) in a single form-based detail view. The two pages are connected through client-side routing using the preact-iso library.

Anchor to Step 3: Run your appStep 3: Run your app

Start a local development server and preview the extension in your dev store's admin.

1. From the app's root directory, run the following command:

   Terminal

   Copy

   $

   $

   shopify app dev

2. When prompted, select your dev store.

3. Press p to open the preview URL.

Your dev store opens at your app's home page. To open the FAQ editor, click Create FAQ.

Anchor to Step 4: Deploy your extensionStep 4: Deploy your extension

App Home UI extensions deploy as part of an app version. There's no separate hosting step.

1. From the app's root directory, run shopify app deploy to release a new app version.

2. Install the released version on your dev store with custom distribution. For details, see Select a distribution method and Deploy app versions.

Anchor to Next stepsNext steps

App Home UI extension reference

Explore the target, target APIs, and web components available to App Home UI extensions.

Configure app extensions

See the full list of configurable properties for the shopify.extension.toml file.

Build an extension-only app

Learn what other extensions you can include in an extension-only app.

Apps in App Home

Compare the iframe and UI extension models, and decide which is right for your app.