Product Setup

This page covers the Shopify admin configuration that the PDP expects. For how the page renders and how variant selection works, see Anatomy → PDP.

Basic product setup

The PDP renders any product that has a handle (URL slug) in Shopify. At minimum, a product needs:

• A title and description (rendered as HTML via descriptionHtml)
• At least one variant (even single-option products have a default variant)
• A featured image and optionally up to 10 media items (images or videos)

The template fetches up to 50 variants per product and 10 media items.

Metafields

The template ships with no metafield identifiers in PRODUCT_FRAGMENT. Metafield namespaces and keys are shop-specific (Shopify's only standard product metafield namespaces are descriptors, facts, reviews, shopify, etc. — not generic spec namespaces like custom or specs), so the template doesn't presume any defaults.

To wire metafields into the PDP for your store:

1. Add a metafields(identifiers: [...]) field to PRODUCT_FRAGMENT in lib/shopify/fragments.ts, importing ${METAFIELD_FRAGMENT} and selecting ...MetafieldFields inside.
2. Extend the METAFIELD_LABELS map in lib/shopify/transforms/product.ts with friendly labels for the keys you query.

Example:

metafields(identifiers: [
  {namespace: "custom", key: "material"},
  {namespace: "custom", key: "warranty"},
]) {
  ...MetafieldFields
}

Define metafields in Shopify admin under Settings → Custom data → Products → Add definition.

Color swatches

When a product option has swatch data in Shopify, the PDP renders color swatches instead of text buttons. Shopify stores swatches as either:

• A hex color value
• A swatch image URL

The template reads these from the optionValues.swatch field in the GraphQL response. To configure swatches in Shopify admin: edit a product → click an option like "Color" → assign a swatch color or image to each value.

Products without swatch data render standard text-based option pickers.

SEO fields

The template reads Shopify's native SEO fields:

• seo.title → used as the page <title> and Open Graph title
• seo.description → used as the meta description and Open Graph description

If these aren't set, the template falls back to the product title and description.

Product taxonomy

The template reads the Shopify Product Taxonomy category (up to 3 levels deep) for structured data. This is configured in Shopify admin under each product's Category field.

Collections

Products must be assigned to at least one collection to appear on collection listing pages.

Recommendations

Product recommendations on the PDP are powered by Shopify's recommendation API. No configuration is needed - Shopify generates recommendations automatically based on purchase history and product similarity.

Key files