All jobs

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

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

The use case this job follows, with its automation and trigger: Hand off a long task.

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

More jobs like this: Hand off a long task

Keep reading