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.

Environment variables

Any option can be supplied through the environment instead of being written into nuxt.config.ts, which is how you keep tokens out of the repository. Nuxt only maps an environment variable onto a config key that already exists, so declare the key under runtimeConfig.shopify first:

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

  shopify: {
    name: "nuxt-module-store",

    clients: {
      storefront: {
        apiVersion: "...",
        publicAccessToken: "...",
      },
    },
  },
})
.env
NUXT_SHOPIFY_NAME="nuxt-module-store"
NUXT_SHOPIFY_CLIENTS_STOREFRONT_API_VERSION="2026-04"
NUXT_SHOPIFY_CLIENTS_STOREFRONT_PUBLIC_ACCESS_TOKEN="..."

Precedence, highest first: runtimeConfig.public.shopify, then runtimeConfig.shopify, then the shopify block in nuxt.config.ts.

Resolved config

The module parses and resolves your configuration on startup and writes the result back to the runtime config. You can read it from _shopify, the shopify object contains the raw config input.

  • useRuntimeConfig()._shopify: Full resolved config on the server, typed as ShopifyConfig. It carries credentials, so it must never reach the browser.
  • useRuntimeConfig().public._shopify: Filtered copy that is safe in the browser, typed as PublicShopifyConfig.
  • useRuntimeConfig().shopify: Raw config input, unresolved.

Quickstart

Minimal configuration to get started:

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

  shopify: {
    name: "nuxt-module-store",
    clients: {
      storefront: {
        apiVersion: "2026-04",
        publicAccessToken: "...",
      },

      customerAccount: {
        apiVersion: "2026-04",
        clientId: "...",
      },

      admin: {
        apiVersion: "2026-04",
        clientId: "...",
        clientSecret: "...",
      },
    },
  },
})
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: "nuxt-module-store",
    clients: {
      storefront: {
        apiVersion: "2026-04",
        publicAccessToken: "...",
      },
    },
  },
})

Full Configuration Reference

Basic Options

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

Client Configuration

Configure one or more API clients:

API versions

Shopify ships a new API version every quarter and supports each one for at least a year. Every client takes an apiVersion, and leaving it unset means the module picks whichever version is current at build time, so an unchanged codebase can move to a new API version when being rebuilt in a new quarter. Pin apiVersion per client if you want that upgrade to be a deliberate change:

nuxt.config.ts
export default defineNuxtConfig({
  shopify: {
    name: 'nuxt-module-store',

    clients: {
      storefront: {
        apiVersion: '2026-04',
        publicAccessToken: '...',
      },
    },
  },
})

Storefront Client

apiVersion
string
Shopify API version to use (e.g., 2026-04) - 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 the default route or provide { route } - default: true
explorer
boolean
Enable the dev-only GraphQL explorer for the client - default: true
codegen
object | boolean
Code generation for the client. Set to false to disable it - default: true
codegen.autoImport
boolean
Declare this client's operation and fragment types globally - default: true
codegen.plugins.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.presets
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. Part of the public runtime config, never add credentials here.
documents
array
Glob patterns to include in code generation. Setting this replaces the default glob patterns for the client. An empty array falls back to the defaults.
retries
number
Number of retries for failed requests, between 0 and 3 - default: 0

Customer Account Client

apiVersion
string
Shopify API version to use (e.g., 2026-04) - 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']
routes.callback
string
Route mounted on your app that runs the OAuth flow. Visiting it without an authorization code starts the flow. Shopify redirects back to the same route to complete it, so this path must be registered as a callback URI in your Shopify app - default: /_auth/customer-account/callback
routes.logout
string
Route mounted on your app that performs the OpenID Connect logout - default: /_auth/customer-account/logout
routes.session
string
Route mounted on your app that exposes the current session to the client - default: /_auth/customer-account/session
afterLogin
string
Where to send the customer once login succeeds. Not to be confused with the OAuth redirect_uri, which is routes.callback - default: /
afterLogout
string
Where to send the customer after logout. Must be a registered logout URI in your Shopify app - default: the value of afterLogin
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)
session.cookie
object
Overrides for the session cookie attributes. httpOnly is always enforced
session.cookie.domain
string
Domain the session cookie is scoped to - default: the request host
session.cookie.path
string
Path the session cookie is scoped to - default: /
session.cookie.sameSite
'lax' | 'strict' | 'none'
SameSite attribute of the session cookie - default: lax. Setting none allows other sites to send authenticated requests to the customer account proxy, so only use it if you need cross-site embedding
session.cookie.secure
boolean
Secure attribute of the session cookie - default: true outside of development
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 the default route or provide { route } - default: true
explorer
boolean
Enable the dev-only GraphQL explorer for the client - default: true
codegen
object | boolean
Code generation for the client. Set to false to disable it - default: true
codegen.autoImport
boolean
Declare this client's operation and fragment types globally - default: false
codegen.plugins.typescript
object
Custom TypeScript plugin options for code generation
headers
object
Additional headers to include in requests. Part of the public runtime config, never add credentials here.
documents
array
Glob patterns to include in code generation. Setting this replaces the default glob patterns for the client. An empty array falls back to the defaults.
retries
number
Number of retries for failed requests, between 0 and 3 - default: 0

