From saleor-commerce
Builds Next.js storefronts for Saleor with GraphQL client setup (urql/Apollo), channel routing, Tailwind CSS, server components, checkout flow, and SEO.
npx claudepluginhub orcaqubits/agentic-commerce-skills-plugins --plugin saleor-commerceThis skill is limited to using the following tools:
**Fetch live docs**:
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Guides MCP server integration in Claude Code plugins via .mcp.json or plugin.json configs for stdio, SSE, HTTP types, enabling external services as tools.
Fetch live docs:
https://docs.saleor.io/docs/developer/storefront for storefront development guidesite:docs.saleor.io storefront GraphQL client setup for client configurationsite:github.com saleor/storefront nextjs for latest storefront starter sourcesite:docs.saleor.io checkout flow storefront for checkout integrationsite:docs.saleor.io channel storefront routing for multi-channel setupSaleor storefronts are headless -- they consume the GraphQL API over HTTP:
| Layer | Component |
|---|---|
| Frontend | Next.js App Router (SSR / RSC) |
| GraphQL Client | urql, Apollo Client, or graphql-request |
| API | Saleor GraphQL endpoint (/graphql/) |
| Styling | Tailwind CSS (official starter) |
| Deployment | Vercel, Netlify, or any Node.js host |
| Client | Strengths | Best For |
|---|---|---|
urql | Lightweight, extensible, SSR-friendly | Official starter default |
Apollo Client | Mature ecosystem, normalized cache | Complex caching needs |
graphql-request | Minimal, no framework dependency | Simple server-side fetching |
fetch (raw) | Zero dependencies | One-off queries in server components |
// 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],
})
| Variable | Purpose |
|---|---|
NEXT_PUBLIC_SALEOR_API_URL | Saleor GraphQL endpoint URL |
SALEOR_API_URL | Server-side only API URL (if different) |
NEXT_PUBLIC_DEFAULT_CHANNEL | Default channel slug |
NEXT_PUBLIC_STOREFRONT_URL | Public storefront URL (for SEO) |
Saleor channels enable multi-region storefronts from a single instance:
| URL Pattern | Channel | Currency |
|---|---|---|
/en-us/products | default-channel | USD |
/en-gb/products | channel-uk | GBP |
/de/products | channel-de | EUR |
| Approach | Implementation |
|---|---|
| Path prefix | /[channel]/products in Next.js App Router |
| Subdomain | us.store.com, uk.store.com with middleware |
| Cookie/header | Single URL, channel detected from locale preference |
The channel slug is passed as an argument to every GraphQL query that returns channel-scoped data (products, pricing, collections).
| Page | Route | Data Source |
|---|---|---|
| Homepage | / | Featured products, collections |
| Product listing | /products | products(channel, first, filter) query |
| Product detail | /products/[slug] | product(slug, channel) query |
| Collection | /collections/[slug] | collection(slug, channel) query |
| Category | /categories/[slug] | category(slug) + products query |
| Cart | /cart | Local state + cart GraphQL object |
| Checkout | /checkout | checkout query and mutations |
| Account | /account | me query (authenticated) |
| Order history | /account/orders | me { orders } query |
| Search | /search | products(filter: {search}) query |
| Pattern | Use For |
|---|---|
| Server Component (RSC) | Product listing, product detail, static content, SEO metadata |
| Client Component | Cart drawer, quantity selector, add-to-cart button, checkout form |
| Server Action | Cart mutations, checkout steps, address submission |
| Route Handler | Webhook receivers, revalidation triggers |
// 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} />
}
| Step | User Action | GraphQL Operation |
|---|---|---|
| 1. Create checkout | First add-to-cart | checkoutCreate mutation |
| 2. Add lines | Add products to cart | checkoutLinesAdd mutation |
| 3. Update lines | Change quantity | checkoutLinesUpdate mutation |
| 4. Set email | Enter email | checkoutEmailUpdate mutation |
| 5. Shipping address | Enter address | checkoutShippingAddressUpdate mutation |
| 6. Billing address | Enter or same as shipping | checkoutBillingAddressUpdate mutation |
| 7. Select shipping | Choose method | checkoutDeliveryMethodUpdate mutation |
| 8. Payment | Enter payment details | transactionInitialize or gateway-specific |
| 9. Complete | Confirm order | checkoutComplete mutation |
Checkout ID is stored in a cookie for persistence across sessions and server-side access.
| Strategy | Use Case | Implementation |
|---|---|---|
| ISR | Product pages | revalidate in fetch options |
| On-demand | After product update webhook | revalidatePath / revalidateTag |
| Client cache | Cart state | urql/Apollo normalized cache |
| Static | Homepage collections | generateStaticParams |
| No cache | Checkout, account | cache: "no-store" in fetch |
| SEO Aspect | Implementation |
|---|---|
| Title and meta | generateMetadata in page components |
| Open Graph | Product images and descriptions in OG tags |
| Structured data | JSON-LD Product schema in script tags |
| Sitemap | Dynamic sitemap.xml from product/collection queries |
| Canonical URLs | alternates.canonical in metadata |
| Robots | robots.txt via Next.js convention |
| Aspect | Detail |
|---|---|
| Source | Saleor media URL from product image fields |
| Optimization | Next.js <Image> component with remote patterns |
| Thumbnails | Saleor generates thumbnails at configurable sizes |
| CDN | Configure next.config.js remotePatterns for Saleor domain |
channel argumentgenerateStaticParams for product and collection pages for SEO and speedFetch the Saleor storefront documentation for exact GraphQL query patterns, checkout mutation sequences, and channel routing strategies before implementing.