상품 목록 그리드
상품 목록 그리드, 빈 카탈로그와 안전한 카드 링크를 표시합니다.
준비
ecommerce를 켜고 Publishable Key를 사용하며, 활성 마켓에 배정된 상품을 하나 이상 공개하세요. 빠른 시작부터 시작합니다. 이 예제는 서버에서 SDK를 호출합니다. 브라우저에서 호출하려면 먼저 브라우저 origin을 허용하세요.
예제는 Next.js App Router 앱에서 요청마다 실행됩니다. 확인한 버전과 구성은 빌드 옵션에 있습니다.
목록 그리드 표시
// app/products/page.tsx
import { createClient } from '@01.software/sdk'
export const dynamic = 'force-dynamic'
export default async function ProductsPage() {
const client = createClient({
publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY!,
apiUrl: process.env.SOFTWARE_API_URL,
})
const page = await client.commerce.product.listingPage({
limit: 24,
basePath: '/products',
emit: 'canonical-id',
})
if (page.cards.length === 0) return <p>No published products yet.</p>
return (
<ul>
{page.cards.map((card) => (
<li key={card.id}>
<a href={card.href}>
{typeof card.title === 'string'
? card.title
: (card.title.en ?? card.title.ko ?? 'Untitled')}
</a>
<span>{card.priceRange.minPrice}</span>
<ul aria-label="Options">
{card.swatches.map((swatch) => (
<li key={swatch.optionValueId}>
<a href={swatch.href}>{swatch.label}</a>
</li>
))}
</ul>
</li>
))}
</ul>
)
}정상·빈 결과·실패
/products를 여세요. listingPage()는 색상 조합이 아니라 상품 단위로 페이지를 나누고, 상세 레시피로 이어지는 카드와 색상 견본 URL을 만듭니다. 카드가 0개이면 성공한 빈 카탈로그입니다. unlisted 상품은 목록에서 빠지지만 상세 URL로 직접 열 수 있습니다. 초안, 보관됨, 아직 공개 시점이 되지 않은 상품은 공개되지 않습니다. 목록과 상세에서 같은 마켓과 콘텐츠 언어를 사용하세요.
키·기능·워크스페이스·네트워크 오류는 예외로 던져집니다. 잡아서 빈 목록으로 바꾸지 마세요. 다음 읽기 재시도 경계를 복사하세요.
// app/products/error.tsx
'use client'
export default function ProductError({ reset }: { reset: () => void }) {
return (
<div role="alert">
Catalog unavailable. <button onClick={reset}>Retry read</button>
</div>
)
}공개 재고 경계
카탈로그 카드와 상세는 공개 상품 데이터입니다. availableForSale은 캐시된 힌트일 뿐, 재고 수량이나 예약이 아닙니다. stock, reservedStock을 표시하거나 카탈로그 데이터로 구매 가능 수량을 계산하지 마세요. stockSnapshot()은 특정 시점의 재고를, stockCheck()는 요청한 수량을 확인합니다. Checkout이 재고를 다시 확인해 최종 판단합니다. 이 중 어떤 조회도 재고를 예약하지 않습니다.
다음 액션
카드나 색상 견본을 상품 상세에서 여세요. 전체 구매 흐름은 Ecommerce, 쿼리 hook은 SDK Import 경계, 캐시 무효화는 Storefront Cache Resources, 카탈로그 운영 책임은 커머스 운영을 참고하세요.