All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

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

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

Keep reading