# Add a Checkout UI Extension to a Shopify App

Yes. An agent scaffolds a checkout UI extension in your app's extensions workspace with Preact and Polaris web components, typechecks and lints it, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-checkout-ui-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 shape first, because an extension lives beside the app rather than inside it. In an app built from Shopify/shopify-app-template-react-router, `package.json` declares `"workspaces": {"packages": ["extensions/*"]}`, so anything under `extensions/` installs with the root `npm install`, and the only thing there today is `extensions/.gitkeep`. `shopify.app.toml` sets `api_version = "2026-10"` for webhooks and events and `scopes = "write_products"`; `app/shopify.server.ts` pins `ApiVersion.October26` to match. `tsconfig.json` includes `**/*.ts` and `**/*.tsx` from the root with `"jsx": "react-jsx"` and no `jsxImportSource`, and `.eslintrc.cjs` already declares a `shopify` global as read-only, which the changelog says was added for UI extensions. `.gitignore` already ignores `/extensions/*/dist`. The CI workflow runs `npx tsc --noEmit`, `npm run lint`, `prisma validate` and `npm run build` across Node 22 and 24 with npm, yarn and pnpm, so whatever the agent adds under `extensions/` is typechecked and linted on every push.

Shopify's checkout UI extension reference describes the pieces, and the agent writes them by hand because `shopify app generate extension --template checkout_ui`, the CLI command that would scaffold them, signs in to a Partner account the sandbox does not have. `extensions/order-note/shopify.extension.toml` gets `api_version = "2026-10"`, the same version as the app, one `[[extensions]]` entry with `type = "ui_extension"`, a `name` and a `handle` of `order-note`, and one `[[extensions.targeting]]` entry with `target = "purchase.checkout.block.render"` and `module = "./src/Checkout.tsx"`. The reference lists `uid` as required and generated by the CLI, so the agent leaves that key out rather than inventing an id and says in the pull request that the CLI writes it on the reader's first `shopify app dev` or `shopify app deploy`. No `[extensions.capabilities]` entry is added: a block that renders text needs neither `network_access` nor `api_access`, and `block_progress` would stop buyers.

`src/Checkout.tsx` follows the reference's Preact form: it imports `@shopify/ui-extensions/preact`, imports `render` from `preact`, and exports a default `extension()` function that calls `render(<Extension />, document.body)`. The component is Polaris web components, an `s-banner` holding `s-text`, with the merchant-facing string read from `locales/en.default.json` so the copy can be translated later rather than hard-coded. `extensions/order-note/package.json` lists `@shopify/ui-extensions` and `preact` so the workspace install pulls them, and a local `tsconfig.json` sets `"jsx": "react-jsx"` with `"jsxImportSource": "preact"`, because the root config's React JSX settings would type the `s-` elements wrongly. The root `tsconfig.json` gets `extensions` added to an `exclude` list so `npm run typecheck` keeps checking the app with React's JSX and the extension with Preact's, and the `.eslintrc.cjs` React override is scoped the same way.

Then the agent checks everything that does not need a store. It runs `npm install`, confirms the workspace resolved the extension's packages, runs `npx tsc --noEmit` at the root and inside the extension, `npm run lint` and `npm run build`, so the three CI jobs will pass. It bundles `src/Checkout.tsx` with `esbuild` to a single file and reads its size against the 64 KB limit the reference sets for a checkout extension bundle; a text block is far under it, and the number goes in the pull request. What it cannot do is preview: `shopify app dev` creates the preview on the reader's development store and `shopify app deploy` publishes a version, both with the reader's Partner sign-in, and the pull request puts those two commands and the step of placing the block in the checkout editor at the top of its description.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a checkout UI extension to this Shopify app that shows a short banner in checkout. Read package.json, shopify.app.toml, app/shopify.server.ts, tsconfig.json, .eslintrc.cjs, .gitignore and .github/workflows first. Create extensions/order-note with a shopify.extension.toml at the app's api_version, type ui_extension, a name and handle, and one targeting entry for purchase.checkout.block.render pointing at src/Checkout.tsx; leave uid for the CLI to write and add no capabilities. Write src/Checkout.tsx with Preact and Polaris web components as Shopify's checkout UI extension reference shows, with the text in locales/en.default.json, a package.json listing @shopify/ui-extensions and preact, and a tsconfig.json with jsxImportSource preact; exclude extensions from the root tsconfig and scope the React ESLint override so both still pass. Run npm install, tsc at the root and in the extension, the lint and the build, and measure the bundled size against the 64 KB limit. Do not run shopify app dev or deploy. Open a pull request that links the issue, lists the commands and their output, and says which steps need the reader's Partner account.",
  "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/order-note/` with `shopify.extension.toml`, `package.json`, `tsconfig.json`, `src/Checkout.tsx` and `locales/en.default.json`, and changes `tsconfig.json` and `.eslintrc.cjs` at the root. The app's routes, `shopify.app.toml` and the Prisma schema are untouched. Its description quotes the typecheck, lint and build output, gives the bundle size, and opens with the three steps that need the reader: `shopify app dev` to preview on a development store, placing the block in the checkout editor, and `shopify app deploy` to publish a version, after which the CLI has written the `uid` and the reader commits that line.

