Vue Storefront is now Alokai! Learn More
@vue-storefront/nuxt

@vue-storefront/nuxt

10.0.0

Major Changes

  • [CHANGED]BREAKING Upgraded to Nuxt 4. All Nuxt-related packages now require Nuxt ^4.0.0.

Migration Guide

1. Update Nuxt and related dependencies

Update your package.json:

package.json
-"nuxt": "^3.13.2",
+"nuxt": "^4.0.0",
-"nuxt-jsonld": "^2.0.8",
-"@nuxtjs/i18n": "^8.5.6",
+"@nuxtjs/i18n": "^10.2.3",
-"@pinia/nuxt": "^0.5.5",
+"@pinia/nuxt": "^0.11.0",
-"pinia": "^2.2.6",
+"pinia": "^3.0.4",

2. Remove nuxt-jsonld module

nuxt-jsonld is not compatible with Nuxt 4. Replace useJsonld with native useHead:

nuxt.config.ts
 modules: [
-  'nuxt-jsonld',...
 ]
composables/seo/useSeoProduct.ts
-import { useJsonld } from '#jsonld';
-useJsonld({ ... });
+useHead({
+  script: [
+    {
+      type: 'application/ld+json',
+      innerHTML: JSON.stringify({ ... }),
+    },
+  ],
+});

3. Migrate i18n to v10 directory structure

i18n v10 enforces a new directory structure where all i18n files must be placed under a root-level i18n/ directory. Move locale files accordingly:

mkdir -p i18n
mv lang i18n/lang
mv i18n.config.ts i18n/i18n.config.ts

Update imports in locale index files:

i18n/lang/en/index.ts
-import base from '@/lang/en/base.json';
+import base from '@/i18n/lang/en/base.json';

4. Rename @alokai/instrumentation-nuxt3-module to @alokai/instrumentation-nuxt-module

package.json
-"@alokai/instrumentation-nuxt3-module": "...",
+"@alokai/instrumentation-nuxt-module": "...",
nuxt.config.ts
 modules: [
-  '@alokai/instrumentation-nuxt3-module',...
+  '@alokai/instrumentation-nuxt-module',...
 ]

5. Update @nuxt/image custom providers to v2 API

Custom image providers must use defineProvider from @nuxt/image/runtime:

modules/alokai-cloudinary/provider.ts
-import { getImage as cloudinaryGetImage } from '#image/providers/cloudinary';
-import type { ProviderGetImage } from '@nuxt/image';
+import { defineProvider } from '@nuxt/image/runtime';
+import cloudinaryFactory from '@nuxt/image/runtime/providers/cloudinary';

-export const getImage: ProviderGetImage = (src, options, ctx) => {
+export default defineProvider({
+  getImage: (src, options, ctx) => {
   // ...
-  return cloudinaryGetImage(src, { ...options, baseURL }, ctx);
-};
+    const cloudinary = cloudinaryFactory();
+    return cloudinary.getImage(src, { ...options, baseURL }, ctx);
+  },
+});

6. Replace useVModel with native computed

VueUse's useVModel returns a Ref type incompatible with Vue 3.5's v-model:

-import { useVModel } from '@vueuse/core';
-const internalModelValue = useVModel(props, 'modelValue', emit);
+const internalModelValue = computed({
+  get: () => props.modelValue,
+  set: (value) => emit('update:modelValue', value),
+});

Patch Changes

  • CHANGED Align dependency versions across SDKs, tooling, and shared configs.
  • FIXED Standardize type usage to always reference API type packages across integrations and SDKs.
  • Updated dependencies:
    • @alokai/connect@2.0.0
    • @alokai/instrumentation-nuxt-module@1.0.0

9.1.0

Minor Changes

Introduced Alokai instrumentation support

  • CHANGED The @vue-storefront/nuxt module now injects value of NUXT_PUBLIC_ALOKAI_VERSION environment variable into appConfig.

Patch Changes

  • Updated dependencies:
    • @alokai/instrumentation-nuxt3-module@1.0.0

9.0.0

Major Changes

  • CHANGED Guarantee compatibility with @alokai/connect package.
  • CHANGED Updated the package for compatibility with Node.js 22.

Key Updates:

  • Upgraded to the latest version of Node.js 22
  • Updated CI pipelines to use Node.js 22 for consistency.
  • Updated .nvmrc or .node-version files to specify Node.js version 22.14.
  • Upgraded @types/node to version ^22.13.17 for compatibility with the latest Node.js features.