Admin Client

apiVersion
string
Shopify API version to use (e.g., 2026-04) - 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
explorer
boolean
Enable the dev-only GraphQL explorer for the client - default: true
codegen
object | boolean
Code generation for the client. Set to false to disable it - default: true
codegen.autoImport
boolean
Declare this client's operation and fragment types globally - default: false
codegen.plugins.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. An empty array falls back to the defaults.
retries
number
Number of retries for failed requests, between 0 and 3 - default: 0

Fragments

fragments.dirs
array
Directories holding your GraphQL fragments, relative to the project root - default: ['graphql']
fragments.autoImport
boolean
Auto-import from the fragments directories - default: true

GraphQL

graphql.generateConfig
boolean
Generate a graphql.config.mjs for IDE features like autocompletion and validation - default: true
graphql.injectFragments
boolean
Inject every fragment an operation references into that operation at build time, so they don't have to be imported by hand - default: true
graphql.normalize
boolean
Strip duplicate and unused fragment definitions from an operation before it is sent to Shopify - 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.

Analytics

Set analytics to true to enable Shopify analytics with the defaults, or to an object to configure it. All options are optional - default: false

analytics.storefrontId
string
Storefront ID from your Headless or Hydrogen sales channel, used to attribute events to a specific storefront
analytics.domain
string
Domain events are sent from - default: <name>.myshopify.com
analytics.shopId
string
Shop ID as gid://shopify/Shop/<id>. Resolved from the Storefront API when omitted
analytics.currency
string
Currency code of the default market (e.g. USD). Resolved from the Storefront API when omitted
analytics.language
string
Language code of the default market (e.g. EN). Resolved from the Storefront API when omitted
analytics.autoPageView
boolean
Report a page_viewed event on the initial load and on every client-side navigation - default: true
analytics.consent.checkoutDomain
string
Checkout domain used by the Customer Privacy API - default: the store domain
analytics.consent.storefrontAccessToken
string
Public token used by the consent API - default: the storefront client's publicAccessToken
analytics.consent.banner
boolean | object
Load Shopify's own cookie banner. Accepts banner.country and banner.language - default: false

Complete Example

Full configuration example with all options:

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

  shopify: {
    name: "nuxt-module-store",

    clients: {
      storefront: {
        apiVersion: "2026-04",
        publicAccessToken: "...",
        privateAccessToken: "...",
        mock: false,
        proxy: {
          route: "/_proxy/storefront",
        },
        explorer: true,
        codegen: {
          plugins: {
            typescript: {},
          },
        },
        cache: {
          client: {
            ttl: 1000 * 10,
          },
          proxy: {
            driver: "lru-cache",
          },
          presets: {
            short: { maxAge: 1, staleMaxAge: 9, swr: true },
            long: { maxAge: 3600, staleMaxAge: 82800, swr: true },
          },
        },
        headers: {},
        retries: 0,
      },

      customerAccount: {
        apiVersion: "2026-04",
        clientId: "...",
        clientSecret: "...",
        apiURL: "https://shopify.com/.../account/customer/api/2026-04/graphql",
        scope: ["openid", "email", "customer-account-api:full"],
        routes: {
          callback: "/_auth/customer-account/callback",
          logout: "/_auth/customer-account/logout",
          session: "/_auth/customer-account/session",
        },
        afterLogin: "/",
        afterLogout: "/",
        session: {
          name: "shopify-customer-account",
          password: "...",
          maxAge: 604800,
          cookie: {
            path: "/",
            sameSite: "lax",
            secure: true,
          },
        },
        tokenStorage: false,
        dev: {
          tunnelURL: "https://your-tunnel-url.ngrok-free.app",
          bridgeURL: "http://localhost:3000/_auth/customer-account/bridge",
        },
        proxy: {
          route: "/_proxy/customer-account",
        },
        explorer: true,
        codegen: {
          plugins: {
            typescript: {},
          },
        },
        headers: {},
        retries: 0,
      },

      admin: {
        apiVersion: "2026-04",
        clientId: "...",
        clientSecret: "...",
        accessToken: "...",
        refreshToken: "...",
        tokenStorage: {
          driver: "memory" 
        },
        explorer: true,
        codegen: {
          plugins: {
            typescript: {},
          },
        },
        headers: {},
        retries: 0,
      },
    },

    logger: {},

    fragments: {
      dirs: ["graphql"],
    },

    graphql: {
      generateConfig: true,
      injectFragments: true,
      normalize: true,
    },

    errors: {
      throw: true,
    },

    webhooks: {
      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: "...",
      storefrontId: "...",
      language: "EN",
      currency: "EUR",
      consent: {
        checkoutDomain: "checkout.your-store.com",
        storefrontAccessToken: "...",
        banner: {
          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

Published under the MIT License