# Add an App Proxy to a Shopify App

Yes. An agent adds an app proxy to your React Router Shopify app: the TOML block, a signed route under /apps with JSON and Liquid answers, the CI checks, and a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-app-proxy/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 and routing before it adds a proxied route, because an app proxy is two things that must agree: a block in `shopify.app.toml` that tells Shopify where to forward storefront requests, and a route on the app that validates the signature on what arrives. In an app laid out like Shopify/shopify-app-template-react-router, `shopify.app.toml` has `client_id` blank, `scopes = "write_products"`, a `[webhooks]` block on API version `2026-10` with `app/uninstalled` and `app/scopes_update` subscriptions, an `[events]` subscription for product price changes, and no `[app_proxy]` block. `app/routes.ts` uses `flatRoutes()` from `@react-router/fs-routes`, so a file's name is its path; `app/routes/webhooks.products.update.tsx` and the two `webhooks.app.*` files show the pattern for a public endpoint: an `action` that calls `authenticate.webhook(request)` and answers `200`. `app/shopify.server.ts` builds `shopifyApp` with `PrismaSessionStorage`, `distribution: AppDistribution.AppStore` and exports `authenticate`, whose `public.appProxy` is the function this job needs.

Then it adds the configuration: `[app_proxy]` with `prefix = "apps"`, `subpath = "proxy"` and `url` set to the app's address plus `/apps/proxy`, so a storefront request to `/apps/proxy/<rest>` on the shop is forwarded to `<app url>/apps/proxy/<rest>`. The flat route file is `app/routes/apps.proxy.products.tsx`, answering `/apps/proxy/products`. Its `loader` calls `authenticate.public.appProxy(request)`, which checks the signature Shopify adds to proxied requests, and reads `session` and `admin` from the result; when the app is not installed on that shop those are `undefined`, and the route answers `404` rather than throwing.

The route does something the template's scope already allows: it reads `handle` from the query string, queries the Admin GraphQL API for the product with that handle through `admin.graphql`, and returns its title and price as JSON with `Cache-Control: no-store`. A second file, `app/routes/apps.proxy.card.tsx`, returns the same data through `liquid()` from the proxy context, so a theme section can embed it as HTML that Shopify renders with the shop's layout. Both are typed by the generated Admin API types that `.graphqlrc.ts` and `npm run graphql-codegen` produce, which the agent runs so `tsc` sees the query's shape.

Then it runs what `.github/workflows/ci.yml` runs: `npx tsc --noEmit`, `npm run lint`, `npx prisma generate && npx prisma validate` and `npm run build`, on Node 22 as `engines` requires. `shopify app dev` needs a Partner sign-in the sandbox does not have, so the agent instead writes a small script under `scripts/` that signs a query string the way Shopify documents for app proxies, sends it to the built server's route with `SHOPIFY_API_SECRET` set, and records that the signed request is answered with the JSON and a tampered one is refused by the library before the loader's query runs; the script and both answers go into the pull request, with the `shopify app deploy` step a person runs to push the new configuration.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add an app proxy to this Shopify app built on React Router. Read shopify.app.toml, app/shopify.server.ts, app/routes.ts, app/routes/app.tsx, app/routes/app._index.tsx, the three webhooks routes, app/db.server.ts, prisma/schema.prisma, .graphqlrc.ts, package.json, Dockerfile and .github/workflows/ci.yml first, and read the shopify-app-react-router documentation for authenticate.public.appProxy and the app_proxy block. Add an [app_proxy] block with prefix apps, subpath proxy and the app URL. Add app/routes/apps.proxy.products.tsx whose loader authenticates the proxied request, reads a product handle from the query string, fetches the product's title and price through the Admin GraphQL API with the existing write_products scope, and returns JSON with no-store caching, answering 404 when the app is not installed on the shop. Add app/routes/apps.proxy.card.tsx that returns the same data as a Liquid response. Run npm run graphql-codegen, npx tsc --noEmit, npm run lint, npx prisma generate, npx prisma validate and npm run build. Write a script that sends a correctly signed and a tampered request to the built server and record both answers. Open a pull request with the output and the steps a person runs to deploy the configuration.",
  "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 changes `shopify.app.toml` and adds `app/routes/apps.proxy.products.tsx`, `app/routes/apps.proxy.card.tsx` and the signature check script. Its description pastes the four CI commands' output, the two recorded answers from the signed and tampered requests, and the deployment steps: `shopify app deploy` to push the proxy block, then a request to `https://<shop>.myshopify.com/apps/proxy/products?handle=<handle>` on a development store.

`CI` runs on the pull request across its matrix of Node 22 and 24 and npm, yarn and pnpm, with the type check, lint, Prisma validation and build; the new routes are part of the build.

Before merging, a reviewer checks the `url` in the proxy block against the address the app is deployed at, since `shopify app dev` rewrites the app URL for tunnels and a committed tunnel address is a common mistake, decides whether the JSON route should rate-limit by shop, and confirms the Liquid route renders inside their theme once deployed.

## Run it on every storefront feature that needs app data

A team that builds several Shopify apps from this template starts one run per repository from its own server: one `POST /o/{org}/sessions` each, with that repository in `resources`, the subpath and the data the route should return in `input`, and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own `shopify.app.toml`, so an app that already has a proxy gets a new route under its existing subpath, and one with `read_products` only gets a query that stays within that scope.

A team that plans features in Linear runs the same prompt from an automation in the Project with a `linear` trigger on issues labelled `storefront`. The trigger adds the issue after the prompt, so an issue that names the theme section the proxy feeds, or the fields it needs, reaches the agent with that detail, and the pull request links back to it.

## Why run it on Rush?

An app proxy fails in ways you only see with a signed request in hand: a subpath that does not match the route file, a loader that trusts the query string before validating it, or a response cached by the shop's CDN. The agent reads the library's own documentation for `authenticate.public.appProxy`, builds the app, and sends real signed and tampered requests to the built server in its own sandbox, keeping both answers with the run.

The same type check, lint, Prisma validation and build that `ci.yml` runs happen before the pull request opens, and the generated Admin API types catch a wrong field name at compile time. For a team with several apps, each gets its own run and its own pull request, fitted to its own scopes and routes.

## Frequently asked questions

### Why does the storefront path differ from the route file name?

Shopify forwards `/apps/<subpath>/<rest>` on the shop to `<url>/<rest>`. With `url` ending in `/apps/proxy`, the forwarded path is `/apps/proxy/products`, which `flatRoutes()` maps to `app/routes/apps.proxy.products.tsx`. Keeping the two aligned is why the agent sets `url` from the app address plus the same prefix and subpath.

### Can the proxied route use the session?

Yes. `authenticate.public.appProxy` returns `session`, `admin` and `storefront` when the app is installed on the requesting shop, and `liquid` always. The route uses `admin.graphql` for the product query, which the existing `write_products` scope covers. If the app is not installed, those are `undefined` and the route answers `404`.

### Does it need the Storefront API?

Not for this route. The `storefront` context exists for queries that should run as the shop's storefront, which needs the matching unauthenticated scopes in `access_scopes`; the agent uses the Admin API because the scope is already granted. A reviewer who wants storefront semantics changes one call.

### How is the proxy deployed?

The `[app_proxy]` block is app configuration, pushed with `shopify app deploy` by a person signed in to the Partner account; the agent cannot run that from a sandbox and says so. After the deploy, a request to `/apps/proxy/products?handle=...` on a store that has the app installed returns the JSON.

### What stops a shop's CDN from caching the JSON?

The route sets `Cache-Control: no-store` on its response. Proxied responses pass through Shopify, so a cacheable header would let one shop's answer be served again; the Liquid route is rendered by Shopify per request from the `application/liquid` body the `liquid()` helper returns.

## More Shopify App jobs

- [Add a Checkout UI Extension to a Shopify App](https://getrush.ai/run/add-checkout-ui-extension/shopify-app/)
- [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/)

## More jobs like this: Hand off a long task

- [Convert an Argo CD App-of-Apps Chart Into an ApplicationSet](https://getrush.ai/run/add-applicationset/argo-cd/)
- [Add Argument Specs to an Ansible Role](https://getrush.ai/run/add-argument-specs/ansible/)
- [Run Molecule Tests for an Ansible Role on arm64 in CI](https://getrush.ai/run/add-arm64-ci/ansible/)

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