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`).

Shopify themes, apps & checkout

The single authoritative skill for building and customizing a Shopify store. The mental model: a Shopify store is a hosted platform you extend at well-defined seams — never a server you control. You render on the storefront with Liquid, you mutate data through the versioned GraphQL Admin API, and you customize checkout through sandboxed extensions. The platform owns hosting, the database, PCI scope, and the checkout DOM; you own only the seams. Three surfaces, three toolchains — name the surface before you write a line of code.

Pinned stack (verify against shopify.dev before pinning in a repo):

  • Shopify CLI 4.x — auto-upgrades via the package manager it was installed with; skips CI, project-local installs, and major bumps. shopify app config push is removed; use shopify app deploy.
  • GraphQL Admin API 2026-04 — latest stable; supported window 2026-04 / 2026-01 / 2025-10 / 2025-07†. Each version is supported ~12 months. Pin apiVersion and bump quarterly. † 2025-07 is at the edge of its window — accessible only until 2026-07-16; treat it as sunsetting and do not pin it in new work. Re-check the live list at shopify.dev/docs/api/usage/versioning.
  • Remix app template (@shopify/shopify-app-remix, App Bridge, Polaris React). GraphQL > REST — REST Admin API is legacy; Shopify steers all new app work to GraphQL.
  • Dawn — Shopify's source-available reference theme; OS 2.0 architecture is the baseline.

Pick your surface first

Most Shopify mistakes are surface confusion — answering with a headless React build when the ask was a Liquid section, or editing checkout.liquid when the seam is now an extension. Branch here:

SurfaceYou're working on…Tool & entryReference
Theme.liquid files, {% schema %}, JSON templates, storefront rendering, merchant-editable contentshopify theme dev on a Dawn-based themereferences/liquid-themes.md
Appembedded admin UI, reading/writing store data, webhooks, automationshopify app dev on the Remix template + Admin GraphQLreferences/apps-graphql.md
Checkoutcheckout/thank-you/order-status UI or logic, discounts, shipping, trackingCheckout UI extensions / Functions / Web Pixelsreferences/checkout-extensibility.md

If the answer is "the React rendering layer of a headless storefront", that is ../nextjs/SKILL.md, not this skill — Shopify is only the data seam (Storefront API) there.

Theme surface — Online Store 2.0 architecture

OS 2.0 (GA 2021, sometimes marketed "3.0") is the architecture: JSON templates + sections- everywhere + theme blocks + @app blocks + dynamic sources. The file map:

layout/theme.liquid            # the HTML shell (one per theme)
templates/product.json         # JSON template: which sections render, in what order
sections/main-product.liquid   # a section: markup + {% schema %} of merchant settings
sections/*.liquid              # section groups (header/footer) live here too
blocks/*.liquid                # theme blocks (reusable, nestable) — OS 2.0
snippets/*.liquid              # partials rendered via {% render %}
config/settings_schema.json    # global theme settings

Rule: every section carries a {% schema %} with presets so merchants edit content in the theme editor without a deploy. The why: content belongs in section.settings and metafields, not in code — if a merchant has to ask you to change a headline, the section is built wrong.

<!-- Bad: copy hardcoded in Liquid; merchant can't touch it -->
<h2>Summer Sale — 20% off everything</h2>

<!-- Good: editable in the theme editor, with a preset so it appears in "Add section" -->
<h2>{{ section.settings.heading | escape }}</h2>
{% schema %}
{
  "name": "Promo banner",
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", "default": "Summer Sale" }
  ],
  "blocks": [{ "type": "@app" }],
  "presets": [{ "name": "Promo banner" }]
}
{% endschema %}

The { "type": "@app" } block lets merchant-installed apps drop content into your section. The Shopify Theme Store requires the main product and featured-product sections to support @app blocks. See references/liquid-themes.md for setting types, section groups, and dynamic sources.

Liquid rules

  • {% render %}, never {% include %}. render is scoped (the snippet only sees what you pass) and cacheable; include leaks the parent scope and is deprecated.

    {% comment %} Bad {% endcomment %}
    {% include 'price' %}
    {% comment %} Good — explicit, scoped, cacheable {% endcomment %}
    {% render 'price', product: product, variant: variant %}
    
  • Bound every collection loop with limit: and never nest unbounded loops — storefront render cost is real and slow pages cost conversions. {% for p in collection.products limit: 8 %}.

  • Pipe all dynamic output. | money for prices (raw values render cents/locale wrong), | escape for any user/merchant string (XSS), | json when emitting data into a <script>.

  • Push branchy logic into metafields/metaobjects, not conditional chains. A case/if ladder over product types is data pretending to be code — bind a metafield and let Liquid do a lookup.

CLI workflow

Theme work (hot-reloads against a dev theme; never edits live unprompted):

shopify theme dev                      # local preview + hot reload
shopify theme pull                     # sync live/named theme down
shopify theme push --only templates/*  # push a subset; --ignore excludes paths
shopify theme check                    # Theme Check linter — wire into CI

Multi-environment lives in shopify.theme.toml; --environment is repeatable (shopify theme push --environment staging --environment prod).

App work:

shopify app dev      # tunnel + env + reload; provisions admin.graphql()
shopify app deploy   # release app + extensions  (NOT `app config push` — removed in 4.x)

CLI 4.x auto-upgrades via your package manager but skips CI and project-local installs — pin the version in CI so a silent bump never changes a release.

App surface — Remix + GraphQL Admin API

Apps are the Remix template. The shape:

app/shopify.server.js     # shopifyApp({ apiVersion, sessionStorage, webhooks, ... })
app/routes/app.*.jsx      # embedded admin pages (App Bridge + Polaris)
shopify.app.toml          # app config, scopes, webhook subscriptions
extensions/*              # app extensions (theme app ext, UI ext, Functions, Flow)
  • Pin apiVersion in shopify.server and bump it quarterly — an unpinned client silently follows Shopify's default and can break on a version rollover.

  • Use the GraphQL Admin API, not REST. REST is legacy; new fields ship to GraphQL only.

    // Bad — legacy REST Admin endpoint
    await fetch(`https://${shop}/admin/api/2026-04/orders.json`);
    
    // Good — authenticated GraphQL through the template
    const { admin } = await authenticate.admin(request);
    const res = await admin.graphql(
      `#graphql
       query Orders { orders(first: 10) { nodes { id name } } }`
    );
    
  • Verify webhook HMAC before trusting any payload — authenticate.webhook(request) in the template does this; never parse a raw webhook body without it.

