SuperAPI AI Directory
Partner中文AI newsFavorites
Skillssaleor-paper-storefront

saleor-paper-storefront

Frontend & websites

View repository

Updated 10-16 04:12

About this skill

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 32 rules across 8 categories covering architecture, Vercel cost discipline, caching, storefront content, PDP architecture, checkout v2, design & composition (token system, design quality, section catalog, page composition, design-from-image, verification), components, UI patterns, locale routing, i18n, 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

Unfamiliar with the codebase? Read paper-architecture first.

Reference these guidelines when:

  • Working on product detail pages (PDP), variant selection, high-cardinality catalogs, or filtering
  • Modifying checkout flow or payment integration
  • Editing GraphQL queries or regenerating types
  • Debugging caching, stale content, or revalidation
  • Optimizing Vercel cost, invalidation scope, or scaling traffic
  • Editing merchandising copy, homepage content, or CONTENT_PROVIDER=saleor
  • Seeding or extending Saleor Models for storefront content (Configurator)
  • Migrating authenticated routes (account, session cookies) under Cache Components / PPR
  • Upgrading a forked shop — see Migrations below
  • Molding PDP or homepage layout/design, or designing from a prompt or reference image
  • Creating UI components with design tokens
  • Adding locale/channel routing, market picker, next-intl messages, or i18n URL structure
  • Adding SEO metadata, JSON-LD, or OG images
  • Writing tests or investigating Saleor API behavior
  • Testing on a real phone via ngrok or LAN while pnpm dev is running

Rule Categories by Priority

Priority Category Impact Prefix
0 Architecture CRITICAL paper-
1 Data Layer CRITICAL data-
2 Product Pages HIGH product-
3 Checkout Flow HIGH checkout-
4 Design & Composition HIGH ui- / design- / page-
5 UI & Channels MEDIUM ui-
6 SEO MEDIUM seo-
7 Development MEDIUM dev-

Quick Reference

0. Architecture (CRITICAL)

  • paper-architecture - Start here — canonical Next.js stance, pillars, non-goals, where to read next
  • paper-vercel-cost - Vercel billing model, cost invariants (no global invalidation for private state, sharded listing tags, sampling, image guards), scaling playbook

1. Data Layer (CRITICAL)

  • data-caching - Cache Components (PPR), three-layer page model, cache manifest, webhooks
  • data-auth-routes - BFF auth, resolveSessionUser, account PPR, header chrome refresh
  • data-redirect-security - Redirect URL allowlists for auth emails, checkout/account flows, and Host/Origin spoofing prevention
  • data-graphql - Two codegen setups (checkout types via server actions, not urql runtime)
  • data-storefront-content - Provider-agnostic copy layer, merge semantics, cache tags, wiring
  • data-storefront-content-saleor - Saleor Models, slug stack, channel overrides, Configurator
  • data-storefront-content-attributes - Attribute inputTypes, catalog references, scalar roadmap

2. Product Pages (HIGH)

  • product-pdp - ProductShell + dynamic islands, gallery, LCP preload, add-to-cart
  • product-variants - Variant selection state machine, control ladder, selection-index, partial selection
  • product-high-cardinality - Caps, buy-box strategies, ?variant=/?sku=, PLP facets alias OR
  • references/variant-selector-ui.md - Border states, pill/circle sizing, renderer routing (read before editing renderers)
  • product-filtering - Server-side categories/price/sort + PLP_FACETS / ProductWhereInput

3. Checkout Flow (HIGH)

  • paper-surfaces - Two surfaces, routes, v2 data flow, session handoff (read paper-architecture first)
  • checkout-design-principles - Evidence-based UX principles (guest-first, mobile, pricing, express pay)
  • checkout-management - Lifecycle, RSC sync, shallow steps, payment transition UX (+ cheat sheet)
  • checkout-payment-gateways - Payment app registry, submit modes, Stripe Express Checkout wallets, adding a new gateway
  • checkout-components - Reusable checkout UI (SignInForm, AddressSelector, billing, integrated payment UI)

4. Design & Composition (HIGH)

  • ui-design-system - Start here for design — token vocabulary (color, fluid type, width, rhythm, radius, elevation, motion) + cva variant matrix
  • design-quality-rubric - World-class bar: hierarchy, whitespace, full-width-allowed clause, mobile non-negotiables, self-check
  • ui-sections - Marketing-block catalog (HeroBanner, FeaturedCollection, ImageWithText, …), selection guide, section authoring pattern
  • page-composition - Mold PDP/homepage within the PPR rails (static shell vs dynamic islands)
  • design-from-image - Prompt/image → brief → tokens → blocks → compose → verify
  • design-verification - Gates: hard-fail token lint, advisory PPR/LCP/client-JS, a11y pass

5. UI & Channels (MEDIUM)

  • references/code-conventions.md - kebab-case files, PascalCase exports, @/ imports
  • ui-components - Design tokens, shadcn/ui primitives, component locations
  • ui-images - Saleor thumbnails vs Vercel's optimizer, sizes discipline, image cost budget
  • ui-channels - Channel allowlist, fulfillment triangle, multi-currency, channel selector
  • ui-locale-routing - /{locale}/{channel}/ routing, middleware redirects, path helpers
  • ui-i18n - next-intl namespaces, server/client patterns, ADR 0002 boundary

6. SEO (MEDIUM)

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

7. Development (MEDIUM)

  • dev-local - ngrok/LAN mobile testing, allowedDevOrigins, dev vs production QA
  • dev-investigation - Saleor API source code investigation methodology
  • third-party-embeds - External widget scripts (reviews, Yotpo) via next/script, env keys, client leaf components

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

Migrations (fork upgrades)

Chronological upgrade prompts for forks behind upstream Paper. Not for greenfield work — use rules/ for current patterns.

Task Location
Apply pending upgrades migrations/SKILL.md
Migration registry migrations/manifest.json
Fork baseline paper-version.json (repo root)

Trigger phrases: "upgrade Paper", "apply Paper migrations", "catch up with upstream caching", "checkout v2", "paper-version".

Notable migration: 2026-06-checkout-v2 — subsystem replacement (adopt-then-replay, not incremental port); RSC + server actions; requires 2026-06-account-ppr-auth. See migrations/references/checkout-v2-overview.md.

Full Compiled Document (humans / offline only)

AGENTS.md concatenates every rule into one ~75k-token file for humans reading offline and for single-file skill export. Agents must not load it — read the one rules/<task>.md whose frontmatter description matches your task instead. Regenerate the compiled doc from rules/ with node scripts/compile-agents.mjs.