# Add a Theme App Extension to a Shopify App

Yes. An agent generates a theme app extension in your Shopify app, writes an app block and an app embed block with settings, runs Theme Check and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-theme-app-extension/shopify-app/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the app's configuration first, because a theme app extension is a second deployable inside the same repository. In an app built from Shopify/shopify-app-template-react-router, `package.json` runs `shopify app dev`, `shopify app generate` and `shopify app deploy` as scripts, lists `extensions/*` as npm workspaces, and pins React Router 7.18.2 for the reasons its `CHANGELOG.md` records. `shopify.app.toml` has an empty `client_id` for the template, `scopes = "write_products"`, webhook subscriptions for `app/uninstalled` and `app/scopes_update` on API version `2026-10`, and an `[events]` subscription that fires only when a variant's price changes. `extensions/` holds a `.gitkeep` and nothing else, and `.graphqlrc.ts` already loops over `extensions/*` looking for a `schema.graphql`, so a theme extension, which has none, is skipped cleanly. `app/routes/app._index.tsx` creates a product through `productCreate` as the template's demo, `app/routes/app.tsx` holds the `s-app-nav` menu, and `.github/workflows/ci.yml` runs `tsc --noEmit`, `npm run lint`, `prisma validate` and `npm run build` across Node 22 and 24 with npm, yarn and pnpm. The repository's `AGENTS.md` points every Shopify platform question at the Shopify Dev MCP server the template configures in `.mcp.json`.

The extension is generated with the CLI rather than written from scratch, so its layout matches what the platform expects: `shopify app generate extension --template theme_app_extension --name product-badge` creates `extensions/product-badge/` with `assets/`, `blocks/`, `snippets/`, `locales/`, a `package.json` and a `shopify.extension.toml` whose `type` is `theme`. The generated example is a product-rating block reading a `demo.avg_rating` metafield; the agent replaces it with what the app sells. An app block in `blocks/product-badge.liquid` renders a badge next to the product title with a `{% schema %}` that sets a `name` under 25 characters, `target: "content"`, `settings` for the badge text, a color and a toggle, `enabled_on` limited to `product` templates, and `stylesheet` and `javascript` entries naming files in `assets/`. An app embed block in `blocks/announcement-bar.liquid` with `target: "body"` injects a dismissible bar on every page once a merchant turns it on under Theme settings, App embeds, with its copy in `locales/en.default.json` so it can be translated.

The blocks stay inside the limits the platform enforces and the ones it suggests: 30 blocks, 10 MB in total, 100 KB of Liquid across the extension, 100 locale files of 15 KB each, and the suggested 10 KB of compressed JavaScript and 100 KB of CSS per block. The agent keeps the badge script to a few lines in `assets/product-badge.js` and the bar's dismiss state in `localStorage`, writes the two stylesheets with class names prefixed to the extension so they cannot collide with Dawn's, and adds a snippet in `snippets/` for the badge markup so both the block and a future section can render it. The app code does not change: a theme app extension reads settings from its own schema and the metafields the app writes, so the `write_products` scope and the existing routes stay as they are.

The checks are the ones that run without a Partner login. The agent runs the CLI's Theme Check against the extension directory, which validates the Liquid, the schema JSON and the asset references, then `npm run typecheck`, `npm run lint` and `npm run build` to be sure the workspace addition broke nothing in the app, and reads the extension's `shopify.extension.toml` back to confirm the `name`, `type` and `handle`. `shopify app dev` and `shopify app deploy` need the reader's Partner account and a development store, so the pull request says which command to run to preview the blocks in the theme editor on Dawn and what to look for: the badge on a product page, the embed under App embeds, both settings panels, and that the bar does not cover the page.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a theme app extension to this Shopify app. Read package.json, shopify.app.toml, .graphqlrc.ts, AGENTS.md, app/shopify.server.ts, the routes under app/routes and .github/workflows/ci.yml first. Generate the extension with shopify app generate extension --template theme_app_extension --name product-badge, then replace the generated rating example with an app block that renders a configurable badge on product pages (text, color and toggle settings, enabled only on product templates, with its stylesheet and script in assets) and an app embed block with target body that shows a dismissible announcement bar with translatable copy in locales/en.default.json. Keep each block within Shopify's enforced and suggested size limits and prefix every class name. Run Theme Check on the extension, npm run typecheck, npm run lint and npm run build, and open a pull request that quotes the output and tells the reviewer how to preview the blocks with shopify app dev in the theme editor.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request adds `extensions/product-badge/` with its `shopify.extension.toml`, two block files, one snippet, two stylesheets, one script and a locale file, and changes `package-lock.json` for the new workspace. Nothing under `app/` changes. Its description quotes the Theme Check result and the three npm commands, lists each block's settings, and ends with the preview steps: `shopify app dev`, open the host theme in the editor, add the badge block to the product template and enable the announcement embed.

