storefront

.%20The%20channel%20slug%20can%20be%20found%20in%20Saleor%20Dashboard%20under%20Configuration%20%3E%20Channels%20(e.g.%20default-channel).%20For%20multi-channel%2C%20set%20STOREFRONT_CHANNELS%20(e.g.%20us%2Cuk)%20and%20optionally%20SALEOR_APP_TOKEN%20for%20the%20footer%20selector.%20For%20locales%2C%20set%20NEXT_PUBLIC_DEFAULT_LOCALE%20(e.g.%20en)%20and%20NEXT_PUBLIC_STOREFRONT_LOCALES%20(e.g.%20en%2Cpl%2Cde%2Cfr%2Cfi%2Cnb).&envLink=https%3A%2F%2Fgithub.com%2Fsaleor%2Fstorefront%23environment-variables&project-name=my-saleor-storefront&repository-name=my-saleor-storefront&demo-title=Saleor%20Next.js%20Storefront&demo-description=Starter%20pack%20for%20building%20performant%20e-commerce%20experiences%20with%20Saleor.&demo-url=https%3A%2F%2Fstorefront.saleor.io%2F&demo-image=https%3A%2F%2Fstorefront-d5h86wzey-saleorcommerce.vercel.app%2Fopengraph-image.png%3F4db0ee8cf66e90af>)

[!TIP] Questions or issues? Check our Discord for help.

---

Why Paper?

Ship faster, customize everything. Paper is a new release—expect some rough edges—but every component is built with real-world e-commerce in mind. This is a foundation you can actually build on.

Open Checkout (v2)

The checkout is where most storefronts fall apart or fall short. Paper's doesn't — and checkout v2 aligns it with the rest of the stack: App Router, Server Components, server actions, and the same BFF session as the storefront (no client-side urql or browser Saleor tokens).

Storefront cart                    Checkout surface
─────────────                      ────────────────
src/lib/checkout.ts                src/app/(checkout)/checkout/
  cookie + mutations        →        CheckoutSessionLoader (RSC)
@paper/session-bridge                  CheckoutApp → steps + payment
buildCheckoutPath()                  /order/{hmac} (guest confirmation)

• Server-first cart — RSC loads checkout + me on entry; client context is a cache of server truth (CheckoutDataProvider).
• URL-driven steps — ?step=contact|shipping|payment updates shallowly (no full page refetch per click); browser Back walks the funnel.
• Dedicated confirmation — /order/{hmac} after pay (URL frozen; status/tracking refresh from Saleor). /order/{saleorId} from email is redacted until we recognize you. Legacy /checkout/complete?order= redirects. See checkout-guest-order.md.
• Extensible payments — Registry (INTEGRATED_GATEWAYS) with Stripe + Dummy; add gateways via checkout-payment-gateways skill.
• Shared BFF auth — Sign-in via /api/auth/login; session resolved server-side (resolveSessionUser — guest / authenticated / unavailable).
• Multi-step, mobile-first — Focused forms, international address fields, composable step components.

Developer docs: start at skills/saleor-paper-storefront/rules/paper-surfaces.md, then checkout-management.md. Forks on the old urql checkout: migrations/atomic/2026-06-checkout-v2/.

International by Default

One codebase, many markets. Browse URLs are /{locale}/{channel}/… — e.g. /en/us/products/hoodie (English, US market, USD) and /pl/pl/products/bluza (Polish, Poland, PLN, with a translated catalog slug when set in Saleor) — with legacy /{channel}/… paths redirecting automatically. Each locale gets its own cached catalog payload, translated product copy from Saleor, per-channel pricing and currency, and hreflang/canonical metadata (including per-locale product/category handles).

• Region picker — header control switches locale and channel together (language + market + currency), remapping catalog URLs to each language’s canonical slug
• Three string systems — Saleor catalog translations, merchant-editable storefront content (CMS), and code-owned UI via next-intl (messages/{locale}.json)
• Seven built-in locales — en, pl, de, fr, fi, nb, ko (extend via LOCALE_DEFINITIONS in src/config/locale.ts)
• Optional translated URL slugs — Saleor Dashboard can set per-language handles for products, categories, collections, and pages; Paper resolves, redirects, links, and hreflang accordingly (ADR 0004)

Storefront channels are explicit. Saleor may have many channels (B2B, wholesale, internal regions); Paper only exposes the slugs you configure via STOREFRONT_CHANNELS. Disallowed channel URLs return 404. For a single-channel store, set NEXT_PUBLIC_DEFAULT_CHANNEL only—the footer channel selector is hidden automatically.