See references/apps-graphql.md for OAuth/session storage, mutations, App Bridge, and extensions.

GraphQL query-cost model

Admin GraphQL meters by calculated query cost (points), not request count. Every response carries extensions.cost:

{ "extensions": { "cost": {
  "requestedQueryCost": 92, "actualQueryCost": 30,
  "throttleStatus": { "maximumAvailable": 2000, "currentlyAvailable": 1970, "restoreRate": 100 }
}}}
  • Over-budget returns HTTP 200 with a MAX_COST_EXCEEDED error — you must handle it in code; it is not an HTTP-level failure your client will throw on.
  • Read throttleStatus and back off on restoreRate (points restored per second) rather than blindly retrying.
  • Large reads use bulk operations, not paginated loops. A 10k-product export through first: pagination will throttle; bulkOperationRunQuery runs async and returns a JSONL file.

Checkout surface — the post-checkout.liquid model

checkout.liquid and additional scripts are deprecated and being removed. Dated facts:

  • 2024-08-13 — Information/Shipping/Payment steps lost checkout.liquid support.
  • 2025-08-28 — Plus self-migrate deadline for Thank-you & Order-status customizations (additional scripts, script tags, checkout.liquid). This was the deadline to act, not the auto-upgrade date.
  • 2026-01 — automatic upgrades of Thank-you & Order-status pages begin (30-day email notice); any remaining additional-scripts / script-tag / checkout.liquid customizations stop running.
  • 2026-04-15 — legacy Shopify Scripts can no longer be edited or published (existing scripts still run).
  • 2026-06-30 — legacy Shopify Scripts (Script Editor discount/shipping/payment scripts) stop executing entirely.

Migrate by surface — match the old mechanism to its new seam:

Old (deprecated)New seamNotes
checkout.liquid UI tweaksCheckout UI extensionssandboxed React/JS targets, not DOM access
Script Editor / additional-script discounts, shipping, payment logicFunctions (Rust or JS → Wasm)deterministic, run server-side
<script> tracking / analytics in checkoutWeb Pixels + server-side eventssandboxed; no arbitrary DOM scripts
custom checkout colors/fonts/CSSCheckout Branding APIGraphQL, not CSS injection

Several checkout surfaces (full checkout UI customization, some Functions) are Shopify Plus-only. The full migration map, extension targets, and Functions structure are in references/checkout-extensibility.md.

App extensions catalog

  • Theme app extension — your app injects an @app block / blocks into themes (no theme edit).
  • Admin UI extension — surfaces inside admin pages (product, order) without leaving Shopify.
  • Customer-account UI extension — extends the new customer accounts.
  • Functions — discount / shipping / payment / cart logic as Wasm; the checkout.liquid logic seam.
  • Flow — triggers/actions for Shopify Flow automation, exposed by your app.

Anti-patterns

Anti-patternWhy it's wrongDo instead
{% include %} in new codedeprecated, leaks parent scope, not cacheable{% render %} with explicit args
Raw {{ price }} / {{ user_input }}wrong locale/cents; XSS| money, | escape, | json
Editing checkout.liquid / additional scriptsdeprecated; auto-upgraded away starting 2026-01UI extensions / Functions / Web Pixels
REST Admin calls in a new applegacy; new fields are GraphQL-onlyadmin.graphql()
Unpinned or stale apiVersionbreaks on Shopify's version rolloverpin a supported version, bump quarterly
Paginated first: loop for big readsthrottles on query costbulkOperationRunQuery
Ignoring extensions.cost.throttleStatussilent MAX_COST_EXCEEDED at HTTP 200read cost, back off on restoreRate
Hardcoded copy in Liquidmerchant can't edit without a deploysection.settings / metafields
Section with no presetswon't appear in "Add section" in the editoradd a presets entry to {% schema %}
Secrets committed in shopify.app.tomlleaks API credentialsenv vars; keep secrets out of TOML
No Theme Check in CIregressions ship to the storefrontshopify theme check in the pipeline
Answering with a headless React buildwrong surface for a Liquid/theme askconfirm the surface; route React to ../nextjs/SKILL.md

Run scripts/verify.sh <theme-or-app-dir> for an advisory scan of these foot-guns.

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: 319kUpdated 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: 196kUpdated 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: 196kUpdated 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: 196kUpdated Claude CodeCodexVerifiedInstall