Recommendations:

  • Use Node.js version 22.14.0 or higher for optimal performance, security, and compatibility.
  • While Node.js 20 is technically supported, it is not recommended as it may cause compatibility issues with certain packages and has not been thoroughly tested. CHANGED Replaced core dependencies with a new @alokai/connect package. @vue-storefront/middleware, @vue-storefront/sdk, vue-storefront/logger, vue-storefront/unified-data-model, @vue-storefront/multistore were replaced with @alokai/connect. The replacement preserves the same functionality and interface as the original packages. To read more about the @alokai/connect package, please refer to the documentation.

Minor Changes

  • ADDED - every request now contains additional "x-alokai-locale" header.
  • ADDED Module-based SDK configuration with defineSdkModule and enhanced defineSdkConfig in @vue-storefront/nuxt. This new approach allows for better code organization and reusability of SDK modules.

Before (all modules inline in the config file)

apps/storefront-unified-nuxt/sdk.config.ts

export default defineSdkConfig(
  ({ buildModule, middlewareModule, config, getRequestHeaders }) => ({
    unified: buildModule(middlewareModule<UnifiedEndpoints>, {
      apiUrl: `${config.apiUrl}/commerce/unified`,
      ssrApiUrl: `${config.ssrApiUrl}/commerce/unified`,
      cdnCacheBustingId: config.cdnCacheBustingId,
      defaultRequestConfig: {
        getConfigSwitcherHeader,
        headers: getRequestHeaders(),
      },
      methodsRequestConfig:
        config.defaultMethodsRequestConfig.unifiedCommerce.middlewareModule,
    }),
  }),
);

After (modules extracted to separate files)

apps/storefront-unified-nuxt/sdk-modules/unified.ts

// Define reusable module
const unified = defineSdkModule(
  ({ buildModule, config, getRequestHeaders, middlewareModule }) =>
    buildModule(middlewareModule<UnifiedEndpoints>, {
      apiUrl: `${config.apiUrl}/commerce/unified`,
      ssrApiUrl: `${config.ssrApiUrl}/commerce/unified`,
      cdnCacheBustingId: config.cdnCacheBustingId,
      defaultRequestConfig: {
        getConfigSwitcherHeader,
        headers: getRequestHeaders(),
      },
      methodsRequestConfig:
        config.defaultMethodsRequestConfig.unifiedCommerce.middlewareModule,
    }),
);

apps/storefront-unified-nuxt/sdk-modules/index.ts

export * from "./unified";

apps/storefront-unified-nuxt/sdk.config.ts

import * as modules from "./modules";

const config = defineSdkConfig(modules);
  • ADDED Added Server Middleware handler appending x-pathname and x-search parameters to Nuxt request object.
  • ADDED Added defineGetConfigSwitcherHeader from @alokai/connect/sdk as a global import source.

Patch Changes

  • FIXED Added missing h3 imports for defineEventHandler and getRequestURL in serverMiddleware.ts
  • Updated dependencies:
    • @alokai/connect@1.0.0

9.0.0-rc.6

Patch Changes

  • FIXED Added missing h3 imports for defineEventHandler and getRequestURL in serverMiddleware.ts

9.0.0-rc.5

Minor Changes

  • ADDED Module-based SDK configuration with defineSdkModule and enhanced defineSdkConfig in @vue-storefront/nuxt. This new approach allows for better code organization and reusability of SDK modules.

Before

export default defineSdkConfig(
  ({ buildModule, middlewareModule, config, getRequestHeaders }) => ({
    unified: buildModule(middlewareModule<UnifiedEndpoints>, {
      apiUrl: `${config.apiUrl}/commerce/unified`,
      ssrApiUrl: `${config.ssrApiUrl}/commerce/unified`,
      cdnCacheBustingId: config.cdnCacheBustingId,
      defaultRequestConfig: {
        getConfigSwitcherHeader,
        headers: getRequestHeaders(),
      },
      methodsRequestConfig:
        config.defaultMethodsRequestConfig.unifiedCommerce.middlewareModule,
    }),
  }),
);

After

// Define reusable module
const unified = defineSdkModule(
  ({ buildModule, config, getRequestHeaders, middlewareModule }) =>
    buildModule(middlewareModule<UnifiedEndpoints>, {
      apiUrl: `${config.apiUrl}/commerce/unified`,
      ssrApiUrl: `${config.ssrApiUrl}/commerce/unified`,
      cdnCacheBustingId: config.cdnCacheBustingId,
      defaultRequestConfig: {
        getConfigSwitcherHeader,
        headers: getRequestHeaders(),
      },
      methodsRequestConfig:
        config.defaultMethodsRequestConfig.unifiedCommerce.middlewareModule,
    }),
);

// Use module in config
export default defineSdkConfig({
  unified,
});
  • ADDED Added Server Middleware handler appending x-pathname and x-search parameters to Nuxt request object.
  • ADDED Added defineGetConfigSwitcherHeader from @alokai/connect/sdk as a global import source.

Patch Changes

  • Updated dependencies:
    • @alokai/connect@1.0.0-rc.4

9.0.0-rc.4

Major Changes

  • CHANGED Updated the package for compatibility with Node.js 22.

Key Updates:

  • Upgraded to the latest version of Node.js 22
  • Updated CI pipelines to use Node.js 22 for consistency.
  • Updated .nvmrc or .node-version files to specify Node.js version 22.14.
  • Upgraded @types/node to version ^22.13.17 for compatibility with the latest Node.js features.

Recommendations:

  • Use Node.js version 22.14.0 or higher for optimal performance, security, and compatibility.
  • While Node.js 20 is technically supported, it is not recommended as it may cause compatibility issues with certain packages and has not been thoroughly tested.

Minor Changes

  • ADDED - every request now contains additional "x-alokai-locale" header.

Patch Changes

  • Updated dependencies:
    • @alokai/connect@1.0.0-rc.3

9.0.0-rc.3

Patch Changes

  • Updated dependencies:
    • @alokai/connect@1.0.0-rc.2

9.0.0-rc.2

Patch Changes

  • Updated dependencies:
    • @alokai/connect@1.0.0-rc.1

9.0.0-rc.1

Major Changes

Update packages to work with connect rc version

Patch Changes

  • Updated dependencies:
    • @alokai/connect@1.0.0-rc.0

9.0.0-rc.0

Major Changes

Replace legacy packages with a connect package

8.1.0

Minor Changes

  • CHANGED changed metatags content to fit new company name

8.0.0

Major Changes

  • CHANGED The config parameter available in the callback passed to defineSdkConfig() no longer contains computed middlewareUrl property. It now exposes apiUrl and ssrApiUrl that should be used instead.

Migration guide

  1. Update SDK configuration file

Update your SDK configuration file (apps/storefront-unified-nuxt/sdk.config.ts) so that registered modules use apiUrl and ssrApiUrl properties instead of middlewareUrl.

export default defineSdkConfig(({ buildModule, config, getRequestHeaders, middlewareModule }) => ({
  commerce: buildModule(middlewareModule, {
-   apiUrl: `${config.middlewareUrl}/commerce`,
+   apiUrl: `${config.apiUrl}/commerce`,
+   ssrApiUrl: `${config.ssrApiUrl}/commerce`,
  }),
}));

7.0.0

Major Changes

  • CHANGED SDK configuration is initialized NOT immediately, but only when needed.
  • [CHANGED]BREAKING from now on getSdk is available instead of sdk property on global NuxtApp.$alokai object.
// get sdk instance
- const { sdk } = useNuxtApp().$alokai;
+ const sdk = useNuxtApp().$alokai.getSdk();

// fetch some data
sdk.unified.getProducts();

6.2.0

Minor Changes

ADDED plugin providing the logger utility to the storefront via auto-import

6.1.0

Minor Changes

  • CHANGED defaultMethodsRequestConfig, so the getCategory, and getPage methods will use GET request as a default.

6.0.2

Patch Changes

  • CHANGED the package @vue-storefront/sdk is now a peer dependency instead of dependency

6.0.1

Patch Changes

FIXED Removed backquote from defineSdkConfig.template

6.0.0

Major Changes

  • BREAKING: Added functionality that automatically configures the proper URLs for SSR & SPA modes when mutlistore mode is enabled. Left your environment variables like in normal mode, just set NUXT_PUBLIC_ALOKAI_MULTISTORE_ENABLED to true.

5.0.0

Major Changes

  • ADDED global state management with Pinia. This will allow you to keep your global state in a more organized way. It shares the data about:
  • cart
  • customer
  • currency
  • locale

This change will require you to refactor your composables to make use of the introduced state manager. As this is only a state management, you will still need to use the composables to fetch the data and put it into the state.

Every part of global state can now be used as refs so reading and writing to them is more straightforward.

Example of usage:

<template>
  <div>
    <p>Cart total: {{ cart.total }}</p>
    <p>Customer name: {{ customer.firstName }} {{ customer.lastName }}</p>
    <p>Currency: {{ currency }}</p>
    <p>Locale: {{ locale }}</p>
  </div>
</template>

<script setup>
const { cart, customer, currency, currencies, locale, locales } =
  storeToRefs(useSfState());

// updating the currency state
currency.value = "USD";

// updating the cart state
onMounted(async () => {
  cart.value = await useSdk().unified.getCart();
});
</script>
  • BREAKING CHANGED module configKey is changed from vsf to alokai. Also, the support for the vsf key in Runtime Envs has been changed to alokai.
 meta: {
    name: "@vue-storefront/nuxt",
-   configKey: "vsf",
+   configKey: "alokai",
    compatibility: {
      nuxt: "^3.0.0",
    },

nuxt.options.runtimeConfig.public.alokai = defu(
-  nuxt.options.runtimeConfig.public?.vsf as any,
+  nuxt.options.runtimeConfig.public?.alokai as any,
   options
);

Patch Changes

  • Updated dependencies:
    • @vue-storefront/sdk@3.2.0

4.1.1

Patch Changes

FIXED: Added getCurrencies unified endpoint to be fetch by HTTP GET. This change enable caching this endpoint on CDN.

4.1.0

Minor Changes

ADDED: Using the GIT_SHA environment variable as secondary input for cdnCacheBustingId option. You can still override this value through NUXT_PUBLIC_ALOKAI_MIDDLEWARE_CDN_CACHE_BUSTING_ID. ADDED Value of Busting ID for CDN Cache. You can access it via config.cdnCacheBustingId. CHANGED Deprecated middlewareUrl in defineSdkConfig context. Use config.middlewareUrl instead. CHANGED Deprecated defaults in defineSdkConfig context. Use config.defaultMethodsRequestConfig instead. CHANGED Depreacted vsf key in RuntimeConfig. Use alokai instead. You should change you environment variables. Example: Change from NUXT_PUBLIC_VSF_MIDDLEWARE_API_URL to NUXT_PUBLIC_ALOKAI_MIDDLEWARE_API_URL. CHANGED Internal naming changed from VSF to Alokai. For e.g. we inject the SDK into the $alokai key in Nuxt App instead of $vsf as in previous versions.

4.0.1

Patch Changes

  • CHANGED shared package wasn't being bundled with the release of the package

4.0.0

Major Changes

  • CHANGED Updated core sdk dependency to latest version
  • ADDED Added .config parameter in createSdk callback

Patch Changes

  • Updated dependencies:
    • @vue-storefront/sdk@3.1.0

3.1.1

Patch Changes

  • FIXED Using the runtime config is now working properly. You can use NUXT_PUBLIC_VSF_MIDDLEWARE_API_URL, NUXT_PUBLIC_VSF_MIDDLEWARE_SSR_API_URL and NUXT_PUBLIC_VSF_MULTISTORE_ENABLED environments variables to define config in the runtime.

3.1.0

  • ADDED middlewareModule to defineSdkConfig params.
sdk.config.ts
- import { UnifiedApiExtension } from "storefront-middleware/types"
+ import { UnifiedEndpoints } from "storefront-middleware/types"

export default defineSdkConfig(
-  ({ buildModule, middlewareUrl, getRequestHeaders }) => ({
-    commerce: buildModule(unifiedModule<UnifiedApiExtension>, {
-      apiUrl: `${middlewareUrl}/commerce`,
-      requestOptions: { headers: getRequestHeaders },
+  ({ buildModule, middlewareModule, middlewareUrl, getRequestHeaders }) => ({
+      commerce: buildModule(middlewareModule<UnifiedEndpoints>, {
+        apiUrl: `${middlewareUrl}/commerce`,
+        defaultRequestConfig: { headers: getRequestHeaders() },
      }),
  })
);
  • CHANGED deprecate getCookieHeader, use getRequestHeaders instead
sdk.config.ts
export default defineSdkConfig(
-  ({ buildModule, middlewareModule, middlewareUrl, getCookieHeader }) => ({
+  ({ buildModule, middlewareModule, middlewareUrl, getRequestHeaders }) => ({
      commerce: buildModule(middlewareModule<UnifiedEndpoints>, {
        apiUrl: `${middlewareUrl}/commerce`,
-        defaultRequestConfig: { headers: getCookieHeader() }, // Only cookie header is included.
+        defaultRequestConfig: { headers: getRequestHeaders() }, // All headers are included.
      }),
  })
);

3.0.3

  • CHANGED @nuxt/kit locked 3.7.4 version to @nuxt/kit@^3.7.4

3.0.2

  • FIXED Multi-store URL calculation, now working correctly in the browser.

3.0.1

  • CHANGED Set @vue-storefront/sdk as a dependency instead of a peer dependency

3.0.0

  • BREAKING Rewritten from scratch. Now the package exports a Nuxt module which allows to initialize the Vue Storefront SDK.