saleor/saleor-paper-storefront

Saleor Paper Storefront

Project-specific guide for the Saleor Paper storefront — a Next.js 16 e-commerce application with TypeScript, Tailwind CSS, and the Saleor GraphQL API. Contains 11 rules across 6 categories covering caching, PDP architecture, checkout components, UI patterns, and SEO.

Prerequisite: This skill depends on saleor-storefront for universal Saleor API knowledge (data model, permissions, checkout lifecycle, channels). Install it alongside this skill.

When to Apply

Reference these guidelines when:

• Working on product detail pages (PDP), variant selection, or filtering
• Modifying checkout flow or payment integration
• Editing GraphQL queries or regenerating types
• Debugging caching, stale content, or revalidation
• Creating UI components with design tokens
• Adding SEO metadata, JSON-LD, or OG images
• Writing tests or investigating Saleor API behavior

Rule Categories by Priority

| Priority | Category | Impact | Prefix | | -------- | ------------- | -------- | ----------- | | 1 | Data Layer | CRITICAL | data- | | 2 | Product Pages | HIGH | product- | | 3 | Checkout Flow | HIGH | checkout- | | 4 | UI & Channels | MEDIUM | ui- | | 5 | SEO | MEDIUM | seo- | | 6 | Development | MEDIUM | dev- |

Quick Reference

1. Data Layer (CRITICAL)

• data-caching - Cache Components (PPR), cache tags, revalidation, price flow
• data-graphql - Two codegen setups, permission patterns, nullable fields

2. Product Pages (HIGH)

• product-pdp - PDP architecture, gallery, data flow, add-to-cart, ErrorBoundary
• product-variants - Variant selection state machine, option states, discount badges
• product-filtering - Server vs client filtering, category slug resolution

3. Checkout Flow (HIGH)

• checkout-management - Checkout lifecycle, cookie storage, payment debugging
• checkout-components - Reusable checkout UI (SignInForm, AddressSelector, PaymentMethodSelector)

4. UI & Channels (MEDIUM)

• ui-components - Design tokens, shadcn/ui primitives, component locations
• ui-channels - Multi-channel URLs, fulfillment model, purchasability debugging, channel selector

5. SEO (MEDIUM)

• seo-metadata - JSON-LD structured data, metadata helpers, OG image generation

6. Development (MEDIUM)

• dev-investigation - Saleor API source code investigation methodology

How to Use

Read individual rule files for detailed explanations and code examples:

rules/data-caching.md
rules/product-variants.md

Each rule file contains:

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

Full Compiled Document

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