📖 Usage Guide

Once you've installed the SDK and initialized your client, you can start fetching Shopify data with full type safety and powerful customization options.

This guide shows you how to:

• Fetch products or collections
• Work with metafields
• Handle server-only operations
• Manage errors properly

🧠 Where should I use SDK functions?​

We recommend organizing your SDK calls inside a lib/NextShopKit/ folder.

Suggested structure:

lib/NextShopKit/client.ts        ← SDK client setup
lib/NextShopKit/products.ts      ← getProduct, getCollection
lib/NextShopKit/cart.ts          ← Cart operations

You can also use the SDK directly where needed — but for larger projects, centralizing logic improves maintainability.

✅ Example: Fetch a Single Product with Error Handling​

The getProduct() function returns an object with data and error. Always check for errors before accessing the result.

import { getProduct } from "@/lib/NextShopKit/client";

export default async function ProductPage({ params }) {
  const { data, error } = await getProduct({ handle: params.handle });

  if (error || !data) {
    // Handle your error logic here
    return <div>Product not found.</div>;
  }

  return (
    <div>
      <h1>{data.title}</h1>
      <p>
        {data.price.amount} {data.price.currencyCode}
      </p>
      <div dangerouslySetInnerHTML={{ __html: data.descriptionHtml }} />
    </div>
  );
}

import { getProduct } from "@/lib/NextShopKit/client";

export default async function ProductPage({ params }) {
  const { data, error } = await getProduct({ handle: params.handle });

  if (error || !data) {
    // Handle your error logic here
    return <div>Product not found.</div>;
  }

  return (
    <div>
      <h1>{data.title}</h1>
      <p>
        {data.price.amount} {data.price.currencyCode}
      </p>
      <div dangerouslySetInnerHTML={{ __html: data.descriptionHtml }} />
    </div>
  );
}

📦 Example: Fetch Products by Collection​

This example fetches products from a collection and handles metafields and formatting:

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

export async function getCollectionProducts(slug: string) {
  return await getCollection({
    collectionHandle: slug,
    customMetafields: [
      { field: "custom.brand", type: "single_line_text" },
      { field: "custom.weight", type: "decimal" },
      { field: "custom.short_description", type: "rich_text" },
    ],
    options: {
      renderRichTextAsHtml: true,
      resolveFiles: true,
      camelizeKeys: true,
      transformMetafields: (raw, casted) => ({
        ...casted,
        metaSummary: `Brand: ${casted["custom.brand"] || "N/A"} · ${
          casted["custom.weight"] ? `${casted["custom.weight"]} kg` : ""
        }`,
      }),
    },
  });
}

You can customize this logic per use case or centralize it to reuse in many routes.

🧪 Pro Tip: "use server" in App Router​

Since Next.js 13.4, you can add "use server" to your SDK-based utilities for guaranteed server-only execution.

"use server";

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

export async function fetchProductsByCategory(category: string) {
  return await getCollection({ collectionHandle: category });
}

🔐 Important: Use SDK on the Server Only​

🔗 What’s next?​

Now that you understand the basics, dive deeper into:

• Get Product →
• Get Collection →