Nuxt Shopify

Instead of downloading all possible variants and matching them client-side, use the selectedOrFirstAvailableVariant GraphQL field. This field accepts a selectedOptions argument of type [SelectedOptionInput!], which is a list of { name, value } pairs.

This approach allows Shopify to return the exact variant the customer is looking for (or the first available one if no match is found) in a single request.

GraphQL Query Pattern

product(handle: $handle) {
  title
  description
  featuredImage {
    ...ImageFields
  }
  options {
    ...ProductOptionFields
  }
  selectedOrFirstAvailableVariant(selectedOptions: $selectedOptions) {
    ...ProductVariantFields
  }
}

The module automatically generates GraphQL types and schema files in the .nuxt directory:

• .nuxt/shopify/<client>: Type definitions
• .nuxt/shopify/schema: GraphQL schema files

To enable IDE support, the module generates a .nuxt/graphql.config.mjs file. You can export this in your project root to point your editor's GraphQL plugin to it:

// ~/graphql.config.mjs
export { default } from "./.nuxt/graphql.config.mjs"

You can disable this generation by setting graphql.generateConfig: false in the module config.

Every API client (Storefront, Customer Account, or Admin) can have a specific apiVersion pinned. If left unset, the module automatically uses the current stable version available at build time. Pinning a version ensures that your codebase only upgrades when you explicitly change the configuration during a rebuild.

export default defineNuxtConfig({
  shopify: {
    name: 'nuxt-module-store',
    clients: {
      storefront: {
        apiVersion: '2026-04',
        publicAccessToken: '...',
      },
    },
  },
})

The module determines which client (Storefront, Admin, or Customer Account) an operation belongs to based on file location and naming conventions defined by the documents glob patterns.

Default Routing Rules:

• Storefront: The default. Any GraphQL found in the app is treated as a Storefront operation unless scoped otherwise.
• Admin: Matches files in an admin/ directory or files named *.admin.{ts,js,gql,graphql}.
• Customer Account: Matches files in customer-account/, customer/, or account/ directories, or files named *.customer-account.*, *.customer.*, or *.account.*.

To keep shared documents organized and correctly routed, it is recommended to place them under graphql/<client>/ in your project root.

The module parses your configuration on startup and provides the resolved results through Nuxt's useRuntimeConfig(). There are three ways to access the configuration depending on your needs and environment:

• useRuntimeConfig()._shopify: The full resolved configuration. This is typed as ShopifyConfig and contains sensitive credentials. Use this only on the server side; it must never reach the browser.
• useRuntimeConfig().public._shopify: A filtered copy of the resolved configuration that is safe to use in the browser. It is typed as PublicShopifyConfig.
• useRuntimeConfig().shopify: The raw, unresolved configuration input provided in your config files.

A Shopify cart is server-side state identified by a client-side handle (Cart ID). To maintain a persistent cart across page reloads, you should store this ID in a cookie.

In this implementation, a useCart composable is used to manage the cart lifecycle. It provides reactive state for cart lines, total quantity, total cost, and the checkout URL, along with methods to perform mutations. Every mutation returns the updated cart object, ensuring the client-side state stays in sync with Shopify.

const { 
  lines, 
  quantity, 
  total, 
  checkoutUrl, 
  loading, 
  get, 
  add, 
  update, 
  remove 
} = useCart()

The module provides specialized support for three primary Shopify APIs:

• Storefront API: Used to query your Shopify store for products, collections, and other public data.
• Customer Account API: Used to manage customer-specific data and authentication.
• Admin API: Used for backend management of your Shopify store.

Additionally, the module supports advanced features like Webhooks (with automatic validation), Analytics (with built-in consent handling via the Customer Privacy API), and Caching for both client and server-side responses.

When serving multiple markets, cart prices must follow the buyer's context. To ensure correct pricing, add the @inContext directive to your GraphQL mutations (like cartLinesAdd or cartLinesUpdate) using the language and country variables.

Warning: A cart is created in a specific context and retains it. If a user changes their country, the existing cart lines will not re-price automatically. You should create a new cart when the shopper changes their country.

mutation AddToCart($cartId: ID!, $lines: [CartLineInput!]!, $language: LanguageCode, $country: CountryCode)
@inContext(language: $language, country: $country) {
  cartLinesAdd(cartId: $cartId, lines: $lines) {
    cart {
      ...CartFields
    }
  }
}