Product Setup
Shopify product configuration for the Product Detail Page - variants, metafields, swatches, and SEO.
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 fetches 14 specific metafields to populate a product specs section. These are optional - if a metafield doesn't exist on a product, it's simply not displayed.
| Namespace | Key | Display label |
|---|---|---|
custom | material | Material |
custom | dimensions | Dimensions |
custom | weight | Weight |
custom | connectivity | Connectivity |
custom | battery_life | Battery Life |
custom | warranty | Warranty |
custom | country_of_origin | Country of Origin |
custom | model_number | Model Number |
specs | material | Material |
specs | dimensions | Dimensions |
specs | weight | Weight |
specs | connectivity | Connectivity |
specs | battery_life | Battery Life |
specs | warranty | Warranty |
Both the custom and specs namespaces are queried. If you use a different namespace for product specs, update the metafield identifiers in lib/shopify/fragments.ts and the label map in lib/shopify/transforms/product.ts.
To add these metafields in Shopify admin: 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 titleseo.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
| File | Purpose |
|---|---|
lib/shopify/fragments.ts | Product fragment with metafield identifiers (lines 60–174) |
lib/shopify/transforms/product.ts | Metafield label mapping and product transform |
lib/shopify/operations/products.ts | Product fetch operations with caching |
components/product/pdp/variants.ts | Variant resolution and swatch handling |