Next.js Saleor Commerce

[!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).

1
Storefront cart                    Checkout surface
2
─────────────                      ────────────────
3
src/lib/checkout.ts                src/app/(checkout)/checkout/
4
  cookie + mutations        →        CheckoutSessionLoader (RSC)
5
@paper/session-bridge                  CheckoutApp → steps + payment
6
buildCheckoutPath()                  /checkout/complete?order= (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 — /checkout/complete?order= is separate from the active cart route.
• 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 [blocked], then checkout-management.md [blocked]. Forks on the old urql checkout: migrations/atomic/2026-06-checkout-v2/ [blocked].

🌍 International by Default

One codebase, many markets. Browse URLs are /{locale}/{channel}/… — e.g. /en/us/products/hoodie (English, US market, USD) and /fr/fr/products/hoodie (French, France, EUR) — 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.

• Region picker — header control switches locale and channel together (language + market + currency)
• Three string systems — Saleor catalog translations, merchant-editable storefront content (CMS), and code-owned UI via next-intl (messages/{locale}.json)
• Six built-in locales — en, pl, de, fr, fi, nb (extend via LOCALE_DEFINITIONS in src/config/locale.ts)

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 [blocked] · ADRs 0001 [blocked] / 0002 [blocked] · skills ui-locale-routing [blocked] / ui-i18n [blocked]

📱 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/ [blocked] — 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

---

Caching Architecture

Paper uses Cache Components (Partial Prerendering) for optimal performance—static shells load instantly while dynamic content streams in. Learn more in the Next.js documentation or see skills/saleor-paper-storefront/rules/data-caching.md [blocked] for project-specific implementation details.

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

1
┌─────────────────────────────────────────────────────────────────────┐
2
│                         DATA FRESHNESS                              │
3
├─────────────────────────────────────────────────────────────────────┤
4
│                                                                     │
5
│   Product Pages          Cart / Checkout         Payment            │
6
│   ──────────────         ──────────────          ───────            │
7
│                                                                     │
8
│   ┌───────────┐         ┌───────────┐          ┌───────────┐       │
9
│   │  CACHED   │────────▶│   LIVE    │─────────▶│   LIVE    │       │
10
│   │  5 min    │  Add    │  Always   │   Pay    │  Always   │       │
11
│   └───────────┘  to     └───────────┘          └───────────┘       │
12
│                  Cart                                               │
13
│   Fast page loads        Real-time prices       Saleor validates    │
14
│                                                                     │
15
└─────────────────────────────────────────────────────────────────────┘

How It Works

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

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 revalidates every locale path via buildPathsForAllLocales(). GraphQL uses Saleor base language codes (PL, not PL_PL). See data-caching.md [blocked] § Locale & Caching.

PPR page patterns

Cached GraphQL lives in src/lib/catalog/, src/lib/menus/, and src/lib/channels/ — not in layout or page components. Pages are thin orchestrators with nested <Suspense> for dynamic islands.

PDP — params only in the static shell; gallery and variant selection read searchParams:

1
ProductPage (sync)
2
└── ProductShell → getProductData(slug, channel, locale) "use cache"
3
    ├── h1, attributes, JSON-LD, LCP preload
4
    ├── Suspense → VariantGalleryDynamic (searchParams)
5
    └── Suspense → VariantSectionDynamic (searchParams)

PLP (category, collection, all products) — cached hero/metadata from params; filter/sort/pagination in a dynamic grid:

1
Page
2
├── CategoryHero ← getCategoryData "use cache"
3
└── Suspense → CategoryProducts (searchParams, always fresh fetch)

Homepage — sync <section> shell; featured collection grid in nested Suspense.

Loading UX — route-level loading.tsx files (products, categories, collections) show skeletons during navigation. The main layout does not wrap {children} in Suspense fallback={null}.

Cache tags (see src/lib/cache-manifest.ts):

Featured homepage products use tag collection:featured-products (same catalog profile as collections).

Instant Updates with Webhooks

Saleor Cloud (recommended): Install the Saleor Cloud Paper app from Dashboard → Extensions. Available on Saleor Cloud only for now. It registers revalidation webhooks for products, categories, collections, pages, menus, and promotions; discovers cache tags via /api/cache-info; and adds Preview in storefront on product pages in Dashboard.

Self-hosted / manual setup:

1. Create webhooks in Saleor Dashboard → Configuration → Webhooks
2. Point to https://your-store.com/api/revalidate
3. Subscribe to product/category/collection/page events; for menus use MENU_* / MENU_ITEM_* and include { menu: { slug } } for navbar and footer menus
4. Set SALEOR_WEBHOOK_SECRET env var

Manual revalidation (requires REVALIDATE_SECRET):

1
# Single product (all locale cache entries for slug)
2
curl "https://your-store.com/api/revalidate?secret=xxx&tag=product:blue-hoodie"
3

4
# Single product path (one locale; tag still clears all locales)
5
curl "https://your-store.com/api/revalidate?secret=xxx&tag=product:blue-hoodie&path=/pl/default-channel/products/blue-hoodie"
6

7
# CMS page (tag only — invalidates getPageData across channels)
8
curl "https://your-store.com/api/revalidate?secret=xxx&tag=page:about-us"
9

10
# Navigation for one channel (tag or tag + channel query)
11
curl "https://your-store.com/api/revalidate?secret=xxx&tag=navigation:us"
12
curl "https://your-store.com/api/revalidate?secret=xxx&tag=navigation&channel=us"
13

14
# All tags for every storefront channel
15
curl "https://your-store.com/api/revalidate?secret=xxx&all=1"

Without webhooks? TTL handles it—cached data expires per the catalog / menus / channels profiles above.

Why This Is Safe

• Saleor is the source of truth: checkoutLinesAdd calculates prices server-side
• Cart always fetches fresh: Users see current prices before checkout
• Payment validates: checkoutComplete uses real-time data

📚 Deep dive: See skills/saleor-paper-storefront/rules/data-caching.md [blocked] for the full architecture, Cache Components (PPR), webhook setup, and debugging guide.

---

Quick Start

[!NOTE] New to Saleor? Check out saleor.io/start to learn how storefronts work underneath.

1. Get a Saleor Backend

Option A: Free Saleor Cloud account (recommended)

Option B: Run locally with Docker

2. Clone & Configure

1
# Using Saleor CLI (recommended)
2
npm i -g @saleor/cli@latest
3
saleor storefront create --url https://{YOUR_INSTANCE}/graphql/
4

5
# Or manually
6
git clone https://github.com/saleor/storefront.git
7
cd storefront
8
cp .env.example .env
9
pnpm install
10

11
# Optional — wire agent skills for Cursor (see "For AI Agents" below)
12
pnpm skills:bootstrap

Edit .env with your Saleor instance details:

1
NEXT_PUBLIC_SALEOR_API_URL=https://your-instance.saleor.cloud/graphql/
2
NEXT_PUBLIC_DEFAULT_CHANNEL=default-channel  # Your Saleor channel slug

Multi-channel (recommended — explicit allowlist):

1
STOREFRONT_CHANNELS=us,uk,eu
2
NEXT_PUBLIC_DEFAULT_CHANNEL=us
3
NEXT_PUBLIC_STOREFRONT_LOCALES=en,pl,de,fr,fi,nb  # URL locale slugs
4
SALEOR_APP_TOKEN=...  # Server-side only — footer currency selector metadata

Finding your channel slug: In Saleor Dashboard → Configuration → Channels → copy the slug

Note: SALEOR_APP_TOKEN alone no longer auto-discovers every Saleor channel. Set STOREFRONT_CHANNELS or opt in with STOREFRONT_DISCOVER_CHANNELS=true (see Environment Variables).

3. Run

1
pnpm dev

Open localhost:3000. That's it.

---

Development

Commands

1
pnpm dev                    # Start dev server
2
pnpm build                  # Production build
3
pnpm run generate           # Regenerate GraphQL types (storefront)
4
pnpm run generate:checkout  # Regenerate GraphQL types (checkout)

Project Structure

1
src/
2
├── app/                    # Next.js App Router
3
│   ├── (storefront)/[locale]/[channel]/  # Browse, cart, account
4
│   └── (checkout)/checkout/              # Checkout route (/checkout)
5
├── messages/               # next-intl UI strings (per locale)
6
├── session-bridge/         # @paper/session-bridge — storefront ↔ checkout handoff
7
├── checkout/               # Checkout UI, providers, payment registry (GraphQL via server actions)
8
├── graphql/                # GraphQL queries
9
├── gql/                    # Generated types (don't edit)
10
├── lib/                    # Server utilities & cached data layer
11
│   ├── catalog/            # getCategoryData, getCollectionData, getFeaturedProducts
12
│   ├── menus/              # getNavbarMenuItems, getFooterMenuItems
13
│   ├── channels/           # getCachedChannelsList
14
│   ├── cache-manifest.ts   # Tag registry + cacheLife mapping
15
│   └── cache-life-profiles.ts
16
├── ui/components/          # UI components
17
│   ├── account/            # Customer profile & address book
18
│   ├── pdp/                # Product detail page
19
│   ├── plp/                # Product listing page
20
│   ├── cart/               # Cart drawer
21
│   └── ui/                 # Primitives (Button, Badge, etc.)
22
└── styles/brand.css        # Design tokens

For AI Agents

If you're working with AI coding assistants, point them to:

• AGENTS.md — Architecture, commands, gotchas
• skills/saleor-paper-storefront/ — 21 project-specific rules (GraphQL, caching, i18n, checkout, etc.)
• skills/saleor-paper-storefront/references/code-conventions.md — File naming, exports, imports
• saleor/agent-skills — Universal Saleor patterns and optional community skills

After clone, wire skills for Cursor discovery (repo-root skills/ is not scanned automatically):

1
pnpm skills:bootstrap

Symlinks the project skill into .agents/skills/, then runs npx skills experimental_install from skills-lock.json. Do not run npx skills add . --skill saleor-paper-storefront — it copies a drifting snapshot.

Environment Variables

1
# Required
2
NEXT_PUBLIC_SALEOR_API_URL=https://your-instance.saleor.cloud/graphql/
3
NEXT_PUBLIC_DEFAULT_CHANNEL=default-channel  # Fallback channel; root "/" redirects here
4

5
# Multi-channel (recommended)
6
STOREFRONT_CHANNELS=us,uk,eu               # Comma-separated allowlist — routes, revalidation, footer
7

8
# Optional
9
NEXT_PUBLIC_STOREFRONT_URL=                  # Canonical URLs and OG images
10
NEXT_PUBLIC_DEFAULT_LOCALE=en                # Default URL locale slug
11
NEXT_PUBLIC_STOREFRONT_LOCALES=en,pl,de,fr,fi,nb  # Enabled locale slugs
12
REVALIDATE_SECRET=                           # Manual cache invalidation (GET /api/revalidate)
13
SALEOR_WEBHOOK_SECRET=                       # Webhook HMAC verification
14
SALEOR_APP_TOKEN=                            # Server-side: footer channel metadata (never exposed to client)
15
STOREFRONT_DISCOVER_CHANNELS=true            # Opt-in: discover ALL active Saleor channels from API
16
                                             # (not recommended when Saleor has many channels; prefer STOREFRONT_CHANNELS)

Channel resolution order (getStorefrontChannelSlugs):

1. STOREFRONT_CHANNELS — explicit allowlist (recommended)
2. STOREFRONT_DISCOVER_CHANNELS=true + SALEOR_APP_TOKEN — all active channels from API
3. NEXT_PUBLIC_DEFAULT_CHANNEL only — single-channel storefront

---

Payments

The checkout architecture supports Saleor payment apps like Adyen and Stripe. The heavy lifting is done—integrating your gateway requires minimal work compared to building from scratch.

---

Customization

Paper works as a reference implementation and as a starting point for your own storefront. Start here:

• Colors & typography → src/styles/brand.css
• Components → src/ui/components/
• Checkout flow → src/checkout/views/saleor-checkout/

The design token system uses CSS custom properties—swap the entire color palette by editing a few lines.

---

Next Steps

Known gaps and planned improvements:

• Checkout functional i18n — checkout step labels still live in storefront content (ADR 0002); migrate to next-intl
• Filtering logic iteration — fetching attributes from API for dynamic product filters
• Error / not-found pages — localized shells for global error boundaries

---

License

FSL-1.1-ALv2 (Functional Source License, Version 1.1, ALv2 Future License) — use it, modify it, ship it. Build your storefront, run your business. The license converts to Apache 2.0 after two years.

Want to offer it as a managed service? Let's talk.

---