Nuxt integration for the Storefront API, Customer Account API and Admin API. Use typed fetch clients on the server and client side with built-in fragment deduplication, proxying, caching, analytics, error handling, retries and automatic, hot-reloaded type generation from your GraphQL queries. Fully configurable, works out of the box with mock.shop for local development.
- ๐ Documentation
- ๐๏ธ Store Template
- โจ Release Notes
- โฌ๏ธ Migrating to 2.0
- ๐ Fully typed fetch clients from GraphQL schemas
- ๐ฅ Hot-reloads types automatically when your GraphQL changes
- ๐ Secure access token handling
- ๐ Storefront, Customer Account and Admin API support
- ๐ Server & client side support
- ๐ฉ Error handling optimized for Nuxt
- ๐ก Storefront API proxy, cart, checkout, search and customer account routes
- ๐งฉ GraphQL fragment injection and deduplication
- ๐๏ธ Caching for client and server-side requests
- ๐ Analytics and Customer Privacy API support
- โ๏ธ Customizable GraphQL code generation
- ๐ฆ Auto-imports for fragments, queries and generated types
- ๐ช Webhook subscription support
- ๐๏ธ Built-in GraphQL explorer for all client APIs
- ๐งญ DevTools panel for Requests, GraphQL operations and configuration
- ๐ ๏ธ Automatic mock.shop integration
- ๐ Hooks for customizing the module behavior
- ๐งช Fully tested with the latest Nuxt version
To get started, use the store template with a fully functioning Shopify store.
Run the following command to install the module in your project:
npx nuxi@latest module add shopifyOr scaffold a complete storefront from the store template:
npx nuxi@latest init -t gh:nuxt-modules/shopify/template ./my-shopOr use the manual installation
-
Install the module via npm:
npm install @nuxtjs/shopify @shopify/hydrogen
-
Add the module to your
nuxt.config.ts:export default defineNuxtConfig({ modules: [ '@nuxtjs/shopify', ], })
Add your Shopify configuration to the nuxt.config.ts:
export default defineNuxtConfig({
shopify: {
name: "my-shopify-store",
clients: {
storefront: {
apiVersion: "2026-10",
publicAccessToken: "...",
},
admin: {
apiVersion: "2026-10",
clientId: "...",
clientSecret: "...",
},
customerAccount: {
apiVersion: "2026-10",
clientId: "...",
},
},
},
})To find the configuration values for your store, check out the setup guide.
There are multiple ways of communicating with the Shopify APIs.
The easiest way is with the useStorefront composable, directly inside of your vue component or page.
To access the
useStorefrontcomposable on the client side, make sure you have added a public access token. You can add it in the module config:clients > storefront > publicAccessToken
<!-- app/pages/your-page.vue -->
<script setup lang="ts">
const storefront = useStorefront()
const { data } = await storefront.request(`#graphql
query FetchProducts($first: Int) {
products(first: $first) {
nodes {
id
title
description
}
}
}
`, {
variables: {
first: 3,
},
})
</script>
<template>
<pre>{{ data?.products }}</pre>
</template>This will fetch the first three products from your Shopify store and display them in a <pre> tag.
The data variable will be typed as FetchProductsQuery, which is auto-generated by the module to enable autocompletion and full type checking.
You can use this generated FetchProductsQuery type anywhere in your code to ensure type safety when working with the query response within components.
You can also use the useStorefrontData composable to fetch data from the Storefront API while leveraging Nuxt's built-in async data fetching under the hood.
<!-- app/pages/your-page.vue -->
<script setup lang="ts">
const { data: products, error } = await useStorefrontData("products", `#graphql
query FetchProducts($first: Int) {
products(first: $first) {
nodes {
id
title
description
}
}
}
`, {
variables: {
first: 3,
},
// Use features from useAsyncData, e.g. transform, pick, etc.
transform: (data) => flattenConnection(data.products),
})
</script>
<template>
<pre>{{ products }}</pre>
</template>Note that useStorefrontData automatically extracts the data property from the response in order to be able to reliably
stringify.
Because only data is kept, GraphQL errors don't appear in the response.
With errors.throw enabled (the default), they are thrown and available in the error ref returned by useStorefrontData.
With errors.throw: false, use the shopify:storefront:client:errors hook if you need them.
First check out the Customer Account API documentation to set up dependencies and add credentials.
Then you can access the Customer Account API on the client side with the useCustomerAccount composable.
Put your Customer Account API operations in an account, customer or customer-account directory, so that they are typed with the Customer Account API schema.
Add the shopify:customer-account middleware to redirect visitors who are not logged in to the login, because their requests fail with a 401 error:
<!-- app/pages/account/index.vue -->
<script setup lang="ts">
definePageMeta({
middleware: "shopify:customer-account",
})
const customerAccount = useCustomerAccount()
const { data } = await customerAccount.request(`#graphql
query FetchCustomer {
customer {
firstName
lastName
}
}
`)
</script>
<template>
<pre>{{ data?.customer }}</pre>
</template>The module exposes utilities to access each API via Nitro endpoints.
You can use the useStorefront utility to access the storefront API:
// server/api/products.ts
export default defineEventHandler(async (event) => {
const storefront = useStorefront(event)
return await storefront.request(`#graphql
query FetchProducts($first: Int) {
products(first: $first) {
nodes {
id
title
description
}
}
}
`, {
variables: {
first: 3,
},
})
})Notice how we can use the graphql directive inside the event handler, this is possible because in
the standard module configuration all .gql, .graphql, .ts, .js and .vue files are automatically
processed for the storefront API, as long as they don't match the admin patterns (e.g. .admin.ts) or the
customer account patterns (e.g. .customer-account.ts, .customer.ts, .account.ts).
Read more about the codegen configuration.
Now we can call the API at /api/products to obtain the first three products:
<!-- app/pages/your-page.vue -->
<script setup lang="ts">
const { data } = await useFetch("/api/products")
</script>
<template>
<pre>{{ data }}</pre>
</template>The data variable will be typed as Ref<ClientResponse<FetchProductsQuery>>, which enables autocompletion and full
type checking.
You can use the useCustomerAccount utility to access the customer account API in a nitro event handler:
// server/api/customer.ts
export default defineEventHandler(async (event) => {
const customerAccount = useCustomerAccount(event)
return await customerAccount.request(`#graphql
query FetchCustomer {
customer {
firstName
lastName
}
}
`)
})Files in an admin directory, or ending with .admin.ts or .admin.gql, will automatically be processed for the admin API.
We can use the useAdmin utility to access the admin API in a nitro event handler:
// server/api/admin/orders.ts
export default defineEventHandler(async (event) => {
const admin = useAdmin(event)
return await admin.request(...)
})For a full example, see Admin API examples.
To mock the Storefront API, you can use the mock option in the module config:
export default defineNuxtConfig({
shopify: {
name: "my-mocked-shopify-store",
clients: {
storefront: {
mock: true,
apiVersion: "2026-10",
},
},
},
})All requests to the Storefront API will now return data from mock.shop instead of hitting the actual Shopify API.
By default, Storefront API requests from the client side are sent through Hydrogen's Storefront API proxy on your own domain.
To send them to Shopify directly, set the proxy option to false in the module config.
export default defineNuxtConfig({
shopify: {
clients: {
storefront: {
proxy: false, // default: true
},
},
},
})Once installed, the module automatically generates your GraphQL types and saves them in:
- .nuxt/shopify/ โ Type definitions
- .nuxt/shopify/schema โ GraphQL schema files
For IDE support, the module automatically generates a GraphQL config file at .nuxt/graphql.config.mjs,
with a project per configured client. Point your editor's GraphQL plugin at it, or reference it from a root config file:
// graphql.config.mjs
export { default } from "./.nuxt/graphql.config.mjs"You can disable the config file generation by setting graphql.generateConfig to false in the module config.
You can define reusable fragments in your GraphQL queries to avoid duplication and make your queries more maintainable. The module supports fragment usage out of the box.
Here's an example of how to define and use a fragment:
// graphql/fragments/product.ts
export const productFields = `#graphql
fragment ProductFields on Product {
id
title
description
}
`<!-- app/pages/products.vue -->
<script setup lang="ts">
const storefront = useStorefront()
const products = await storefront.request(`#graphql
query FetchProducts($first: Int) {
products(first: $first) {
nodes {
...ProductFields
}
}
}
`, {
variables: {
first: 5,
},
})
</script>The ProductFields fragment is automatically injected into the query, so you don't need to import it explicitly in your request.
You can also export a query from a .ts file and import it where you send the request.
Files placed in the graphql directory in your project root will be automatically imported by the module, it is recommended to organize your fragments there. The path is resolved from the project root, so on Nuxt 4 it is graphql/, not app/graphql/.
To scan other directories, set them in the fragments.dirs option.
Fragments outside of these directories are not injected, so define them in the operation itself or add them with string interpolation, such as ${productFields}.
By default, the module will throw an error if a client encounters an error instead of returning the errors object in the response. This is done so that Nuxt can take over the error handling.
You can customize this behavior by setting the errors.throw option in the module config.
export default defineNuxtConfig({
shopify: {
errors: {
throw: false,
},
},
})This will prevent the module from throwing an error and instead return the error response.
The module also provides hooks to handle errors.
// server/plugins/your-plugin.ts
export default defineNitroPlugin((nitroApp) => {
nitroApp.hooks.hook("shopify:storefront:client:errors", ({ errors }) => {
// Do something with the errors
console.log("Storefront client errors:", errors)
})
})Read more about all available hooks in our hooks documentation.
The module provides caching for both client and server-side Storefront API requests.
Caching is set up by default and can be configured in the module options.
For each request, caching is opt-in by setting the cache option in the request options.
<!-- app/pages/products.vue -->
<script setup lang="ts">
const storefront = useStorefront()
const { data } = await storefront.request(`#graphql
query FetchProducts($first: Int) {
products(first: $first) {
nodes {
...ProductFields
}
}
}
`, {
variables: {
first: 5,
},
// Cache settings for this request, in the browser and during server rendering
cache: "short",
// Or set the browser and server cache separately:
// cache: { browser: "short", server: "long" },
})
</script>This also applies to the useStorefrontData composable.
On the server side you can use nitro's built-in caching utilities within your API routes or plugins to cache requests to both the storefront and admin API.
See the caching documentation for more details and examples.
The module can send Shopify headless analytics, powering the reports and live view in your admin.
Enable the analytics option to load Shopify's scripts from @shopify/hydrogen, which send the events to Shopify.
Then report views with the view components, or publish events with the useShopifyAnalytics composable:
<!-- app/pages/product.vue -->
<template>
<ShopifyProductView
:data="{
products: [{
id: product.id,
title: product.title,
vendor: product.vendor,
price: variant.price,
variantId: variant.id,
variantTitle: variant.title,
quantity: 1,
}],
}"
/>
</template>To send the events to other tools, add them as destinations of Shopify's analytics bus once Shopify's scripts are running:
// app/plugins/ga.client.ts
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.hook("shopify:analytics:ready", () => {
useShopifyAnalytics()?.addDestination({
name: "ga4",
setup: ({ subscribe }) => subscribe("product_added_to_cart", (payload) => {
// e.g. forward to GA4 or Meta
}),
})
})
})For cart events, call useCartAnalytics() from @shopify/hydrogen/vue inside your CartProvider.
Events are only sent if Shopify's Customer Privacy API allows it, so no events are sent without consent in regions that require it.
See the analytics documentation for view components, destinations, and consent configuration.
To subscribe or unsubscribe a webhook, you can either do so manually within the Shopify Admin UI or via Shopify's CLI. The module also introduces a CLI command to easily add Webhooks from your local dev environment.
First, configure your webhooks:
export default defineNuxtConfig({
modules: ["@nuxtjs/shopify"],
shopify: {
webhooks: {
secret: "my-shopify-app-client-secret",
subscriptions: [
{
topic: "ORDERS_CREATE",
uri: "https://your-app.com/api/webhooks/orders-create",
},
],
},
},
})Then subscribe with the CLI command:
npx @nuxtjs/shopify webhooks subscribeTo receive webhooks with Shopify's HMAC validation the module introduces defineWebhookEventHandler, which automatically
validates any incoming request against the app client secret.
Read more about webhooks in our webhooks documentation.
- Clone this repository
- Create a
.envfile (see.env.example) - Install dependencies using:
pnpm install
- Run
pnpm run prepare:devto generate type stubs. - Start the default playground with:
pnpm run dev
Published under the MIT License.
