shopify-graphql-reference

name	shopify-graphql-reference
description	Reference Vercel Shop GraphQL patterns, fragments, cache conventions, and transforms for any Shopify GraphQL work in the template.

Shopify GraphQL Reference

Description

Use this skill as the reference source for Shopify GraphQL work in the template. It keeps queries, mutations, schema validation, fragment changes, locale handling, caching rules, and transforms aligned with the live Shopify schema and established storefront patterns.

When to Use This Skill

• When the user is doing any Shopify GraphQL work
• When the user wants a new query or mutation
• When an existing operation needs more fields
• When a GraphQL response shape must be mapped into domain types
• When debugging Shopify GraphQL errors, missing fields, or stale cache behavior
• When invoked via /vercel-shop:shopify-graphql-reference

Read These First

• Read references/REFERENCE.md for the detailed technical reference: operation structure, fragment usage, locale context, cache rules, and common modifications.
• Use shopify-ai-toolkit or the vercel-shop:fetch-shopify-schema skill when you need authoritative schema facts for the Storefront or Customer Account APIs.

Workflow

1. Verify the schema first

• Verify fields, types, enum values, and arguments with shopify-ai-toolkit before writing or changing GraphQL.
• Never guess Shopify field names, enum values, or argument shapes.
• Do not add repo-local schema snapshots or .claude folders to the template.

2. Choose the right operation file

• Add the operation to the closest existing file in lib/shopify/operations/ when the concern already exists there.
• Create a new operation file only when the concern is genuinely new.
• Always call shopifyFetch with a stable operation name, a GraphQL document string, and variables passed as an object.

3. Reuse fragments deliberately

• Use PRODUCT_FRAGMENT for PDP-level product data.
• Use PRODUCT_CARD_FRAGMENT for listings, search results, and other lighter product cards.
• Extend lib/shopify/fragments.ts when several operations need the same fields.

4. Handle locale context correctly

• Locale-sensitive reads should use @inContext(...).
• Use helpers from lib/i18n to derive country and language codes instead of hardcoding them.
• Keep locale flowing through the operation API so pages and components stay consistent.

5. Apply cache rules to reads

• Stable, low-cardinality reads should include "use cache", cacheLife(...), and cacheTag(...).
• High-cardinality reads that depend on search, filters, sort, or cursors should use "use cache: remote" instead.
• Pick existing cache tags when the data belongs to an established surface.
• Mutations should not use read-cache directives.
• Every cart mutation must call invalidateCartCache() after the write succeeds.

6. Transform before returning

• Convert Shopify response shapes to domain types before they cross into components.
• Keep raw Shopify types inside lib/shopify/**.
• Update the matching transform and domain type when you add new fields.

7. Verify the change

• Re-check the query against the live schema with shopify-ai-toolkit.
• Check that the operation name passed to shopifyFetch matches the GraphQL operation name.
• Run the smallest relevant validation command for the touched area.

Guardrails

• Always verify Shopify GraphQL fields against the live schema via shopify-ai-toolkit.
• Never interpolate dynamic values directly into the query string when GraphQL variables can carry them.
• Use PRODUCT_CARD_FRAGMENT for listings and PRODUCT_FRAGMENT for PDP work unless there is a clear reason not to.
• Return domain types from operations, not raw Shopify response types.
• Cart mutations must call invalidateCartCache().

Common changes

Add a field to an existing product query

1. Confirm the field exists in the live Storefront API schema with shopify-ai-toolkit.
2. Add it to the appropriate fragment in lib/shopify/fragments.ts.
3. Update the Shopify response type and transform in lib/shopify/transforms/product.ts.
4. Add the mapped field to lib/types.ts if components need it.

Add a new read operation

1. Define the GraphQL query using existing fragments where possible.
2. Add "use cache", cacheLife(...), and cacheTag(...); use "use cache: remote" for search/filter/sort/cursor reads.
3. Call shopifyFetch with the query and variables object.
4. Transform the response before returning it.

Add a mutation

1. Define the mutation and typed response shape.
2. Call shopifyFetch without read-cache directives.
3. If the mutation touches cart state, call invalidateCartCache().
4. Return transformed domain data.

Debug GraphQL errors

• Set DEBUG_SHOPIFY=true in .env.local to log Shopify requests with timing and variables.
• Compare every field and argument against the live schema with shopify-ai-toolkit.
• Check whether the wrong fragment is being reused for the surface.

See also

• the vercel-shop:fetch-shopify-schema skill
• references/REFERENCE.md
• vercel-shop:enable-shopify-auth
• vercel-shop:enable-shopify-cms