Developer docs: docs/international-storefront.md · ADRs 0001 / 0002 / 0004 · skills ui-locale-routing / ui-i18n

Product Pages Done Right

The hard parts are solved. Adapt the look, keep the logic.

• Partial Prerendering (PPR) — Product name, attributes, and SEO stay in a static cached shell; variant gallery and add-to-cart stream in via Suspense when searchParams change.
• Multi-attribute variant selection — Color + Size + Material? Handled. Complex variant matrices just work.
• Dynamic pricing — Sale prices, variant-specific pricing, channel pricing—all reactive.
• Image gallery — Next.js Image optimization, proper aspect ratios, keyboard navigation.

♿ Accessibility Built In

Not an afterthought. Focus management on step transitions, keyboard navigation everywhere, semantic HTML, proper ARIA labels. Everyone deserves to shop.

AI-Ready Codebase

Built for front-end developers and AI agents. The codebase includes:

• AGENTS.md — Architecture overview and quick reference for AI assistants
• skills/saleor-paper-storefront/ — 21 task-specific rules covering GraphQL, caching, i18n, variant selection, checkout v2, and more
• saleor/agent-skills — Universal Saleor API patterns; external skills via pnpm skills:bootstrap (skills-lock.json)
• Consistent patterns — Predictable structure that AI tools can navigate and modify confidently

Whether you're pair-programming with Cursor, Claude, or Copilot—the codebase is designed to help them help you.

⚡ Bleeding Edge Stack

• Next.js 16 with App Router and Server Components
• React 19 with the latest concurrent features
• TypeScript in strict mode—your IDE will thank you
• Tailwind CSS with design tokens (OKLCH colors, CSS variables)
• GraphQL Codegen for type-safe Saleor API calls

---

What's in the Box

Feature	Description
Checkout (v2)	RSC + server actions, shallow step URLs, payment registry (Stripe/Dummy), guest /order/{key}
Cart	Slide-over drawer with real-time updates, quantity editing
Product Pages	Multi-attribute variants, image gallery, sticky add-to-cart
Product Listings	Category & collection pages with PPR (cached hero + dynamic filters), pagination
International	/{locale}/{channel}/ routing, region picker, Saleor translations + optional translated URL slugs, next-intl UI, hreflang SEO
Storefront content	Merchant-editable copy layer (code or Saleor Models) — homepage, cart trust, checkout editorial
Navigation	Dynamic menus from Saleor, mobile hamburger, breadcrumbs
SEO	Per-locale metadata, JSON-LD, Open Graph images, hreflang with per-locale catalog handles
Caching	Cache Components (PPR), named cacheLife tiers, per-locale catalog cache, webhooks
Saleor Cloud Paper app	Saleor Cloud only — Dashboard extension for cache invalidation webhooks and Preview in storefront
Customer Profile	Account dashboard, address book, order history, password change, account deletion
Authentication	Login, register, password reset, guest checkout
API Resilience	Automatic retries, rate limiting, timeouts—handles flaky connections gracefully

---

Caching Architecture

Paper uses Cache Components (Next.js 16 — "use cache", cacheLife, cacheTag behind cacheComponents: true) for optimal performance: static shells load instantly while dynamic content streams in. Learn more in the directive docs or see skills/saleor-paper-storefront/rules/data-caching.md for project-specific patterns.

The display-cached, checkout-live model ensures fast browsing with accurate checkout:

…

How It Works

Component	Freshness	Why
Product pages	Cached (catalog)	Static shell + dynamic variant islands (PPR)
Category/Collection	Cached (catalog)	Cached hero from params; filters/pagination stream in Suspense
Homepage featured	Cached (catalog)	Sync page shell; product grid streams in nested Suspense
Navigation / footer	Cached (menus)	Per-channel tags; per-locale menu payloads in cache keys
Storefront content	Cached (menus)	Tag storefront-content:{channel}:{locale}
Cart drawer	Always live	Saleor API with cache: "no-cache"
Checkout	Always live	RSC entry + server actions (cache: "no-cache"), real-time totals

cacheLife tiers (see src/lib/cache-life-profiles.ts):

Profile	Fallback TTL	Used for
catalog	~5 min	Products, categories, collections, homepage
menus	~1 hr	Header nav, footer menu
channels	~1 day	Footer channel metadata

Webhook revalidateTag(tag, profile) clears data immediately; TTL is the safety net when webhooks are missing.

Locale

Browse URLs are /{locale}/{channel}/…. Cached catalog fetches pass localeSlug — separate cache entry per language, same warm-path speed. Invalidation uses slug-scoped tags (product:{slug}) and re