❓ Frequently Asked Questions

The SDK works with both the App Router and Pages Router in Next.js. For the best experience, we recommend Next.js 13.4 or higher, which introduces "use server" and stable server component support.

That said, the SDK is also fully compatible with:

• getServerSideProps and getStaticProps
• API routes in the Pages Router
• Route Handlers in the App Router

To use the SDK, you need to set the following in your .env.local:

SHOPIFY_ACCESS_TOKEN=your-storefront-access-token
SHOPIFY_STORE_DOMAIN=your-shop.myshopify.com

These values come from your Shopify admin under:
Apps → Develop Apps → Configure Storefront API.

These variables must stay on the server and will never be exposed to the client.

By default, this SDK targets:

2025-04

You can customize this in the createShopifyClient() function using the apiVersion option. Keeping your API version up to date ensures compatibility with the latest Shopify features and data structures.

✅ Yes! The CORE tier is 100% open source and will always be free to use.

It includes:

• Product & collection fetching
• Cart features
• Metafield support
• Utility functions

We're committed to keeping the fundamentals accessible to everyone — forever.

When calling getProduct(), the SDK returns { data, error }.

Example:

const { data, error } = await getProduct({ handle: "my-product" });

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

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

You should always check for error before rendering. This keeps your UX clean and protects you from runtime crashes due to missing data.

Yes, but with proper security considerations.

For cart functionality (required client-side usage):

NEXT_PUBLIC_SHOPIFY_ACCESS_TOKEN=your-storefront-access-token
NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN=your-shop.myshopify.com

For data fetching (recommended server-side usage):

SHOPIFY_ACCESS_TOKEN=your-storefront-access-token
SHOPIFY_STORE_DOMAIN=your-shop.myshopify.com

✅ Client-side usage is required for:

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

✅ Server-side usage is recommended for:

• Product pages and collections
• Search results and static generation
• Better performance and SEO

Security guidelines:

• Only use Storefront API tokens for client-side (never Admin API)
• Ensure minimal required permissions
• Consider rate limiting and request validation

Yes! The getCollection() function supports:

• Filters (e.g. by price, availability, metafields)
• Sort keys like PRICE, TITLE, CREATED_AT
• Pagination using cursors (after, before)

This makes it perfect for building dynamic collection pages, category filters, or even faceted search.

👉 Learn more in Filters →

You can define metafields using the customMetafields array.
To reshape or enhance them, use the transformMetafields() option to:

• Flatten nested references
• Format or compute display values
• Create summaries or fallback text

Example:

transformMetafields: (raw, casted) => ({
  ...casted,
  metaSummary: `Brand: ${casted["custom.brand"]} · ${casted["custom.weight"]} kg`,
});

This keeps rendering logic outside of your components and inside the data layer.

Hydrogen is great — but it comes with constraints:

• Built around Vite and RSC
• Smaller community
• Custom tooling and routing

@nextshopkit/sdk lets you:

• Stay in Next.js (the most popular React meta-framework)
• Use your own stack and deploy anywhere (Vercel, AWS, Cloudflare)
• Leverage a massive ecosystem and better hiring pool

If you want flexibility, familiarity, and scalability — this SDK fits better.

Headless lets you break free from Shopify's frontend limitations. You get:

• Full design freedom (no Liquid or theme constraints)
• Better performance and SEO with SSR/SSG
• Custom checkout flows or APIs
• Seamless integration with CRMs, CDPs, or other tools

And with the PRO tier, even content like landing pages or blogs can be fully managed from inside Shopify using metaobjects.

Raw GraphQL is powerful — but also repetitive, error-prone, and hard to type.

This SDK offers:

• Pre-built functions for 90% of your use cases
• Type-safe inputs and outputs
• Easier metafield handling
• Optional transformations and customization

Most devs spend hours debugging queries. This SDK makes your work predictable and fast.

Yes! Since it runs on Next.js, it fully supports:

• Server-side rendering (SSR)
• Static generation (SSG)
• Dynamic routing
• Clean, crawlable URLs

Plus, features like rich_text rendering and transformMetafields() help you control your content for SEO without needing extra CMS tools.

No — it's designed for performance.
Because it's server-side only, it keeps your frontend lightweight and secure.

You can also cache or revalidate queries using:

• fetch-cache strategies
• Next.js revalidate or ISR
• Custom in-memory or edge caching