A reviewer checks the `handle`, which the reference says cannot change after a draft or deployment, the `target`, since a block placed by the merchant is a different thing from a static target that renders without placement, and the wording in the locale file. The CI run on the pull request already covers the typecheck and lint across the matrix, so the review is about what the extension says and where it appears, not whether it compiles.

## Run it on every Linear issue labelled checkout

A team that triages in Linear adds an automation to the Project with a `linear` trigger on `linear.issue.labeled`, the label `checkout` and `plan` mode, so the agent reads the issue and the app and posts the target, the files it would add and the capabilities it would or would not request as a comment on the issue. Only a change by a member of the Rush org fires it, and the comment is the whole result: an automation's runs are read-only and push nothing.

When the plan is agreed, a handler on the team's own server starts the run that pushes: it sends this body with the Linear issue URL added to `resources`, which puts the issue text in front of the agent through the team's Linear connection, and a `request_id` that is a UUID v5 of the issue id, so a redelivered event returns the run already started rather than a second pull request.

## Why run it on Rush?

A checkout extension is a small amount of code wrapped in rules: which `api_version`, which target renders where, which keys the CLI owns, which capabilities trigger review, how big the bundle may be, and how the app's own TypeScript and ESLint configuration must change so two JSX runtimes coexist in one workspace. The agent reads the app's files and Shopify's reference, writes the extension against both, and runs the same typecheck, lint and build the CI runs in its own sandbox, with the output kept in the run's record, so the pull request arrives already green on everything a sandbox can check and honest about the two commands it cannot run.

The template's conventions carry the change: the `extensions/*` workspace means no new install step, the existing `shopify` global in ESLint means the extension lints as the template intended, and the CI matrix means the extension is checked on both Node versions and all three package managers. Several apps from the same template get several pull requests, each reading its own `api_version` and configuration.

## Frequently asked questions

### Why not run shopify app generate extension?

Because the CLI signs in to a Partner account and links the app before it writes files, and the sandbox has no such account. The agent writes the same files the reference describes by hand, and leaves `uid`, which the reference says the CLI generates, for the reader's first `shopify app dev` or `shopify app deploy` to fill in.

### Why Preact and web components rather than React?

Because that is what Shopify's current checkout UI extension reference shows: `@shopify/ui-extensions/preact` with `render` from `preact` and Polaris components such as `s-banner` and `s-text`, built on remote-dom. The app itself stays on React 18; the extension's own `tsconfig.json` with `jsxImportSource` set to `preact` keeps the two from sharing JSX settings.

### Where does the block appear in checkout?

`purchase.checkout.block.render` is a block target, so the merchant places it in the checkout editor after the extension is deployed; it has no fixed position of its own. The reference also lists `purchase.thank-you.block.render` for the thank-you page, and the pull request shows how a second targeting entry with its own module adds that.

### Does it need new access scopes or capabilities?

No. A block that renders text makes no API or network calls, so `[extensions.capabilities]` stays out and `scopes` in `shopify.app.toml` is unchanged. An extension that fetches from your server would add `network_access`, which the reference says you must request, and the pull request describes that step.

### What is the 64 KB limit?

The reference says a checkout UI extension's compiled bundle cannot exceed 64 KB. The agent bundles the module with esbuild and reports the size so the reviewer knows the margin before the first `shopify app deploy`, which is where Shopify enforces it.

## More Shopify App jobs

- [Add the Mandatory Compliance Webhooks to a Shopify App](https://getrush.ai/run/add-compliance-webhooks/shopify-app/)
- [Add a Discount Function to a Shopify App](https://getrush.ai/run/add-discount-function/shopify-app/)
- [Add Lint, Type Check and Build Steps to CI for a Shopify App](https://getrush.ai/run/add-lint-to-ci/shopify-app/)

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

- [Generate CLI Reference Docs for a Typer App](https://getrush.ai/run/add-cli-reference-docs/typer/)
- [Put CloudFront With HTTPS in Front of an S3 Site in a Pulumi Program](https://getrush.ai/run/add-cloudfront-cdn/pulumi/)
- [Add CloudWatch Alarms to an AWS CDK Stack](https://getrush.ai/run/add-cloudwatch-alarms/aws-cdk/)

## 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/)
