---
title: Build an App Home UI extension
description: >-
Build a custom-distribution app with a Shopify-hosted App Home page using a UI
extension. No backend required.
source_url:
html: 'https://shopify.dev/docs/apps/build/app-home/app-home-ui-extensions'
md: 'https://shopify.dev/docs/apps/build/app-home/app-home-ui-extensions.md'
api_name: app-home-ui-extension
---
# Build an App Home UI extension
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](https://shopify.dev/docs/apps/launch/distribution) that don't need server-side logic. For most apps, the [iframe model built with React Router](https://shopify.dev/docs/apps/build/scaffold-app) is still the recommended path.
To learn more about which option is right for your use case, see the [Apps in App Home](https://shopify.dev/docs/apps/build/app-home) page.
***
## What 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.
***
## Requirements
* You're a [user with app development permissions](https://shopify.dev/docs/apps/build/dev-dashboard/user-permissions) and have created a [dev store](https://shopify.dev/docs/apps/build/stores/development-stores). You can create one by running `shopify store create dev`.
- You're using the latest version of [Shopify CLI](https://shopify.dev/docs/api/shopify-cli).
- You're using the latest version of [Chrome](https://www.google.com/chrome/) or [Firefox](https://www.mozilla.org/).
***
## Step 1: (Optional) Set up Shopify AI Toolkit
Install the [Shopify AI Toolkit](https://shopify.dev/docs/apps/build/ai-toolkit) to connect your AI coding assistant to Shopify's docs, APIs, and CLI. Your assistant gets the Shopify context it needs to answer questions, write code, and run commands more reliably.
#### Claude Code
In your terminal, run `claude plugin install`:
## Terminal
```terminal
claude plugin install shopify-ai-toolkit@claude-plugins-official
```
#### Codex
In your terminal, run `codex plugin add`:
## Terminal
```terminal
codex plugin add shopify@openai-curated
```
#### Antigravity CLI
In your terminal, install the Shopify plugin:
## Terminal
```terminal
agy plugin install https://github.com/Shopify/shopify-ai-toolkit
```
#### Cursor
In Cursor Chat, add the Shopify plugin:
## Cursor Chat
```terminal
/add-plugin shopify
```
#### Hermes
In your terminal, download the install script and run it:
## Terminal
```terminal
curl -fsSL https://raw.githubusercontent.com/Shopify/Shopify-AI-Toolkit/main/.hermes-plugin/install.sh -o /tmp/shopify-hermes-install.sh
bash /tmp/shopify-hermes-install.sh
```
#### OpenClaw
In your terminal, install the Shopify plugin from npm:
## Terminal
```terminal
openclaw plugins install npm:@shopify/ai-toolkit
```
#### Pi
In your terminal, install the package from npm:
## Terminal
```terminal
pi install npm:@shopify/ai-toolkit
```
#### VS Code
1. Ensure the [Agent plugins](https://code.visualstudio.com/docs/copilot/customization/agent-plugins) preview is enabled in your VS Code settings.
2. Open the Command Palette (`Cmd+Shift+P` on macOS, `Ctrl+Shift+P` on Windows/Linux) and run:
## VS Code: Command Palette
Chat: Install Plugin From Source
3. When prompted, enter the repository URL:
## VS Code: Plugin source URL
https://github.com/Shopify/shopify-ai-toolkit
***
## Step 2: 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
```terminal
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.
***
## Step 3: 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
```toml
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](https://shopify.dev/docs/api/app-home-ui-extension/latest#configuration).
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
```tsx
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(, document.body);
};
function App() {
return (
);
}
```
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.
***
## Step 4: 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
```terminal
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**.
***
## Step 5: 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](https://shopify.dev/docs/apps/launch/distribution/select-distribution-method) and [Deploy app versions](https://shopify.dev/docs/apps/launch/deployment/deploy-app-versions).
***
## Next steps
[App Home UI extension reference\
\
](https://shopify.dev/docs/api/app-home-ui-extension/2026-07-rc)
[Explore the target, target APIs, and web components available to App Home UI extensions.](https://shopify.dev/docs/api/app-home-ui-extension/2026-07-rc)
[Configure app extensions\
\
](https://shopify.dev/docs/api/app-home-ui-extension/latest#configuration)
[See the full list of configurable properties for the `shopify.extension.toml` file.](https://shopify.dev/docs/api/app-home-ui-extension/latest#configuration)
[Build an extension-only app\
\
](https://shopify.dev/docs/apps/build/app-extensions/build-extension-only-app)
[Learn what other extensions you can include in an extension-only app.](https://shopify.dev/docs/apps/build/app-extensions/build-extension-only-app)
[Apps in App Home\
\
](https://shopify.dev/docs/apps/build/app-home)
[Compare the iframe and UI extension models, and decide which is right for your app.](https://shopify.dev/docs/apps/build/app-home)
***