<img width="1920" height="1080" alt="saleor-storefront-paper-fin" src="https://github.com/user-attachments/assets/a8e37c20-35c8-42e0-a9c5-5c0b6097b921" /> <br/> <br/> <div align="center"> <img width="180" height="180" alt="apple-touch-icon-dark" src="https://github.com/user-attachments/assets/5327c1d3-86eb-4e5b-811a-81e8a5561d19" /> <h1>Paper</h1> <p>A minimal, production-ready storefront template for <a href="https://github.com/saleor/saleor">Saleor</a>.<br/>Clean as a blank page — built to ship.</p> </div> <br/> <div align="center"> <a href="https://saleor.io/start">Learn about headless storefronts</a> <span> · </span> <a href="https://saleor.io/">Website</a> <span> · </span> <a href="https://docs.saleor.io/docs/3.x">Docs</a> <span> · </span> <a href="https://saleor.io/discord">Discord</a> <span> · </span> <a href="https://saleor.io/roadmap">Roadmap</a> </div> <br/>

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

📱 Product Pages Done Right

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

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/ — 11 task-specific rules covering GraphQL, caching, variant selection, checkout, and more
.agents/skills/ — 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

| Feature | Description | | -------------------- | --------------------------------------------------------------------------------- | | Checkout | Multi-step flow with guest/auth support, address selector, international forms | | 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 pagination | | Navigation | Dynamic menus from Saleor, mobile hamburger | | SEO | Metadata, JSON-LD, Open Graph images | | Caching | ISR with on-demand revalidation via webhooks | | 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 (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 for project-specific implementation details.

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

┌─────────────────────────────────────────────────────────────────────┐
│                         DATA FRESHNESS                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   Product Pages          Cart / Checkout         Payment            │
│   ──────────────         ──────────────          ───────            │
│                                                                     │
│   ┌───────────┐         ┌───────────┐          ┌───────────┐       │
│   │  CACHED   │────────▶│   LIVE    │─────────▶│   LIVE    │       │
│   │  5 min    │  Add    │  Always   │   Pay    │  Always   │       │
│   └───────────┘  to     └───────────┘          └───────────┘       │
│                  Cart                                               │
│   Fast page loads        Real-time prices       Saleor validates    │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

How It Works

| Component | Freshness | Why | | ----------------------- | ------------------ | ------------------------------------ | | Product pages | Cached (5 min TTL) | Instant loads, great Core Web Vitals | | Category/Collection | Cached (5 min TTL) | Fast browsing experience | | Cart drawer | Always live | Saleor API with cache: "no-cache" | | Checkout | Always live | Direct API calls, real-time totals |

Instant Updates with Webhooks

Configure Saleor webhooks to invalidate cache immediately when data changes:

Create webhook in Saleor Dashboard → Configuration → Webhooks
Point to https://your-store.com/api/revalidate
Subscribe to PRODUCT_UPDATED, CATEGORY_UPDATED, etc.
Set SALEOR_WEBHOOK_SECRET env var

Without webhooks? TTL handles it—cached data expires naturally after 5 minutes.

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

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

# Or manually
git clone https://github.com/saleor/storefront.git
cd storefront
cp .env.example .env
pnpm install

Edit .env with your Saleor instance details:

NEXT_PUBLIC_SALEOR_API_URL=https://your-instance.saleor.cloud/graphq

Storefront

Install / Use

README