Skip to content

ericrisco/rsc-harness / skills/shopify

shopify

Verified

Use when building or customizing a Shopify store across its three code surfaces — themes (Liquid, Online Store 2.0 sections, blocks and JSON templates), apps (Remix with the versioned GraphQL Admin API and its query-cost model), and checkout (UI extensions, Functions, Web Pixels), plus the CLI flow and checkout-extensibility migration. NOT WooCommerce or PHP stores (that is `wordpress`), NOT the React layer of a headless storefront (that is `nextjs`), NOT non-Shopify payment integrations (that is `stripe`).

FileKindSize
SKILL.mdskill md12.4 KB
evals/README.mdmarkdown1.0 KB
evals/cases.yamlconfig2.8 KB
references/apps-graphql.mdmarkdown3.5 KB
references/checkout-extensibility.mdmarkdown3.8 KB
references/liquid-themes.mdmarkdown3.8 KB
scripts/verify.shexecutablescript5.0 KB

references/apps-graphql.md

View on GitHub
# Shopify apps & the GraphQL Admin API — deep dive

Companion to the App surface section of `../SKILL.md`. The template is `@shopify/shopify-app-remix`.

## Template wiring

```js
// app/shopify.server.js
import { shopifyApp, ApiVersion } from "@shopify/shopify-app-remix/server";
import { PrismaSessionStorage } from "@shopify/shopify-app-session-storage-prisma";

const shopify = shopifyApp({
  apiKey: process.env.SHOPIFY_API_KEY,
  apiSecretKey: process.env.SHOPIFY_API_SECRET,   // env, never in shopify.app.toml
  apiVersion: ApiVersion.April26,                  // pin; bump quarterly
  scopes: process.env.SCOPES?.split(","),
  sessionStorage: new PrismaSessionStorage(prisma),
  webhooks: { ORDERS_CREATE: { deliveryMethod: "http", callbackUrl: "/webhooks" } },
  future: { unstable_newEmbeddedAuthStrategy: true },
});
export const authenticate = shopify.authenticate;
```

OAuth, token exchange, and session storage are handled by the template — store sessions in a real
DB (Prisma/SQL) in production, never in memory.

## Queries & mutations

```js
export async function loader({ request }) {
  const { admin } = await authenticate.admin(request);
  const res = await admin.graphql(
    `#graphql
     query Products($n: Int!) {
       products(first: $n) { nodes { id title totalInventory } }
     }`,
    { variables: { n: 20 } },
  );
  const { data, extensions } = await res.json();
  return { products: data.products.nodes, cost: extensions.cost };
}
```

Mutations follow the same shape and always select `userErrors { field message }` — Shopify returns
validation failures there, not as thrown errors:

```graphql
mutation UpdatePrice($input: ProductVariantsBulkInput!, $productId: ID!) {
  productVariantsBulkUpdate(productId: $productId, variants: [$input]) {
    productVariants { id price }
    userErrors { field message }
  }
}
```

## Query-cost, throttling & bulk operations

Read `extensions.cost.throttleStatus` after every call. Over-budget = HTTP 200 + a
`MAX_COST_EXCEEDED` entry in `errors`. Back off using `restoreRate` (points/sec). For large
exports use bulk operations instead of `first:`/`after:` loops:

```graphql
mutation {
  bulkOperationRunQuery(query: "{ products { edges { node { id title } } } }") {
    bulkOperation { id status }
    userErrors { field message }
  }
}
```

Poll `currentBulkOperation` until `status: COMPLETED`, then stream the JSONL from its `url`.

## Webhooks (HMAC)

```js
// app/routes/webhooks.jsx
export async function action({ request }) {
  const { topic, shop, payload } = await authenticate.webhook(request); // verifies HMAC
  // ... handle topic; return 200 fast, offload heavy work
  return new Response();
}
```

Never parse `request.body` directly — an unverified payload is untrusted input. Reconcile periodically;
webhooks can be missed.

## App Bridge & Polaris

Embedded UI runs inside the Shopify admin iframe. App Bridge handles session-token auth, navigation,
and toasts; Polaris React gives admin-consistent components. Keep app UI in Polaris so it matches the
admin chrome — do not hand-roll admin-looking CSS.

## App extensions & deploy

Extensions live under `extensions/` (theme app extension, admin/customer-account UI extensions,
Functions, Flow). Ship them with versioned releases:

```bash
shopify app deploy   # creates an app version bundling code + extensions; `app config push` is removed
```

Each `shopify app deploy` is an immutable, rollback-able version. Pin and bump `apiVersion`
quarterly across both the app client and extension configs.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall