Nuxt Shopify

Essentials

Module Config

Configure the Nuxt Shopify module

The Nuxt Shopify module can be configured via the shopify property in your nuxt.config.ts file.

Quickstart

Minimal configuration to get started:

nuxt.config.ts
export default defineNuxtConfig({
  modules: ["@nuxtjs/shopify"],

  shopify: {
    name: "quickstart-abcd1234",
    clients: {
      storefront: {
        apiVersion: "2026-01",
        publicAccessToken: "YOUR_ACCESS_TOKEN",
      },
      customerAccount: {
        apiVersion: "2026-01",
        clientId: "YOUR_CLIENT_ID",
      },
      admin: {
        apiVersion: "2026-01",
        clientId: "YOUR_ADMIN_CLIENT_ID",
        clientSecret: "YOUR_ADMIN_CLIENT_SECRET",
      },
    },
  },
})
See the Shopify Setup Guide to learn how to find your store name and access tokens.

Configuration Examples

Choose the configuration that matches your use case:

nuxt.config.ts
export default defineNuxtConfig({
  shopify: {
    name: "quickstart-abcd1234",
    clients: {
      storefront: {
        apiVersion: "2026-01",
        publicAccessToken: "YOUR_ACCESS_TOKEN",
      },
    },
  },
})

Full Configuration Reference

Basic Options

name
string required
Your Shopify store name (e.g., quickstart-abcd1234).
logger
object
Optional module logger configuration (Consola options)

Client Configuration

Configure one or more API clients:

Storefront Client

apiVersion
string
Shopify API version to use (e.g., 2026-01) - default: the current stable API version
publicAccessToken
string
Public access token for client-side requests
privateAccessToken
string
Private access token for server-side requests
mock
boolean
Use mock.shop instead of your actual store - default: false
proxy
boolean | object
Proxy all client-side requests through Nitro. Use true for default path or provide custom path - default: true
sandbox
boolean
Enable GraphiQL sandbox for the client - default: true
autoImport
boolean
Auto-import generated types for this client - default: true
codegen.skip
boolean
Skip code generation for the client - default: false
codegen.pluginOptions.typescript
object
Custom TypeScript plugin options for code generation
cache
object | boolean
Default cache configuration for the client
cache.client
object | boolean
Cache configuration for client-side requests - default: in-memory LRU cache with 10 second TTL
cache.proxy
object | string | boolean
Cache configuration for proxied requests - default: lru-cache driver
cache.options
object
Named cache options to use in your application (e.g., short, long) - default: short (10 second TTL) and long (1 day TTL)
headers
object
Additional headers to include in requests
documents
array
Glob patterns to include in code generation. Setting this replaces the default glob patterns for the client
retries
number
Number of retries for failed requests - default: 0

Customer Account Client

apiVersion
string
Shopify API version to use (e.g., 2026-01) - default: the current stable API version
clientId
string required
Client ID for customer account API requests
apiUrl
string
Customer Account API endpoint. Resolved automatically at build time, set this to override.
clientSecret
string
Client secret for confidential clients. When set, the OAuth token exchange is authenticated with the secret instead of PKCE - server-side only, optional
scope
array
OAuth scopes to request during authentication - default: ['openid', 'email', 'customer-account-api:full']
loginURL
string
Login URL for customer account API authentication - default: /_auth/customer-account/callback
logoutURL
string
Logout URL for customer account API authentication - default: /_auth/customer-account/logout
sessionURL
string
Endpoint that exposes the current session to the client - default: /_auth/customer-account/session
redirectURL
string
Redirect URL to navigate to after successful customer account API authentication - default: /
logoutRedirectURL
string
Redirect URL to navigate to after logout. Must be a registered logout URI in your Shopify app - default: the value of redirectURL
session.password
string
Password used to encrypt the session cookie (at least 32 characters). Auto-generated in development, required in production - server-side only
session.name
string
Name of the session cookie - default: shopify-customer-account
session.maxAge
number
Lifetime of the session cookie in seconds - default: 604800 (7 days)
tokenStorage
string | object | boolean
Where the customer's tokens are kept. By default they live in a sealed session cookie, which is stateless and works on serverless hosts. Set an unstorage mount or driver (e.g. Redis) to store them server-side instead, or true for the in-memory driver (single-instance only) - default: false (client-side cookie fallback)
dev.tunnelURL
string
Tunnel URL for local development with ngrok or similar - optional
dev.bridgeURL
string
Bridge URL for local development with ngrok or similar - default: /_auth/customer-account/bridge
proxy
boolean | object
Proxy all client-side requests through Nitro. Use true for default path or provide custom path - default: true
sandbox
boolean
Enable GraphiQL sandbox for the client - default: true
autoImport
boolean
Auto-import generated types for this client - default: false (only the storefront client auto-imports by default)
codegen.skip
boolean
Skip code generation for the client - default: false
codegen.pluginOptions.typescript
object
Custom TypeScript plugin options for code generation
headers
object
Additional headers to include in requests
documents
array
Glob patterns to include in code generation. Setting this replaces the default glob patterns for the client
retries
number
Number of retries for failed requests - default: 0

Admin Client

apiVersion
string
Shopify API version to use (e.g., 2026-01) - default: the current stable API version
clientId
string
Admin API client ID
clientSecret
string
Admin API client secret
accessToken
string
Access token for admin API requests
refreshToken
string
Refresh token for admin API requests
tokenStorage
object | string | false
Unstorage mount name or configuration object - default: in-memory storage
sandbox
boolean
Enable GraphiQL sandbox for the client - default: true
autoImport
boolean
Auto-import generated types for this client - default: false (admin only enabled when explicitly set)
codegen.skip
boolean
Skip code generation for the client - default: false
codegen.pluginOptions.typescript
object
Custom TypeScript plugin options for code generation
headers
object
Additional headers to include in requests
documents
array
Glob patterns to include in code generation. Setting this replaces the default glob patterns for the client
retries
number
Number of retries for failed requests - default: 0

Fragments

fragments.paths
array
Paths to GraphQL fragments directories - default: ['/graphql']
fragments.autoImport
boolean
Auto-import from fragments directory - default: true

GraphQL

graphql.generateConfig
boolean
Generate a graphql.config.mjs for IDE features like autocompletion and validation - default: true

Error Handling

errors.throw
boolean
API clients throw errors instead of returning them in the errors object in the response - default: true

Webhooks

webhooks.secret
string
Your Shopify App Client Secret. Used for HMAC validation.
webhooks.hooks
array
An array of webhooks to subscribe to.

Complete Example

Full configuration example with all options:

nuxt.config.ts
export default defineNuxtConfig({
  modules: ["@nuxtjs/shopify"],

  shopify: {
    name: "quickstart-abcd1234",

    clients: {
      storefront: {
        apiVersion: "2026-01",
        publicAccessToken: "YOUR_PUBLIC_ACCESS_TOKEN",
        privateAccessToken: "YOUR_PRIVATE_ACCESS_TOKEN",
        mock: false,
        proxy: {
          path: "/_proxy/storefront",
        },
        sandbox: true,
        autoImport: true,
        codegen: {
          skip: false,
          pluginOptions: {
            typescript: {},
          },
        },
        cache: {
          client: {
            ttl: 1000 * 10,
          },
          proxy: {
            driver: "lru-cache",
          },
          options: {
            short: { maxAge: 1, staleMaxAge: 9, swr: true },
            long: { maxAge: 3600, staleMaxAge: 82800, swr: true },
          },
        },
        headers: {},
        documents: [],
        retries: 0,
      },

      customerAccount: {
        apiVersion: "2026-01",
        clientId: "YOUR_CLIENT_ID",
        clientSecret: "YOUR_CLIENT_SECRET",
        scope: ["openid", "email", "customer-account-api:full"],
        loginURL: "/_auth/customer-account/callback",
        logoutURL: "/_auth/customer-account/logout",
        sessionURL: "/_auth/customer-account/session",
        redirectURL: "/",
        logoutRedirectURL: "/",
        session: {
          name: "shopify-customer-account",
          password: "YOUR_SESSION_PASSWORD_AT_LEAST_32_CHARACTERS",
          maxAge: 604800,
        },
        tokenStorage: false,
        dev: {
          tunnelURL: "https://your-tunnel-url.ngrok-free.app",
          bridgeURL: "http://localhost:3000/_auth/customer-account/bridge",
        },
        proxy: {
          path: "/_proxy/customer-account",
        },
        sandbox: true,
        autoImport: true,
        codegen: {
          skip: false,
          pluginOptions: {
            typescript: {},
          },
        },
        headers: {},
        documents: [],
        retries: 0,
      },

      admin: {
        apiVersion: "2026-01",
        clientId: "YOUR_ADMIN_CLIENT_ID",
        clientSecret: "YOUR_ADMIN_CLIENT_SECRET",
        accessToken: "YOUR_ADMIN_ACCESS_TOKEN",
        refreshToken: "YOUR_ADMIN_REFRESH_TOKEN",
        tokenStorage: {
          driver: "memory" 
        },
        sandbox: true,
        autoImport: false,
        codegen: {
          skip: false,
          pluginOptions: {
            typescript: {},
          },
        },
        headers: {},
        documents: [],
        retries: 0,
      },
    },

    logger: {},

    fragments: {
      paths: ["/graphql"],
      autoImport: true,
    },

    graphql: {
      generateConfig: true,
    },

    errors: {
      throw: true,
    },

    webhooks: {
      secret: "YOUR_SHOPIFY_CLIENT_SECRET",
      hooks: [
        {
          topic: "ORDERS_CREATE",
          uri: "https://your-app.com/api/webhooks/orders-create",
          format: "JSON",
          filter: "",
          includeFields: ["id", "title"],
          metafieldNamespaces: [],
          metafields: [],
        },
      ],
    },

    analytics: {
      domain: "your-store.com",
      shopId: "YOUR_SHOP_ID",
      storefrontId: "YOUR_STOREFRONT_ID",
      language: "EN",
      currency: "EUR",
      consent: {
        checkoutDomain: "checkout.your-store.com",
        storefrontAccessToken: "YOUR_PUBLIC_ACCESS_TOKEN",
        withPrivacyBanner: false,
        country: "DE",
        language: "EN",
      },
    },
  },
})

Setup Shopify

How to setup your Shopify shop to use with Nuxt Shopify

Storefront API

Using the Shopify Storefront API in Nuxt

Copyright © 2026