Home › Shopify › Shopify app AGENTS.md

Shopify app AGENTS.md

AGENTS.md for Shopify apps built with Shopify CLI and the React Router template: auth, GraphQL Admin API, and webhooks.

AGENTS.mdShopify

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# AGENTS.md: Shopify app

## Commands
- `shopify app dev` (tunnels to a dev store) · `shopify app deploy` (only when asked) · `npm run typecheck` · `npm test`
- Config: `shopify.app.toml` (scopes, webhooks, app proxy). Run `shopify app config link` once per environment.

## Rules
- Every loader/action in admin routes starts with `const { admin, session } = await authenticate.admin(request);`. Webhook routes use `authenticate.webhook(request)`; app proxy routes use `authenticate.public.appProxy(request)`.
- Use the GraphQL Admin API (`admin.graphql(query, { variables })`) with a pinned API version. REST Admin API is legacy; don't add new REST calls.
- Request only the access scopes you need; changing scopes requires merchants to re-approve, so call it out.
- Handle GraphQL `userErrors` in mutation responses, not just HTTP errors. Respect rate limits (query cost) and paginate with cursors.
- Webhooks are declared in `shopify.app.toml`; handlers verify via the library, respond fast, and queue heavy work. Mandatory privacy webhooks (customer data request/redact, shop redact) must be implemented.
- Store shop data keyed by `session.shop`; never trust a shop domain from query params without authentication.
- Embedded admin UI uses Polaris (web components or React, matching the template) and App Bridge for navigation, toasts, and modals.
- Extensions (checkout UI, theme app extensions, functions) live in `extensions/` and are generated with `shopify app generate extension`.

## Don't
Don't deploy, change billing config, or hit a production store from the agent.