Migrating to 2.0
Version 2 of the module is built on @shopify/hydrogen 2026.10.
The module now adds Hydrogen's storefront routes, uses Hydrogen's customer accounts for the login and loads Shopify's own scripts for analytics.
The GraphQL clients, code generation, the explorer and webhooks work as before, apart from the renames below.
When Nuxt starts, the module shows a warning for each option it no longer supports, and nuxt typecheck reports renamed hooks and removed types.
Not every change shows up this way, so go through each section of this guide.
Requirements
- Nuxt 4 or newer is required. Nuxt 3 is no longer supported. On Nuxt 3, Nuxt disables the module with a warning, so stay on version 1 until you upgrade Nuxt.
@shopify/hydrogen2026.10.3 or newer is required. In version 1, only customer accounts needed it. It is now a required peer dependency, also for the storefront and admin clients. Install it in your own dependencies, because your app also imports from it, for example for the cart. npm doesn't install the module next to an older version of Hydrogen, so upgrade Hydrogen first.@shopify/hydrogen-reactis no longer used. Analytics in version 1 was built on it. You can remove it, unless your own code uses it.
Routes
When the storefront client is configured or analytics is enabled, the module adds Hydrogen's storefront routes. They are matched before your own routes and pages, so move any of your routes that use one of these paths:
| Path | Description |
|---|---|
/api/<version>/graphql.json | The Storefront API proxy, replaces /_proxy/storefront |
/api/cart | The cart API |
GET /api/predictive-search | The predictive search API |
/checkout | Redirects to the checkout of the visitor's cart |
/cart/<variant>:<quantity>, /buy/<item>:<quantity> | Cart and buy permalinks |
/cart.js, /cart/add, /cart/update, /cart/change, /cart/clear | The AJAX cart API used by Shopify's scripts, also with .js or .json and behind a locale prefix |
POST /__shopify/api/collect | Shopify's performance beacon |
/.well-known/ucp, /api/mcp, /api/ucp/mcp | Your store's UCP business profile and the MCP endpoints for AI agents |
/.well-known/apple-developer-merchantid-domain-association | The domain verification for Apple Pay |
/.well-known/shopify/fec/produce | Shopify's event collector |
When the customer account client is configured, the module adds these routes:
| Path | Description |
|---|---|
/account/login, /account/authorize, /account/refresh, POST /account/logout | The login and logout, replace /_auth/customer-account/callback, /_auth/customer-account/logout and the dev bridge |
GET /account/session | The session for useCustomerAccountSession, replaces /_auth/customer-account/session |
POST /account/customer/api/<version>/graphql | The customer account proxy, replaces /_proxy/customer-account |
If your CDN, firewall or monitoring rules use the old paths, update them.
The module also redirects ?variant=<id> links to the selected options of the variant, and checks for a redirect when a page is not found during server-side rendering, see variant links and redirects.
If you only use the storefront client to send your own queries, as in version 1, set routes: false on it to leave out the storefront routes, Shopify's scripts and the redirects, see without the routes.
The routes are always served from the root of your domain.
The browser clients no longer add app.baseURL to the proxy paths, and the storefront client, the customer account client and analytics don't support an app.baseURL other than /.
The module shows a warning when Nuxt starts if you set one.
On statically generated sites, built with nuxt generate or a static preset such as github_pages, the proxies are disabled, because there is no server for them.
In development, the URL of the admin explorer now contains a token that changes every time the dev server starts. Open it from the link in the output of the dev server, see GraphQL explorer.
Configuration
Options with a new format, such as proxy: { route }, are invalid.
nuxt dev and nuxt prepare log the error and set up the module without that feature, and nuxt build fails.
Removed and renamed options are ignored, with a warning for each of them.
Shop and market
The shop options moved from analytics to the top level, and the language and currency to the new i18n option, because the routes, the login and Shopify's scripts also use them without analytics:
| 1.x | 2.0 |
|---|---|
analytics.shopId | shopId, only the number (e.g. 12345) |
analytics.storefrontId | storefrontId |
analytics.language, analytics.currency | i18n: { defaultLocale: { country, language, currency } }, with the new and required country |
NUXT_SHOPIFY_ANALYTICS_SHOP_ID | NUXT_SHOPIFY_SHOP_ID |
NUXT_SHOPIFY_ANALYTICS_STOREFRONT_ID | NUXT_SHOPIFY_STOREFRONT_ID |
NUXT_SHOPIFY_ANALYTICS_LANGUAGE, NUXT_SHOPIFY_ANALYTICS_CURRENCY | NUXT_SHOPIFY_I18N_DEFAULT_LOCALE_COUNTRY, _LANGUAGE and _CURRENCY |
i18n.defaultLocale is the locale of requests whose URL has no other locale.
To serve several markets, add their locales to i18n.routing.
The module's routes, the login and Shopify's scripts use it.
It doesn't localize your own queries, so keep their @inContext variables.
Without i18n, the module fetches your shop's default market with the storefront client, so you need to set i18n.defaultLocale if you only use the customer account client or analytics.
API versions
By default, the clients now use the API version of the installed @shopify/hydrogen, such as 2026-10 for Hydrogen 2026.10, instead of the API version of the current date.
This way, the API version only changes when you upgrade Hydrogen, not when you rebuild your app.
Documents
Patterns in documents that start with ! now work the same for code generation, fragment injection, the regeneration during development and the generated graphql.config.mjs.
They follow the rules of codegen, so !legacy only excludes the legacy folder in your project root.
Before, fragment injection excluded every legacy folder.
To exclude every legacy folder, use !**/legacy/**.
The module now finds the files of your patterns with Node's built-in glob, which reads some patterns differently than version 1:
- A
!pattern that matches a folder excludes everything in it, so!legacy/*now also excludeslegacy/old/. - Square brackets only match one character.
pages/[handle].vuematchespages/h.vue, but no longer your[handle].vuepage, so usepages/*.vueinstead. !patterns no longer apply inside folders whose name starts with a dot, such as.storybook/, unless they name the folder, as in!.storybook/**/*.admin.ts.- Folders that are symlinks are no longer searched.
Route groups such as pages/(account)/ no longer count as customer account or admin folders for fragment injection and in your editor, the same as in codegen.
node_modules, dist, .nuxt and .output folders and .d.ts files are now always skipped, also when you set your own documents.
Storefront client
| 1.x | 2.0 |
|---|---|
proxy: { route } | proxy: true or false, always at /api/<version>/graphql.json |
cache.proxy | cache.server, for requests during server-side rendering |
cache.client | cache.browser |
cache.client takes the options of lru-cache, with ttl in milliseconds | cache.browser takes max, maxSize, maxEntrySize and ttl, now in seconds |
storage mount storefront-proxy | storefront-cache |
codegen.autoImport (every client) | codegen.globalTypes |
preset staleMaxAge | staleWhileRevalidate |
preset swr | removed, staleWhileRevalidate sets how long a stale response is served |
The cache option of a request changed the same way, from cache: { client, proxy } to cache: { browser, server }, and the ttl of cache: { browser: { ttl } } is now in seconds.
The ttl of a cache.server or tokenStorage with the lru-cache driver is also in seconds now.
nuxt typecheck reports the old keys, but not in useStorefrontData() if only one of them is renamed, such as cache: { client, server }.
At runtime, a leftover client key is ignored without a warning, and the request isn't cached in the browser, so search your code for it:
useStorefrontData('products', query, {
- cache: { client: 'short', proxy: 'long' },
+ cache: { browser: 'short', server: 'long' },
})
With proxy: false, only the browser client sends its requests directly to Shopify.
The module's routes are added either way.
cache.server no longer caches requests from the browser in the proxy.
Instead, it caches the requests of your pages during server-side rendering.
These responses are shared by all visitors, so never use a server-side preset for a query with personalized data, see caching.
Customer account client
| 1.x | 2.0 |
|---|---|
clientSecret | removed, the login only needs the clientId |
scope | removed |
routes, dev.tunnelURL, dev.bridgeURL | removed, the routes are always at /account/* and there is no dev bridge |
apiURL | removed, the API URL is built from the top-level shopId |
proxy: { route } | proxy: true or false, always at /account/customer/api/<version>/graphql |
afterLogout defaults to afterLogin | afterLogout defaults to /, as in Hydrogen |
tokenStorage: true without a limit | tokenStorage: true keeps up to 10,000 sessions in memory, on a single server |
session cookie shopify-customer-account | __Host-session, as in Hydrogen's template |
session.cookie.domain, .path, .secure | removed, the session cookie is always Secure and set for / on your own domain, also in development |
session.cookie.sameSite: 'strict' | not supported, because the login fails with it, use lax (the default) or none |
The session password must be a random secret with at least 32 characters.
The placeholder from the old .env.example is rejected, and in development, the module replaces it in your .env with a generated password.
A production build no longer includes the password from NUXT_SHOPIFY_CLIENTS_CUSTOMER_ACCOUNT_SESSION_PASSWORD, so set the variable where your app runs, not only where it is built.
Otherwise, for example with a prebuilt or Docker deployment, customers can't log in.
Analytics options
| 1.x | 2.0 |
|---|---|
consent.banner: true | consent.mode: 'default-banner' |
consent.banner: { country, language } | consent.mode: 'default-banner', the banner uses the locale of the request |
consent.banner: false (default) | consent.mode: 'no-banner' (default), or 'custom-banner' for your own banner or consent provider |
domain, consent.checkoutDomain, consent.storefrontAccessToken | removed |
Without the storefront client, the module can't fetch your shop, so set the top-level shopId and an i18n.defaultLocale with a currency.
The module shows a warning when Nuxt starts if shopId or the default locale is missing.
Customer accounts
- Update your Shopify settings. In the Customer Account API settings, set the callback URI to
https://<your-domain>/account/authorize, the JavaScript origin tohttps://<your-domain>and the logout URI tohttps://<your-domain>. - No dev bridge and no
localhost. Shopify only accepts HTTPS URLs that aren't onlocalhost, so the login doesn't work onhttp://localhostorhttps://localhost. Use thelocalHttpsVite plugin from@shopify/hydrogen/viteinstead. You only need a tunnel to log in from another device, see local development. - Logout is a
POSTrequest.logout()submits a form to/account/logoutand only works in the browser. Replace logout links and logout pages with a button that callslogout(), or with a form, see the session composable. - Login links go to
/account/logininstead of/_auth/customer-account/callback. The country of Shopify's login page now comes from the locale of the request, sologin({ countryCode })and theregion_countryparameter are removed. useCustomerAccountSession()returnsisLoggedIn,isReady,fetch,loginandlogout.readyis renamed toisReady, anduserandloggedInAtare removed. To load the customer, use a Customer Account API query.- Server helpers.
getCustomerAccountSession(event),requireCustomerAccountSession(event)and the session route return{ isLoggedIn }instead of{ loggedIn, user, loggedInAt }. Code that readsloggedIngetsundefinedwithout an error, so rename it. To load the customer, useuseCustomerAccount(event). - Hooks.
shopify:customer-account:auth:success,:refresh,:logoutand:erroronly receive{ event }.successruns after the session is stored, so it can no longer stop a login.logoutruns after the session is cleared, and only when a logged in customer logs out. Insuccessandrefresh, you can load the customer withuseCustomerAccount(event).customer-account:auth:authorizeis removed, passlocale,loginHint,loginHintMode,acrValuesorreturnTotologin()instead. - Cached pages are rendered without the customer. Pages with a
cache,swrorisrroute rule never read the session, so they are rendered for a visitor who is not logged in, anduseCustomerAccount()fails with a401error while rendering them.useCustomerAccountSession()reads the session in the browser after hydration. Exclude your account pages from catch-all rules:nuxt.config.tsexport default defineNuxtConfig({ routeRules: { '/**': { swr: 60 }, '/account/**': { cache: false, isr: false }, }, }) - All customers are logged out once after the upgrade, because the session format and the cookie name changed.
- The customer account proxy only accepts
POSTrequests with a JSON body from your own domain. - Types.
CustomerAccountUser,CustomerAccountTokenSet,CustomerAccountTokensandOpenIdConfigurationare removed.CustomerAccountSessionis renamed toShopifyCustomerAccountSession, which is{ isLoggedIn }.CustomerAccountSessionDatais no longer exported.
Analytics
Analytics now uses the same scripts as Shopify's own storefronts: Shopify's analytics bus, the Customer Privacy API and Shopify's privacy banner.
useShopifyAnalytics() returns Shopify's analytics bus.
On the server and before Shopify's scripts have loaded, it returns null, so call it in browser code:
| 1.x | 2.0 |
|---|---|
publish(event, payload) | useShopifyAnalytics()?.publish(event, payload), only for Shopify's standard events |
subscribe(event, callback) | useShopifyAnalytics()?.addDestination({ name, setup }) in the shopify:analytics:ready hook |
setTrackingConsent(consent) | window.Shopify.customerPrivacy.setTrackingConsent(consent) |
canTrack() | window.Shopify.customerPrivacy.analyticsProcessingAllowed() |
showPreferences() | window.privacyBanner.showPreferences(), with consent.mode: 'default-banner' |
setShopContext({ country, language }) | the locales of the i18n option, or event.context.shopifyLocale in a Nitro plugin, and a full page load to switch locales |
setCart(cart), automatic cart events | useCartAnalytics() from @shopify/hydrogen/vue, inside CartProvider |
cart | useCart() from createCartComponents() |
shop (shopId, hydrogenSubchannelId, acceptedLanguage, currency) | shop (shopId, storefrontId) and i18n (language, currency) of the shopify:analytics:ready hook |
useNuxtApp().$shopify.analytics | useShopifyAnalytics() |
analytics:publish hook | a destination, which only receives the events that the visitor's consent allows |
<ShopifyCartView :data="{ cart }" /> | <ShopifyCartView :cart="cartState" />, with useCart(state => state) |
<ShopifyCustomView /> | removed, custom events are not supported |
<ShopifyPrivacyBanner> and its accept, decline, setConsent | your own banner with consent.mode: 'custom-banner' and setTrackingConsent(), or Shopify's banner with 'default-banner' |
ShopifyProductView takes Hydrogen's ProductViewPayload, so price is the variant's MoneyV2, and variantId, variantTitle and quantity are required.
ShopifyCollectionView needs collection.handle, and ShopifySearchView only reports searches with a term.
The event payloads are Hydrogen's, so update your mappings for tools such as GA4, see analytics.
Errors
- Visitors no longer see Shopify's response. A failed request throws
[shopify] Request to Shopify failedwith Shopify's status, and Shopify's errors are written to the server log. If Shopify sent no error status, for example for GraphQL errors with a successful status or a network failure, the status is502instead of500. A failed admin token request is always a502. - A customer account request without a logged in customer throws a
401error with the message[shopify] No customer account session: the customer is not logged in, without theRequest failed:prefix. data.graphQLErrorsis nowcause.graphQLErrors. You can read it in your code, but it is never included in error pages, JSON error responses or the page payload, see error handling.
Renamed
| 1.x | 2.0 |
|---|---|
Hooks such as storefront:client:configure | shopify:storefront:client:configure, every hook starts with shopify: |
createStorefrontClient, createCustomerAccountClient, createAdminClient | createStorefrontApiClient, createCustomerAccountApiClient, createAdminApiClient |
createShopifyClient | removed, use the factory of the client you need |
ShopifyAuthCallbacks | ShopifyAdminAuthCallbacks, only for the admin client |
CustomerAccountSession, AdminTokenSet | ShopifyCustomerAccountSession, ShopifyAdminTokenSet |
CustomerAccountSessionData | no longer exported |
ShopifyTemplateHookParams | ShopifyCodegenHookParams, with codegen's Types.ConfiguredOutput as config instead of Record<string, unknown> |
Client factory option cache | browserCache, next to the new serverCache |
useCustomerAccountSession().ready | isReady |
webhooks.hooks | webhooks.subscriptions |
Module name nuxt-shopify, for hasNuxtModule() | @nuxtjs/shopify |
Nuxt plugin shopify:cache:storefront | shopify:storefront:cache |
Nuxt plugin shopify:customer-account-session | shopify:customer-account:session |
Nuxt plugin shopify:analytics | shopify:scripts |
Route middleware customer-account, in definePageMeta | shopify:customer-account |
shopify:config and shopify:setup keep their names.
nuxt typecheck reports hook names without the prefix in your Nuxt and Nitro plugins, but at runtime, hooks with an old name are never called.
If your own plugins use dependsOn, update it to the new plugin names.
Outside Nuxt
createCustomerAccountApiClientno longer needs aclientId. Instead, it needs your shop'sname, its numericshopIdand anauthoption that returns the customer's access token.createShopifyClientis removed. UsecreateStorefrontApiClient,createCustomerAccountApiClientorcreateAdminApiClientinstead.ShopifyGenericClientOptionsis removed.ShopifyClientDefinitionandShopifyClientSetupContextare no longer exported.- The admin client keeps its access token in memory, so it no longer requests a new token for every request.
npx @nuxtjs/shopify webhooksexits with code1on an unknown action.- The
initcommand is removed.npx nuxi@latest init -t gh:nuxt-modules/shopify/template ./my-shopdownloads the template from the main branch and installs its dependencies. To get the template of a release, add its tag, such asgh:nuxt-modules/shopify/template#v2.0.0.