A reviewer reads the two schemas, since settings are what merchants will see, and the Liquid, which runs inside every storefront that installs the app. The CI matrix runs the same type check, lint and build on the pull request. The preview on a development store is the one step only the reviewer can take, and the description tells them exactly what to check there before `shopify app deploy` creates a version.

## Run it on every Linear issue labelled theme

In the console, add an automation to the Project with this prompt and a `linear` trigger on `linear.issue.labeled`, filtered to the `theme` label. When an issue such as "merchants want to show the badge on product pages without editing their theme" gets the label, the trigger puts the issue after the prompt, and the run reads which block, settings and templates the issue asks for before generating anything. Only label changes by a person in your Rush org fire it, and the automation starts at most `max_runs_per_hour` runs in an hour.

An automation's runs are read-only, so the run that pushes the branch starts from your own server: a handler receiving the automation's comment sends this body to `POST /o/{org}/sessions` with the issue URL in `resources` and a `request_id` that is a UUID v5 of the issue id, so a redelivered event returns the run already started.

## Why run it on Rush?

A theme app extension has its own tooling, its own limits and its own review surface, and a mistake in it ships to every storefront that installs the app. The agent generates the extension with the CLI so the layout is the platform's, writes blocks against the schema fields and limits the documentation sets out, runs Theme Check and the app's own checks in its own sandbox, and keeps every command and its output in the run's record.

The agent also knows where its sandbox ends. Previewing in a theme editor needs the reader's Partner account, so instead of pretending, the pull request carries the exact steps to take there and what each should show, which is what a reviewer needs to finish the job in a few minutes.

## Frequently asked questions

### What is the difference between the two blocks?

An app block with `target: "content"` is placed by the merchant inside a section of an Online Store 2.0 theme and can be moved and configured in the editor. An app embed block with `target: "body"` has no placement: Shopify injects it before `</body>` on every page once the merchant enables it under App embeds, and it works in older themes too.

### Does the app need new scopes?

No. A theme app extension renders from its own settings and from data the app already writes, such as product metafields under `write_products`. If a block later needs a metafield the app does not write yet, that is an app change with its own pull request.

### Can the agent preview it in a store?

Not from the sandbox. `shopify app dev` signs in to a Partner account and pushes the extension to a development store, which only the reader can do. The agent runs Theme Check and the app's checks instead and writes the preview steps into the pull request.

### How are the size limits handled?

The agent keeps the script and stylesheets small and reads their sizes before opening the pull request, against the 10 MB total, 100 KB of Liquid and 30 blocks the platform enforces and the 10 KB of JavaScript and 100 KB of CSS it suggests per block. The description lists each file's size.

### Will merchants see the blocks right after deploy?

After `shopify app deploy` releases a version, app blocks appear in the theme editor's block picker and embeds under App embeds, switched off until the merchant turns them on. The pull request suggests a line for the app's onboarding page telling merchants where to find them.

## More Shopify App jobs

- [Move a Shopify App's Session Storage From SQLite to Postgres](https://getrush.ai/run/migrate-sqlite-to-postgres/shopify-app/)
- [Review Pull Requests on a Shopify App](https://getrush.ai/run/review-pull-requests/shopify-app/)
- [Write Vitest Tests for a Shopify App's Webhooks and Actions](https://getrush.ai/run/write-vitest-tests/shopify-app/)

## More jobs like this: Turn a Linear label into a PR

- [Add Throttling to a Django REST Framework API from a Linear Issue](https://getrush.ai/run/add-throttling/django-rest-framework/)
- [Add TLS with cert-manager to a Kubernetes App](https://getrush.ai/run/add-tls-with-cert-manager/kubernetes/)
- [Add Pagination to a Vapor API from a Linear Issue](https://getrush.ai/run/add-todo-pagination/vapor/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
