Saleor Next.js Storefront

Before writing code

Fetch live docs:

1. Fetch https://docs.saleor.io/docs/developer/storefront for storefront development guide
2. Web-search site:docs.saleor.io storefront GraphQL client setup for client configuration
3. Web-search site:github.com saleor/storefront nextjs for latest storefront starter source
4. Web-search site:docs.saleor.io checkout flow storefront for checkout integration
5. Web-search site:docs.saleor.io channel storefront routing for multi-channel setup

Storefront Architecture

Saleor storefronts are headless -- they consume the GraphQL API over HTTP:

GraphQL Client Options

Client Setup Pattern

// lib/graphql-client.ts
// Fetch live docs for current client initialization
import { createClient, cacheExchange, fetchExchange } from "urql"

export const client = createClient({
  url: process.env.NEXT_PUBLIC_SALEOR_API_URL!,
  exchanges: [cacheExchange, fetchExchange],
})

Environment Variables

Channel-Based URL Routing

Saleor channels enable multi-region storefronts from a single instance:

Routing Strategy

The channel slug is passed as an argument to every GraphQL query that returns channel-scoped data (products, pricing, collections).

Key Storefront Pages

Server vs Client Component Split

Data Fetching in Server Components

// app/products/[slug]/page.tsx
// Fetch live docs for current query patterns
export default async function ProductPage({ params }) {
  const { product } = await executeQuery(ProductBySlugDocument, {
    slug: params.slug, channel: DEFAULT_CHANNEL,
  })
  return <ProductTemplate product={product} />
}

Checkout Flow

Checkout ID is stored in a cookie for persistence across sessions and server-side access.

Caching Strategies

SEO with Server Components

Image Handling

Best Practices

• Use Server Components for all data fetching -- minimize client-side JavaScript
• Store checkout ID in an HTTP-only cookie for security and SSR access
• Scope every storefront query with the channel argument
• Use generateStaticParams for product and collection pages for SEO and speed
• Implement on-demand revalidation via webhooks for real-time content updates
• Handle multi-channel at the layout or middleware level, not per-page
• Use GraphQL code generation for type safety across all queries and mutations
• Keep the checkout as a linear flow -- do not allow skipping steps

Fetch the Saleor storefront documentation for exact GraphQL query patterns, checkout mutation sequences, and channel routing strategies before implementing.