🧪 Usage Examples

Real-world examples of how to use getCollection() with filtering, pagination, sorting, metafields, and server integration.

📦 Basic Collection Query

TypeScript
JavaScript

import type { FetchCollectionResult } from "@nextshopkit/sdk";

const result: FetchCollectionResult = await getCollection({
  collectionHandle: "solar-kits",
  includeProducts: true,
});

const result = await getCollection({
  collectionHandle: "solar-kits",
  includeProducts: true,
});

🎯 Filter by Product Type and Availability

TypeScript
JavaScript

import type { ProductFilter } from "@nextshopkit/sdk";

const filters: ProductFilter[] = [
  { available: true },
  { productType: "Solar Panels" },
];

const result = await getCollection({
  collectionHandle: "solar-kits",
  includeProducts: true,
  filters,
});

const result = await getCollection({
  collectionHandle: "solar-kits",
  includeProducts: true,
  filters: [{ available: true }, { productType: "Solar Panels" }],
});

🔍 Filter by Metafield Value

TypeScript
JavaScript

import type { CustomMetafieldDefinition } from "@nextshopkit/sdk";

const result = await getCollection({
  collectionHandle: "solar-kits",
  includeProducts: true,
  filters: [
    {
      productMetafield: {
        namespace: "custom",
        key: "category",
        value: "Batteries",
      },
    },
  ],
  productMetafields: [
    {
      field: "custom.category",
      type: "single_line_text",
    } satisfies CustomMetafieldDefinition,
  ],
});

const result = await getCollection({
  collectionHandle: "solar-kits",
  includeProducts: true,
  filters: [
    {
      productMetafield: {
        namespace: "custom",
        key: "category",
        value: "Batteries",
      },
    },
  ],
  productMetafields: [{ field: "custom.category", type: "single_line_text" }],
});

💶 Price Range Filtering

TypeScript
JavaScript

const result = await getCollection({
  collectionHandle: "solar-kits",
  includeProducts: true,
  filters: [
    {
      price: {
        min: 100,
        max: 1000,
      },
    },
  ],
  sortKey: "PRICE",
  reverse: false,
});

const result = await getCollection({
  collectionHandle: "solar-kits",
  includeProducts: true,
  filters: [
    {
      price: {
        min: 100,
        max: 1000,
      },
    },
  ],
  sortKey: "PRICE",
  reverse: false,
});

⚛️ React Pagination Example (Client + Server)

This example uses the "use server" pattern from Next.js 13.4+ — no API route needed.

TypeScript
JavaScript

lib/NextShopKit/collection.ts
"use server";

import { getCollection } from "@/lib/NextShopKit/server";
import type { FetchCollectionResult } from "@nextshopkit/sdk";

export async function getPaginatedCollection(
  cursor?: string
): Promise<FetchCollectionResult> {
  return await getCollection({
    collectionHandle: "solar-kits",
    includeProducts: true,
    sortKey: "CREATED",
    limit: 8,
    cursor,
  });
}

components/ProductList.tsx
"use client";

import { useEffect, useState } from "react";
import { getPaginatedCollection } from "@/lib/server/collection";
import type { Product } from "@nextshopkit/sdk";

export default function ProductList() {
  const [products, setProducts] = useState<Product[]>([]);
  const [cursor, setCursor] = useState<string | null>(null);
  const [hasNextPage, setHasNextPage] = useState(true);

  useEffect(() => {
    const loadProducts = async () => {
      const result = await getPaginatedCollection(cursor ?? undefined);

      if (result?.error) {
        console.error(result.error);
        return;
      }

      setProducts((prev) => [...prev, ...result.data]);
      setCursor(result.pageInfo?.endCursor ?? null);
      setHasNextPage(!!result.pageInfo?.hasNextPage);
    };

    loadProducts();
  }, [cursor]);

  return (
    <>
      <div>
        {products.map((p) => (
          <div key={p.id}>{p.title}</div>
        ))}
      </div>
      {hasNextPage && (
        <button onClick={() => setCursor(cursor)}>Load more</button>
      )}
    </>
  );
}

lib/NextShopKit/collection.js
"use server";

import { getCollection } from "@/lib/NextShopKit/server";

export async function getPaginatedCollection(cursor) {
  return await getCollection({
    collectionHandle: "solar-kits",
    includeProducts: true,
    sortKey: "CREATED",
    limit: 8,
    cursor,
  });
}

components/ProductList.js
"use client";

import { useEffect, useState } from "react";
import { getPaginatedCollection } from "@/lib/server/collection";

export default function ProductList() {
  const [products, setProducts] = useState([]);
  const [cursor, setCursor] = useState(null);
  const [hasNextPage, setHasNextPage] = useState(true);

  useEffect(() => {
    const loadProducts = async () => {
      const result = await getPaginatedCollection(cursor ?? undefined);

      if (result?.error) {
        console.error(result.error);
        return;
      }

      setProducts((prev) => [...prev, ...result.data]);
      setCursor(result.pageInfo?.endCursor ?? null);
      setHasNextPage(!!result.pageInfo?.hasNextPage);
    };

    loadProducts();
  }, [cursor]);

  return (
    <>
      <div>
        {products.map((p) => (
          <div key={p.id}>{p.title}</div>
        ))}
      </div>
      {hasNextPage && (
        <button onClick={() => setCursor(cursor)}>Load more</button>
      )}
    </>
  );
}

❌ Error Handling

TypeScript
JavaScript

import type { FetchCollectionResult } from "@nextshopkit/sdk";

const result: FetchCollectionResult = await getCollection({
  collectionHandle: "solar-kits",
  includeProducts: true,
  limit: 12,
});

if (result.error) {
  console.error("Failed to fetch collection:", result.error);
} else {
  console.log("Loaded products:", result.data);
}

const result = await getCollection({
  collectionHandle: "solar-kits",
  includeProducts: true,
  limit: 12,
});

if (result.error) {
  console.error("Failed to fetch collection:", result.error);
} else {
  console.log("Loaded products:", result.data);
}