next-shopify-experimental

next-shopify-experimental

A Shopify toolkit for Next.js: a typed Storefront API client with built in support for Next.js 16 Cache Components.

Requirements

• Next.js 16+ with Cache Components enabled (cacheComponents: true)
• React 19
• A Shopify store with a Storefront API access token, plus a webhook signing secret for revalidation

Installation

npm install next-shopify-experimental
# or
pnpm add next-shopify-experimental
# or
yarn add next-shopify-experimental
# or
bun add next-shopify-experimental

Quick start

1. Enable Cache Components

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  cacheComponents: true,
}

export default nextConfig

2. Create the client and a cached fetch

// lib/shopify.ts
import { createStorefrontClient } from 'next-shopify-experimental'
import { defineFetch } from 'next-shopify-experimental/cache'

// Reads SHOPIFY_STORE_DOMAIN + SHOPIFY_STOREFRONT_TOKEN from the environment.
export const { shopifyFetch } = defineFetch({
  client: createStorefrontClient(),
})

createStorefrontClient() reads your store domain and access token from the environment by convention, so the common case takes no arguments. Pass any option to override its env default, and it validates up front — a missing domain or token throws a clear, actionable error instead of failing cryptically on the first request.

3. Read data inside a 'use cache' boundary

shopifyFetch runs the query, then tags the surrounding cache entry with the GID of every resource it returned. Call it from a 'use cache' function:

// app/page.tsx
import { shopifyFetch } from '@/lib/shopify'

async function getShop() {
  'use cache'
  const { data } = await shopifyFetch<{ shop: { id: string; name: string } }>({
    query: `{ shop { id name } }`,
  })
  return data?.shop
}

export default async function Page() {
  const shop = await getShop()
  return <h1>{shop?.name}</h1>
}

4. Revalidate on change with a webhook

Add a webhook route. When Shopify reports a change, next-shopify-experimental verifies it and revalidates the matching tags:

// app/api/shopify/webhook/route.ts
export { POST } from 'next-shopify-experimental/webhook'

Then create a webhook subscription pointed at https://your-app.com/api/shopify/webhook, and set its signing secret as SHOPIFY_WEBHOOK_SECRET.

5. Set environment variables

# .env.local
SHOPIFY_STORE_DOMAIN=your-shop.myshopify.com
SHOPIFY_STOREFRONT_TOKEN=your-public-storefront-access-token
SHOPIFY_WEBHOOK_SECRET=your-webhook-signing-secret

Variable	Read by	Description
SHOPIFY_STORE_DOMAIN	createStorefrontClient	Your store's domain.
SHOPIFY_STOREFRONT_TOKEN	createStorefrontClient	A public Storefront API access token.
SHOPIFY_WEBHOOK_SECRET	the webhook handler	The webhook signing secret — read automatically by POST.

createStorefrontClient also reads SHOPIFY_STOREFRONT_PRIVATE_TOKEN (a server-only token, as an alternative to the public one) and SHOPIFY_API_VERSION (optional; otherwise a built-in default is used).

That's the whole integration: reads are cached and tagged, and a shop/update webhook busts exactly the pages that read the shop.

How it works

Every object in Shopify's API has a global ID — a GID, like gid://shopify/Shop/1. next-shopify-experimental uses it as the link between reads and writes:

• On read, shopifyFetch scans the response for GIDs and tags the cache entry with each one (shopify:shop:1).
• On write, your webhook receives the same GID, resolves it to the same tag, and calls revalidateTag.

Because both sides derive the tag from the same GID, a change invalidates exactly the cache entries that read that resource — with no tag bookkeeping on your part.

API reference

createStorefrontClient

Creates the Storefront API client, reading configuration from the environment by convention so the common case is zero-argument. It validates up front — a missing store domain or access token throws a clear, actionable error rather than failing cryptically on the first request. Pass any option to override its env default.

import { createStorefrontClient } from 'next-shopify-experimental'

// Reads SHOPIFY_STORE_DOMAIN + SHOPIFY_STOREFRONT_TOKEN from the environment:
const client = createStorefrontClient()

