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

The checkout is where most storefronts fall apart or fall short. Paper's doesn't. We aim to provide open UI components and full wiring around the whole process.

• Multi-step, mobile-first — Each step is a focused form. No infinite scrolling on phones.
• Guest & authenticated — Seamless flow for everyone. Logged-in users get address book and saved preferences.
• International address forms — Country-aware fields that adapt (US states, UK postcodes, German formats).
• Connection resilience — Automatic retries with exponential backoff. Flaky networks? Handled.
• Componentized architecture — Swap steps, add steps, remove steps. It's your checkout.
• Multi-channel ready — Different currencies and shipping zones per channel.

🌍 Multi-Channel, Multi-Currency

One codebase, many storefronts. Channel-scoped routing means /us/products and /eu/products can serve different catalogs, prices, and shipping options—all from the same deployment.

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.

📱 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] — 13 task-specific rules covering GraphQL, caching, variant selection, checkout, and more
• .agents/skills/ [blocked] — Installed community skills (Vercel React best practices, composition patterns)
• 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.

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 "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

Configure Saleor webhooks to invalidate cache immediately when data changes:

1. Create webhook in Saleor Dashboard → Configuration → Webhooks, or install the Paper Storefront app (registers product, category, collection, page, menu, and promotion webhooks automatically)
2. Point to https://your-store.com/api/revalidate
3. Subscribe to product/category/collection/page events; for menus use MENU_* / MENU_ITEM_* (Paper app forwards { menu: { slug } } for navbar and footer menus)
4. Set SALEOR_WEBHOOK_SECRET env var

Manual revalidation (requires REVALIDATE_SECRET):

1
# Single product
2
curl "https://your-store.com/api/revalidate?secret=xxx&tag=product:blue-hoodie"
3

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

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

11
# All tags for every storefront channel
12
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

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
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
│   ├── [channel]/          # Channel-scoped routes
4
│   └── checkout/           # Checkout pages
5
├── checkout/               # Checkout components & logic
6
├── graphql/                # GraphQL queries
7
├── gql/                    # Generated types (don't edit)
8
├── lib/                    # Server utilities & cached data layer
9
│   ├── catalog/            # getCategoryData, getCollectionData, getFeaturedProducts
10
│   ├── menus/              # getNavbarMenuItems, getFooterMenuItems
11
│   ├── channels/           # getCachedChannelsList
12
│   ├── cache-manifest.ts   # Tag registry + cacheLife mapping
13
│   └── cache-life-profiles.ts
14
├── ui/components/          # UI components
15
│   ├── account/            # Customer profile & address book
16
│   ├── pdp/                # Product detail page
17
│   ├── plp/                # Product listing page
18
│   ├── cart/               # Cart drawer
19
│   └── ui/                 # Primitives (Button, Badge, etc.)
20
└── 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/ — 13 project-specific rules (GraphQL, caching, checkout, etc.)
• .agents/skills/ — Installed community skills (React best practices, composition patterns)

To install the project skill for agent auto-discovery:

1
npx skills add . --skill saleor-paper-storefront

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
REVALIDATE_SECRET=                           # Manual cache invalidation (GET /api/revalidate)
11
SALEOR_WEBHOOK_SECRET=                       # Webhook HMAC verification
12
SALEOR_APP_TOKEN=                            # Server-side: footer channel metadata (never exposed to client)
13
STOREFRONT_DISCOVER_CHANNELS=true            # Opt-in: discover ALL active Saleor channels from API
14
                                             # (not recommended for large catalogs; 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/SaleorCheckout/

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

---

Next Steps

Features planned for future development:

• Filtering logic iteration. Fetching attributes from API for dynamic product filters.
• Paper App. Revalidation webhooks (products, categories, collections, menus) and Preview in storefront in Dashboard.
• Opinionated model for standard content. Moving currently hardcoded stuff like Credibility or Free checkout information to API models.

---

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.

---