%20and%20Channel%20slug%20(e.g.%20default-channel)&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)
A minimal, production-ready storefront template for Saleor.
Clean as a blank page—and unlike most templates, it's not just for screenshots.
Tip
Questions or issues? Check our Discord for help.
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.
The checkout is where most storefronts fall apart. Paper's doesn't.
- 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.
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.
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.
Not an afterthought. Focus management on step transitions, keyboard navigation everywhere, semantic HTML, proper ARIA labels. Everyone deserves to shop.
Built for front-end developers and AI agents. The codebase includes:
AGENTS.md— Architecture overview and quick reference for AI assistants- Skills system — Task-specific guides in
.claude/skills/for GraphQL workflows, component patterns, variant selection, and more - 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.
- 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
| 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 |
| Authentication | Login, register, password reset, order history |
| API Resilience | Automatic retries, rate limiting, timeouts—handles flaky connections gracefully |
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 .claude/skills/caching-strategy/SKILL.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 │
│ │
└─────────────────────────────────────────────────────────────────────┘
| 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 |
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_SECRETenv var
Without webhooks? TTL handles it—cached data expires naturally after 5 minutes.
- Saleor is the source of truth:
checkoutLinesAddcalculates prices server-side - Cart always fetches fresh: Users see current prices before checkout
- Payment validates:
checkoutCompleteuses real-time data
📚 Deep dive: See
.claude/skills/caching-strategy/SKILL.mdfor the full architecture, Cache Components (PPR), webhook setup, and debugging guide.
Option A: Free Saleor Cloud account (recommended)
Option B: Run locally with Docker
# 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 installEdit .env with your Saleor instance details:
NEXT_PUBLIC_SALEOR_API_URL=https://your-instance.saleor.cloud/graphql/
NEXT_PUBLIC_DEFAULT_CHANNEL=default-channel # Your Saleor channel slugFinding your channel slug: In Saleor Dashboard → Configuration → Channels → copy the slug
pnpm devOpen localhost:3000. That's it.
pnpm dev # Start dev server
pnpm build # Production build
pnpm run generate # Regenerate GraphQL types (storefront)
pnpm run generate:checkout # Regenerate GraphQL types (checkout)src/
├── app/ # Next.js App Router
│ ├── [channel]/ # Channel-scoped routes
│ └── checkout/ # Checkout pages
├── checkout/ # Checkout components & logic
├── graphql/ # GraphQL queries
├── gql/ # Generated types (don't edit)
├── ui/components/ # UI components
│ ├── pdp/ # Product detail page
│ ├── plp/ # Product listing page
│ ├── cart/ # Cart drawer
│ └── ui/ # Primitives (Button, Badge, etc.)
└── styles/brand.css # Design tokens
If you're working with AI coding assistants, point them to:
AGENTS.md— Architecture, commands, gotchas.claude/skills/— Task-specific guides (GraphQL, components, checkout, etc.)
# Required
NEXT_PUBLIC_SALEOR_API_URL=https://your-instance.saleor.cloud/graphql/
# Optional
NEXT_PUBLIC_STOREFRONT_URL= # For canonical URLs and OG images
REVALIDATE_SECRET= # Manual cache invalidation
SALEOR_WEBHOOK_SECRET= # Webhook HMAC verification
SALEOR_APP_TOKEN= # For channels queryThe 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.
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.
Features planned for future development:
- Filtering logic iteration. Fetching attributes from API for dynamic product filters.
- Customer Profile. Implementing new Past Orders and Address Book for signed-in customers.
- Paper App. Iteration on the revalidation logic and supported webhooks, providing a Preview in storefront feature in Saleor Dashboard.
- Opinionated model for standard content. Moving currently hardcoded stuff like Credibility or Free checkout information to API models.
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.
Built with 🖤 by the Saleor team