---
name: use-catalog-and-product-read-flows
description: >
  Load this skill when reading products, catalog listings, categories,
  collections, or regions from @techsio/storefront-data through
  storefront.hooks.products, storefront.hooks.catalog, and the related read
  hooks. Use it for region-aware inputs, query-option helpers, and suspense
  usage that waits until required params actually exist.
type: core
library: "@techsio/storefront-data"
library_version: "0.1.0"
requires:
  - setup-storefront-platform-in-next-app
sources:
  - "TechsioCZ/new-engine:libs/storefront-data/README.md"
  - "TechsioCZ/new-engine:libs/storefront-data/src/products/hooks.ts"
  - "TechsioCZ/new-engine:libs/storefront-data/src/products/medusa-service.ts"
  - "TechsioCZ/new-engine:libs/storefront-data/src/catalog/hooks.ts"
  - "TechsioCZ/new-engine:libs/storefront-data/src/catalog/medusa-service.ts"
  - "TechsioCZ/new-engine:libs/storefront-data/src/collections/hooks.ts"
  - "TechsioCZ/new-engine:libs/storefront-data/src/categories/hooks.ts"
  - "TechsioCZ/new-engine:libs/storefront-data/src/regions/hooks.ts"
---

## Setup

Start from the preset-owned read hooks. Keep region inputs explicit in the app code that knows them.

```tsx
"use client"

import { storefront } from "@/src/lib/storefront"

export function ProductGrid({
  regionId,
  countryCode,
}: {
  regionId: string
  countryCode: string
}) {
  const query = storefront.hooks.products.useProducts({
    region_id: regionId,
    country_code: countryCode,
    limit: 24,
  })

  if (query.isLoading) return <div>Loading...</div>

  return (
    <ul>
      {query.products.map((product) => (
        <li key={product.id}>{product.title}</li>
      ))}
    </ul>
  )
}
```

## Core Patterns

### Filter catalog listings through the shared catalog hook

```tsx
"use client"

import { storefront } from "@/src/lib/storefront"

export function CategoryListing({
  regionId,
  countryCode,
  categoryId,
}: {
  regionId: string
  countryCode: string
  categoryId: string
}) {
  const query = storefront.hooks.catalog.useCatalogProducts({
    region_id: regionId,
    country_code: countryCode,
    category_id: [categoryId],
    limit: 24,
  })

  if (query.isLoading) return <div>Loading...</div>

  return <div>{query.products.length} products</div>
}
```

### Use suspense detail hooks only after route and region params are ready

```tsx
"use client"

import { storefront } from "@/src/lib/storefront"

export function ProductHero({
  handle,
  regionId,
  countryCode,
}: {
  handle: string
  regionId: string
  countryCode: string
}) {
  const query = storefront.hooks.products.useSuspenseProduct({
    handle,
    region_id: regionId,
    country_code: countryCode,
  })

  if (!query.product) return null

  return <h1>{query.product.title}</h1>
}
```

### Pull option objects from the hooks when SSR or manual cache work is needed

```ts
import { storefront } from "@/src/lib/storefront"

const listQuery = storefront.hooks.products.getListQueryOptions({
  region_id: "reg_123",
  country_code: "cz",
  limit: 24,
})

const detailQuery = storefront.hooks.products.getDetailQueryOptions({
  handle: "classic-tee",
  region_id: "reg_123",
  country_code: "cz",
})
```

Use the hook surface for most reads. Use query-option helpers when SSR, manual prefetch, or loader integration needs the exact query shape.

## Common Mistakes

### CRITICAL Suspense before params exist

Wrong:

```tsx
const query = storefront.hooks.products.useSuspenseProduct({
  handle: params.handle,
  region_id: regionId,
})
```

Correct:

```tsx
const query = storefront.hooks.products.useProduct({
  handle: params.handle,
  region_id: regionId,
  enabled: Boolean(params.handle && regionId),
})
```

Suspense variants assume required inputs already exist. During routing or region bootstrap they throw instead of waiting.

Source: `libs/storefront-data/src/products/hooks.ts`, `libs/storefront-data/src/categories/hooks.ts`, `libs/storefront-data/src/collections/hooks.ts`

### HIGH App-local `useQuery` wrappers for Medusa reads

Wrong:

```ts
const products = useQuery({
  queryKey: ["products", params],
  queryFn: () => sdk.store.product.list(params),
})
```

Correct:

```ts
const products = storefront.hooks.products.useProducts(params)
```

App-local wrappers duplicate the normalization, query-key rules, and bug fixes that the preset is supposed to centralize.

Source: `libs/storefront-data/AGENTS.md`, maintainer interview

### HIGH Dropping region-sensitive inputs

Wrong:

```ts
storefront.hooks.catalog.useCatalogProducts({
  category_id: ["cat_123"],
  limit: 24,
})
```

Correct:

```ts
storefront.hooks.catalog.useCatalogProducts({
  category_id: ["cat_123"],
  region_id: "reg_123",
  country_code: "cz",
  limit: 24,
})
```

Product and catalog services normalize region-aware inputs. Missing them fragments payload shape and cache identity across the storefront.

Source: `libs/storefront-data/src/catalog/medusa-service.ts`, `libs/storefront-data/src/products/medusa-service.ts`

### HIGH Assuming custom field defaults come from the library

Wrong:

```ts
storefront.hooks.products.useProduct({
  handle: "classic-tee",
  region_id: "reg_123",
})
```

Correct:

```ts
storefront.hooks.products.useProduct({
  handle: "classic-tee",
  region_id: "reg_123",
  fields: "+variants,+metadata",
})
```

The README explicitly keeps product field defaults in the local storefront composition layer. Do not assume a universal default bundle for every storefront.

Source: `libs/storefront-data/README.md`, `libs/storefront-data/src/products/types.ts`

See also: `configure-pagination-prefetch-and-cache-policy` for prefetch behavior and normalized query-key rules.