mcpField
S
saleor-storefront

saleor-storefront

github.com/saleorDevelopment22.3k installsUpdated 12w ago
Repository

About saleor-storefront

saleor-storefront is a framework-agnostic guide for developers building stores on Saleor. It covers the GraphQL API, product variants, checkout, and channel-specific stock behavior.

Key features

  1. 01Saleor GraphQL API data model and permissions
  2. 02Product and variant query patterns
  3. 03Checkout lifecycle and payment debugging
  4. 04Channel stock and purchasability rules
  5. 05Rule files with code examples

Use cases

  1. 01Query products, categories, or collections
  2. 02Build product pages with variant selection
  3. 03Implement checkout and payment flows
  4. 04Investigate unpurchasable products or permission errors

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/saleor/agent-skills --skill saleor-storefront

After installing, type/saleor-storefrontin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

AGENTS.md
README.md
references/
saleor-key-directories.md
rules/
api-data-model.md
api-graphql-patterns.md
api-investigation.md
api-permissions.md
channels-purchasability.md
checkout-lifecycle.md
products-variants.md

Details

From the project README

Saleor Storefront

Universal guide for building storefronts on the Saleor e-commerce platform. Covers the Saleor GraphQL API data model, permission system, checkout lifecycle, channel architecture, and product/variant patterns. Framework-agnostic — these rules apply whether you're using Next.js, Remix, Nuxt, or a custom setup.

When to Apply

Reference these guidelines when:

  • Querying Saleor's GraphQL API for products, categories, or collections
  • Building product detail pages with variant selection
  • Implementing checkout and payment flows
  • Working with multi-channel and multi-currency setups
  • Debugging "product not purchasable" or permission errors
  • Working with Saleor 3.23+ stock availability modes (useLegacyShippingZoneStockAvailability)
  • Investigating Saleor API behavior via source code

Rule Categories

PriorityCategoryImpactPrefix
1APICRITICALapi-
2ProductsHIGHproducts-
3CheckoutHIGHcheckout-
4ChannelsMEDIUMchannels-

Quick Reference

1. API (CRITICAL)
  • api-data-model — Nullable fields, pricing structure, automatic storefront filtering
  • api-permissions — Token types, permission errors, two-tier query pattern
  • api-graphql-patterns — Channel-scoped queries, variant attributes, filtering, codegen
  • api-investigation — How to investigate Saleor API behavior via types and source
2. Products (HIGH)
  • products-variants — Variant model, selection vs non-selection attributes, pricing, UX patterns
3. Checkout (HIGH)
  • checkout-lifecycle — Session lifecycle, common errors, debugging payment issues
4. Channels (MEDIUM)
  • channels-purchasability — Stock availability modes (legacy vs direct, 3.23+), purchasability vs shippability, fulfillment triangle, mode-aware checklists, channel-scoped queries, stock webhooks

How to Use

Read individual rule files for detailed explanations and code examples:

rules/api-data-model.md
rules/products-variants.md

Each rule file contains:

  • Brief explanation of why it matters
  • Code examples (correct and incorrect patterns)
  • Anti-patterns to avoid

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

Comments

Markdown supported