$ARGUMENTS

• 1

  → Step 1: Project Bootstrap

• 2

  → Step 2: Design & Aesthetic

• 3

  → Step 3: Catalog — Product List + PDP

Saleor Storefront Builder

Usage: /storefront-builder <step>

Steps:
  1   Bootstrap — wire GraphQL client, codegen, Saleor API connection
  2   Design & aesthetic — color palette, typography, accent color
  3   Catalog — product list page + product detail page with variant selection

Example: /storefront-builder 1

"Do you have a Saleor instance ready?

• No — create one at https://cloud.saleor.io/ (free tier available), then come back with the API URL.
• Yes — paste your storefront/API URL and we'll get started."

package.json

nuxt.config.ts

next.config.*

svelte.config.js

remix.config.js

vite.config.*

• Framework and version
• Package manager in use (check for lockfiles:

  pnpm-lock.yaml

  ,

  yarn.lock

  ,

  package-lock.json

  )
• Existing GraphQL setup (if any)
• Import alias conventions (e.g.

  @/

  ,

  ~/

  ,

  #

  )
• Source directory layout (

  src/

  ,

  app/

  , flat root)

codegen.ts

codegen.js

• schema: Saleor GraphQL API URL, read from the env variable the project uses (or

  SALEOR_API_URL

  if none is established)
• documents: glob pointing to the project's GraphQL files directory, following local conventions
• generates: use the

  client

  preset with

  gqlTagName: "graphql"

codegen

package.json

NEXT_PUBLIC_*

NUXT_PUBLIC_*

• [PUBLIC_PREFIX]_SALEOR_API_URL

  — Saleor GraphQL endpoint

• [PUBLIC_PREFIX]_SALEOR_CHANNEL

  — default channel slug

• SALEOR_APP_TOKEN

  (no public prefix — server-side only)

.env.local

.env

Tip — inspecting an existing store with Configurator If you have access to an existing Saleor instance and are unsure what channels, categories, or products are configured, use the Configurator CLI:

bash

export SALEOR_URL=https://your-store.saleor.cloud/graphql/
export SALEOR_TOKEN=YOUR_TOKEN
pnpm dlx @saleor/configurator introspect

Read the resulting

config.yml

to find exact channel slugs, published products, and category structure — use these values directly in env and queries.

• CSS framework in use (Tailwind, CSS Modules, styled-components, UnoCSS, vanilla CSS, etc.)
• Existing design token conventions (CSS custom properties, a

  theme.*

  file, Tailwind config, etc.)
• Where shared styles live

"Let's define the look of your storefront. A few quick questions:

1. Do you have any references? (a brand, a URL, a screenshot — or skip)
2. What's the general vibe? Some starting points if helpful: minimalist light, dark luxury, bold & colorful, soft & warm, classic editorial — or describe it in your own words.
3. Any accent color in mind? This goes on buttons and links. A hex, a color name, or leave it to me."

• Style preset name
• Reference (if any)
• Accent rationale
• Typography choice

• Tailwind: extend

  tailwind.config.*

  with the token values
• CSS custom properties: write to the project's global CSS file
• Other: follow what's already in use

/storefront-builder 1

"What's your Saleor channel slug? (Saleor Dashboard → Channels, or press Enter for 'default-channel')"

getStaticProps

load

asyncData

fragment ProductCard on Product {
  id
  name
  slug
  thumbnail {
    url
    alt
  }
  pricing {
    priceRange {
      start {
        gross {
          amount
          currency
        }
      }
    }
  }
  category {
    name
    slug
  }
}

• thumbnail

  is nullable — always guard with a fallback image or placeholder

• pricing.priceRange.start

  is nullable — guard before rendering price

• category

  is nullable — guard before rendering category label

fragment ProductDetails on Product {
  id
  name
  slug
  description
  thumbnail {
    url
    alt
  }
  media {
    url
    alt
    type
  }
  pricing {
    priceRange {
      start {
        gross {
          amount
          currency
        }
      }
    }
  }
  category {
    name
    slug
  }
  variants {
    id
    name
    sku
    pricing {
      price {
        gross {
          amount
          currency
        }
      }
      priceUndiscounted {
        gross {
          amount
          currency
        }
      }
    }
    selectionAttributes: attributes(variantSelection: VARIANT_SELECTION) {
      attribute {
        name
        slug
      }
      values {
        name
        slug
      }
    }
    quantityAvailable
  }
}

• media

  array preferred over

  thumbnail

  on PDP — use

  thumbnail

  as fallback when

  media

  is empty

• variants.pricing

  is nullable — guard before accessing

  amount

• quantityAvailable

  is nullable for anonymous users — treat

  null

  as in-stock (behave as if 1 available)

• selectionAttributes

  uses

  variantSelection: VARIANT_SELECTION

  filter — returns only variant-differentiating attributes (size, color, etc.), not product-level attributes

• On PDP: prefer

  product.media[0]

  over

  thumbnail

  ; fall back to

  thumbnail

  if

  media

  is empty
• Always guard for missing images — render a neutral placeholder, not a broken

  <img>

  tag
• Use

  alt ?? product.name

  as the alt text fallback

• quantityAvailable === null

  → treat as available (anonymous users don't see inventory)

• quantityAvailable === 0

  → out of stock — disable selection and show visual indicator (strikethrough or muted)

• quantityAvailable > 0

  → in stock

• Show all variants; disable (not hide) out-of-stock ones — visibility helps users understand what exists
• Use

  selectionAttributes

  to label variants (e.g. "Size: M", "Color: Red") when attributes are present
• If a product has only one variant and no selection attributes, skip the selector and go straight to Add to Cart
• The selected variant's

  pricing.price

  overrides the product-level

  pricing.priceRange

  — update the displayed price on selection

• Product list with no results: show a clear message with troubleshooting hint (wrong channel slug or products not published)
• Product not found (null from

  ProductBySlug

  ): use the framework's not-found/404 mechanism
• Pricing missing: omit price entirely rather than showing $0 or NaN

VariantSelector

ref

• Shows all variants; disables out-of-stock ones (do not hide them)
• Highlights selected variant
• Updates displayed price when a variant is selected (variant

  pricing.price

  takes precedence)
• Add to Cart button is disabled until a variant is selected (when selection is required)
• Single-variant / no-attribute products: skip selector, show Add to Cart directly
• Add to Cart is non-functional at this step — placeholder only, note this clearly in a comment

• Empty list: wrong channel slug or products not published in that channel — suggest running

  configurator introspect

  to inspect the store
• Codegen errors: API URL not set or unreachable
• Product not found on every slug: channel mismatch or product unpublished in that channel

1. Always pass

   channel

   — every product/pricing/availability query requires it; omitting it returns no data
2. Parse

   description

   safely — it is EditorJS JSON, not plain text or HTML
3. Never expose

   SALEOR_APP_TOKEN

   to the browser — use the two-client pattern; the auth client is server-side only

4. quantityAvailable

   null = available — anonymous users don't receive inventory counts; null means "don't block purchase"

5. pricing

   is nullable at every level — guard

   pricing

   ,

   pricing.price

   ,

   pricing.priceRange

   , and

   gross

   before accessing

   amount

6. Use

   Intl.NumberFormat

   for prices — never hardcode currency symbols or assume locale
7. PDP media priority:

   media[0]

   →

   thumbnail

   → placeholder
8. Disable, don't hide, out-of-stock variants — hiding them confuses users about what the product offers