📖 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-side and client-side 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-side execution.

"use server";

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

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

🔒 Security & Usage Guidelines​

🛡️ Server-side Usage (Recommended)​

Use private environment variables for optimal security and performance:

✅ Best for:

• Server Components (e.g., page.tsx)
• API routes and Route Handlers
• "use server" utilities
• Static generation and SSR

⚛️ Client-side Usage (When Required)​

Use NEXT_PUBLIC_ environment variables for interactive features:

✅ Required for:

• Cart management (CartProvider, useCart())
• Real-time inventory updates
• Interactive product configurators
• Dynamic user-specific content

🔗 What's next?​

Now that you understand the basics, dive deeper into:

• Get Product →
• Get Collection →