Usage

To quickly get started building your Shopify-powered Nuxt application, you can use the useStorefront and useAdmin composables provided by the module. On the client side, you can also use the useAsyncStorefront composable for direct integration with Nuxt's async data fetching.

Depending on the module configuration, you will have access to either the Storefront API, the Admin API, or both. The composables are automatically provided when configured correctly.

Storefront API

First, ensure you have configured the module to use the Storefront API client in your nuxt.config.ts file:

export default defineNuxtConfig({
  modules: ['@nuxtjs/shopify'],

  shopify: {
    name: 'quickstart-abcd1234',

    clients: {
      storefront: {
        apiVersion: '2025-07',
        publicAccessToken: 'YOUR_ACCESS_TOKEN',
      },
    },
  },
})

Adding the publicAccessToken will enable the Storefront API client on the server and client side. If you only need access through Nitro you can set the privateAccessToken instead. When using the mock option, the client will be available on both server and client side with mock data.

Client side

Once configured, you can use the useStorefront and useAsyncStorefront composables to interact with the Storefront API.

<script setup lang="ts">
const storefront = useStorefront()

const { data: product } = await storefront.request(`#graphql
  query GetProduct($handle: String!) {
    product(handle: $handle) {
      id
      title
      description
    }
  }
`, {
  variables: {
    handle: 'high-top-sneakers',
  }
})
</script>

<template>
  <div v-if="product">
    <h1>{{ product.data.title }}</h1>

    <p>{{ product.data.description }}</p>
  </div>
</template>

<script setup lang="ts">
const handle = 'high-top-sneakers'

const { data: product } = await useAsyncStorefront(`product-${handle}`, `#graphql
  query GetProduct($handle: String!) {
    product(handle: $handle) {
      id
      title
      description
    }
  }
`, {
  variables: {
    handle,
  }
})
</script> 

<template>
  <div v-if="product">
    <h1>{{ product.title }}</h1>

    <p>{{ product.description }}</p>
  </div>
</template>

Server side

On the server side, you can use the useStorefront composable in server routes, server middleware, or API routes.

export default defineEventHandler(async (event) => {
  const { handle } = getQuery(event)

  const storefront = useStorefront()

  const { data: product } = await storefront.request(`#graphql
    query GetProduct($handle: String!) {
      product(handle: $handle) {
        id
        title
        description
      }
    }
  `, {
    variables: {
      handle,
    }
  })

  return product
})

Admin API

First, ensure you have configured the module to use the Admin API client in your nuxt.config.ts file:

export default defineNuxtConfig({
  modules: ['@nuxtjs/shopify'],

  shopify: {
    name: 'quickstart-abcd1234',

    clients: {
      admin: {
        apiVersion: '2025-07',
        accessToken: 'YOUR_ACCESS_TOKEN',
      },
    },
  },
})

Adding the accessToken will enable the Admin API client on the server side only. Using the Admin API on the client side is not supported due to security reasons. If you want to use admin functionality on the client side, you need to create server endpoints that use the Admin API client and call them from the client side.

Server side

Once configured, you can use the useAdmin composable within your Nitro endpoints.

export default defineEventHandler(async (event) => {
  const admin = useAdmin()

  const { data: product } = await admin.request(`#graphql
    query GetProduct($handle: String!) {
      product(handle: $handle) {
        id
        title
        description
      }
    }
  `, {
    variables: {
      handle: 'high-top-sneakers',
    }
  })

  return product
})

Fragments

When using the Shopify GraphQL APIs, it's common to reuse fragments across multiple queries and mutations. The module provides a way to define and use fragments easily. You can define your fragments in a separate file and import them into your queries or mutations.

It is recommended to organize your fragments in the ~/graphql directory within your project structure. Files within this directory will be scanned for code generation and auto-imported by default.

Anywhere in the codebase, including the ~/graphql directory, files for the Storefront API will be evaluated by default. Files for the Admin API need to be placed in an admin subdirectory or use the file ending *.admin.{ts,js,vue}.

<script setup lang="ts">
const props = defineProps<{
  handle: string
}>()

const key = computed(() => `product-${props.handle}`)

const { data: products } = await useAsyncStorefront(key, `#graphql
  query GetProduct($handle: String!) {
    product(handle: $handle) {
      ...ProductFields
    }
  }
  ${PRODUCT_FRAGMENT}
`, {
  variables: props,
})
</script>

<template>
  <div
    v-for="product in products"
    :key="product.id"
  >
    <h2>{{ product.title }}</h2>
    <p>{{ product.description }}</p>
  </div>
</template>

Generated Types

The code generation process will automatically create TypeScript types for your GraphQL queries, mutations and fragments. These types will be based on the schema defined in your Shopify store and will be available for use throughout your application.

Generated types will be placed in the ./.nuxt/types/storefront and ./.nuxt/types/admin directories and will be auto-imported by default. When for example using the useAsyncStorefront composable, the types will be inferred automatically. When you want to be able to pass objects from a client response to another component or function, you can use the auto-imported types directly.

<script setup lang="ts">
import type { ProductFieldsFragment } from '#shopify/storefront' // Auto-imported type

defineProps<{
  product: ProductFieldsFragment
}>()
</script>

<template>
  <div>
    <h2>{{ product.title }}</h2>
    <p>{{ product.description }}</p>
  </div>
</template>

Auto-Imports

The module provides auto-imports for all generated types from the Storefront and Admin APIs. You can find the generated types under the #shopify/storefront and #shopify/admin import paths.

For example, if you have a fragment named ProductFields in your Storefront API queries, you can import the generated type ProductFieldsFragment like this:

import type { ProductFieldsFragment } from '#shopify/storefront'

This allows you to use the generated types directly in your components, composables, or any other part of your application. You can also import types for queries and mutations. For example, if you have a query named GetProduct, you can import the generated type GetProductQuery like this:

import type { GetProductQuery } from '#shopify/storefront'

By default, the module will auto-import all generated types for the Storefront and Admin APIs, as well as the contents of the ~/graphql directory. You can customize this behavior in the module configuration:

export default defineNuxtConfig({
  shopify: {
    autoImports: {
      storefront: true,
      admin: true,
      graphql: true,
    }
  },
})