medusa-product-detail-logic

Reusable product detail hook logic for Medusa storefronts.

This package exposes useProduct and related service helpers used by the product detail page flow:

• variant selection
• price formatting
• stock/availability
• add-to-cart readiness and status
• media/gallery state
• wishlist (local or Medusa API)
• reviews (callback or Medusa rating endpoint)
• related products

Installation

npm install

For local development in this monorepo:

npm run build

Exports

From src/index.ts:

• useProduct hook
• product formatter/service helpers from medusa-services:
  • product-detail
  • wishlist
  • reviews
  • related-products

Quick Usage

import { useProduct } from "medusa-product-detail-logic"

const pdp = useProduct({
  initialProduct,
  onAddToCart: async (variantId, quantity) => {
    // call cart API
  },
  syncSelectionWithUrl: true,
  wishlistMedusa: {
    backendUrl: "https://your-medusa-server.com",
    publishableApiKey: "pk_...",
  },
  wishlistCustomerAuthorization: customerJwtOrNull,
  reviewsMedusa: {
    backendUrl: "https://your-medusa-server.com",
    publishableApiKey: "pk_...",
  },
  relatedProductsMedusa: {
    backendUrl: "https://your-medusa-server.com",
    publishableApiKey: "pk_...",
    regionId: "reg_...",
    limit: 8,
  },
})

useProduct Input (high level)

• initialProduct: normalized product data for PDP
• onAddToCart: async callback for cart add
• maxLineQuantity: optional per-line quantity cap
• syncSelectionWithUrl: read/write selected options in query params
• wishlistMedusa + wishlistCustomerAuthorization: enables Medusa /store/wishlist mode
• onFetchReviewsSummary: custom reviews summary callback (takes precedence)
• reviewsMedusa: fallback Medusa rating summary source (GET /store/products/:id/rating)
• onFetchRelatedProducts: custom related products callback (takes precedence)
• relatedProductsMedusa: fallback Medusa related products source

Returned API (high level)

• Core: product, isLoading, error
• Variants: options, selectedOptions, activeVariant, availableOptions, setOption
• Pricing: pricing
• Quantity: quantity, incrementQuantity, decrementQuantity, setQuantity
• Media: mediaUrls, activeMedia, activeMediaIndex, setActiveMedia
• Cart: isReadyToAddToCart, addToCartStatus, handleAddToCart
• Inventory: isAvailable, inventoryQuantity, stockStatusMessage
• Wishlist group: wishlist.{ ids, isWishlisted, toggleWishlist, status, error, refresh }
• Reviews group: reviews.{ averageRating, totalReviews, status, error, refresh, fetch }
• Related group: relatedProducts.{ items, status, error, refresh, fetch }

Required Product Shape

initialProduct should include:

• id, title, description
• options[]
• variants[] with option mapping, price, stock/backorder
• mediaUrls[]

For related-products Medusa fallback, include:

• collectionId (optional but recommended)
• tagIds (optional but recommended)

Use formatProductData export from medusa-services/product-detail to normalize Medusa Store product responses.

Notes

• Wishlist/reviews/related can run in callback mode or Medusa mode.
• If Medusa config/auth is missing, the hook falls back safely where applicable.
• This package is intended for UI-agnostic logic; render layer stays in your app.