// …or override any option:
const client = createStorefrontClient({ apiVersion: '2025-10' })

Every option is optional; each falls back to an environment variable:

Option	Falls back to	Description
storeDomain	SHOPIFY_STORE_DOMAIN	Your *.myshopify.com (or custom) domain.
publicAccessToken	SHOPIFY_STOREFRONT_TOKEN	A public Storefront access token (safe in the browser).
privateAccessToken	SHOPIFY_STOREFRONT_PRIVATE_TOKEN	A private Storefront access token (server only).
apiVersion	SHOPIFY_API_VERSION (or default)	Storefront API version, e.g. '2026-04'.

A store domain and exactly one access token are required (from config or the environment). It also accepts the client's remaining options (clientName, retries, customFetchApi, logger).

createStorefrontApiClient

The raw client factory, re-exported from @shopify/storefront-api-client (along with all of its types) unchanged — no env convention, no validation. Reach for it when you want full, unmanaged control; otherwise prefer createStorefrontClient. request() is return-based and does not throw on GraphQL errors.

import { createStorefrontApiClient } from 'next-shopify-experimental'

const client = createStorefrontApiClient({
  storeDomain: 'your-shop.myshopify.com',
  apiVersion: '2026-04',
  publicAccessToken: process.env.SHOPIFY_STOREFRONT_TOKEN!,
})

defineFetch

From next-shopify-experimental/cache. Binds a client to a shopifyFetch that tags reads for revalidation.

import { defineFetch } from 'next-shopify-experimental/cache'

export const { shopifyFetch } = defineFetch({ client })

Name	Type	Default	Description
client	StorefrontApiClient	—	The client returned by createStorefrontApiClient.
debug	boolean	false	Log each fetch's collected cache tags to the server console.

shopifyFetch

Returns the client's { data, errors, extensions } response, and tags the surrounding 'use cache' entry.

const { data, errors } = await shopifyFetch<TData>({ query, variables })

Name	Type	Default	Description
query	string	—	The GraphQL operation.
variables	object	—	Operation variables.
cache	boolean	true	Tag this read. Set false for a dynamic, uncached read — no 'use cache' boundary needed.
debug	boolean	inherited	Override the defineFetch debug setting for this call.

It also accepts the underlying client's request options (apiVersion, headers, retries, signal).

Inside a 'use cache' boundary, shopifyFetch tags the entry. Called outside one without cache: false, it throws with a message pointing you at both fixes.

next-shopify-experimental/webhook

POST

The convention handler — verifies with SHOPIFY_WEBHOOK_SECRET and revalidates. Re-export it as your route:

// app/api/shopify/webhook/route.ts
export { POST } from 'next-shopify-experimental/webhook'

createWebhookHandler

Use the factory when you need to configure it:

import { createWebhookHandler } from 'next-shopify-experimental/webhook'

export const POST = createWebhookHandler({
  secret: process.env.SHOPIFY_WEBHOOK_SECRET,
})

Name	Type	Default	Description
secret	string	process.env.SHOPIFY_WEBHOOK_SECRET	Webhook signing secret. The handler fails closed (500) if it's missing.
signatureVerification	boolean	true	Set false only if you verify upstream — HMAC is skipped and no secret is required.

Responses: 200 { revalidated } for a verified webhook (including topics it doesn't tag), 401 for a missing or invalid signature, 500 if the secret isn't configured.

Primitives

To build a fully custom handler, compose these directly:

Export	Description
verifyWebhook({ body, signature, secret })	Verify a Shopify webhook signature (Web Crypto, constant-time). Resolves a boolean; never throws.
getWebhookCacheTags(topic, payload)	Derive the cache tags for a verified payload — the same tags the read side produced.

Supported resources

next-shopify-experimental tags the Shop resource today. Other resources (products, collections, …) aren't tagged yet: their data still reads normally, but no tags are emitted for them and their webhooks are acknowledged without revalidation — no errors are thrown. Coverage grows as the resource registry expands.

Local example

A runnable Next.js app lives in apps/example.

License

MIT