Vue Storefront is now Alokai! Learn More
Alokai Changelog

Alokai Changelog

1.0.0-rc.18

Before starting the migration, please update all the dependencies to the compatible versions based on the compatibility matrix.

Major Changes

  • CHANGED Updated the package for compatibility with Node.js 22.
  • CHANGED Updated the enterprise registry to npm.alokai.cloud.
  • CHANGED Updates to SDK and frontend apps. Now, every sdk request should contain x-alokai-locale header instead of vsf-locale cookie. This change is important in CDN support, as we cannot pass cookies to the CDN.
  • 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.
  • CHANGED The @vue-storefront/multistore package has been renamed to @alokai/connect/config-switcher. If you were using the multistore functionality, you'll need to update your code to use the new package.

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, all modules were defined inline in the config file. Now, you can extract them to separate files.
  • ADDED createAlokaiMiddleware to @vue-storefront/next - a wrapper for a Next.js middleware which registers the Alokai-specific logic. Example usage
// apps/storefront-unified-nextjs/middleware.ts
import { createAlokaiMiddleware } from "@vue-storefront/next";

export default createAlokaiMiddleware(async (request) => {
  // your middleware logic
});
  • ADDED to @vue-storefront/next getPathnameFromRequestHeaders function which allows getting pathname from the request headers during the server side rendering. It requires createAlokaiMiddleware to be used in the middleware.ts file.
  • ADDED getConfigSwitcherHeader to defaultRequestConfig in the middlewareModule of @alokai/connect/sdk. It allows setting the x-alokai-middleware-config-id header on the Storefront side for the Config Switcher extension.

Example usage:

export function getSdkConfig() {
  return defineSdkConfig(
    ({ buildModule, config, getRequestHeaders, middlewareModule }) => ({
      commerce: buildModule(middlewareModule<CommerceEndpoints>, {
        apiUrl: `${config.apiUrl}/commerce`,
        cdnCacheBustingId: config.cdnCacheBustingId,
        defaultRequestConfig: {
          getConfigSwitcherHeader: (computedHeaders) => "some-value",
          headers: getRequestHeaders(),
        },
        ssrApiUrl: `${config.ssrApiUrl}/commerce`,
      }),
    }),
  );
}
  • ADDED New feature for the middleware app. Now, for every request, the middleware will convert the x-alokai-locale header into vsf-locale cookie. This change is important in CDN support, as we cannot pass cookies to the CDN. The feature can also be implemented in the projects that are NOT using @alokai/connect package, by adding an extension to each registered integration:
  1. Install @alokai/cookies-bridge package:
yarn add @alokai/cookies-bridge
  1. Add the extension to the integration configuration:
apps/storefront-middleware/integrations/<your-integration>/config.ts
// Only in projects that are NOT using `@alokai/connect` package.

+ import { createCookiesBridgeExtension } from "@alokai/cookies-bridge";
+ const cookiesBridgeExtension = createCookiesBridgeExtension([{
+   header: 'x-alokai-locale',
+   cookie: 'vsf-locale',
+ }]);

export const config = {
configuration: {
  // ...
}

extensions: (extensions: ApiClientExtension[]) => [
+    cookiesBridgeExtension,
  ...extensions,
  unifiedApiExtension,
  cdnExtension,
  ...(IS_MULTISTORE_ENABLED === 'true' ? [configSwitcherExtensionFactory()] : []),
],
};

Note: The extension should be added as first in the extensions list, as it should be executed before any other extension.

In some projects, the middleware configuration might be placed in middleware.config.ts file, but implementation is the same.

  • ADDED Added a way to pass playwright test options in Alokai CLI through the --playwright-options (-p) flag in the store test command.
alokai-cli store test --playwright-options="--project=nuxt-desktop --headed"
  • ADDED alokai store remove command.

Patch Changes

  • CHANGED The maximum file upload size limit has been increased to 20MB.
  • CHANGED Updated the express version to ^4.20.0 to fix security vulnerabilities. See more in GitHub Vulnerability Alert.
  • FIXED Fixed randomly failing integration tests when running them for multiple stores using the store test command. The issue was due to tests running in parallel through Turbo's pipeline. From now on, when running tests for multiple stores (using the --all flag or passing an array of store IDs via the --store-id flag), the tests will be run for each store consecutively.
  • FIXED Issue with jw-paginate on cart page in Nuxt storefront. Previously, it was throwing a SyntaxError: The requested module '/node_modules/jw-paginate/lib/jw-paginate.js?v=5a45ef3c' does not provide an export named 'default' error. Now, it is fixed by adding jw-paginate to the optimizeDeps.include config in nuxt.config.ts.

Migration guide

  1. Update the registry in your project:
  • Step 1: Update the registry in your project:
.npmrc
+ @vsf-enterprise:registry=https://npm.alokai.cloud
+ @alokai:registry=https://npm.alokai.cloud
- @vsf-enterprise:registry=https://registrynpm.storefrontcloud.io
- @alokai:registry=https://registrynpm.storefrontcloud.io
auto-install-peers=true
  • Step 2: Login to the enterprise registry:
npm login --registry=https://npm.alokai.cloud
  1. Update your Next application to use the new x-alokai-locale header instead of the vsf-locale cookie.

The changes below are only relevant for Next apps. If you are using Nuxt, you can skip this section.

  • Step 1: Update the storefront-unified-nextjs/sdk/index.ts file to pass current locale into SDK instance:
+import { getLocale as nextIntlGetLocale } from 'next-intl/server';

import { getSdk as getUniversalSdk } from './sdk.server';

/**
* A dedicated function to get the SDK instance on the server side.
* You can import it in React Server Components, Middleware, Route Handlers.
*/
-export const getSdk = () =>
+export const getSdk = async ({ getLocale = nextIntlGetLocale } = {}) => {
-  getUniversalSdk({
+  const locale = await getLocale();
+  return getUniversalSdk({
+    getLocale: () => locale,
+    getRequestHeaders: () => ({
+      cookies: cookies(),
+      headers: headers(),
+    }),
+  });
+};
  • Step 2: Update apps/storefront-unified-nextjs/middleware.ts
export default async function middleware(request: NextRequest) {
  // ... existing code

- const authRedirectPath = await getAuthRedirectPath(request);
+ const authRedirectPath = await getAuthRedirectPath(request, { locale });
  if (authRedirectPath) {
    response = NextResponse.redirect(new URL(`/${locale}${authRedirectPath}`, request.nextUrl));
  }
  // ...existing code
}

-async function getAuthRedirectPath(request: NextRequest) {
+async function getAuthRedirectPath(request: NextRequest, config: { locale: string }) {
- const sdk = getSdk();
+ const sdk = await getSdk({ getLocale: async () => config.locale });
  • Step 3: Update every place that fetches data on the server-side to wait for the promise returned by getSdk. For example:
-  const sdk = getSdk();
+  const sdk = await getSdk();
const currencies = await sdk.unified.getCurrencies();

If you're using SDK directly in a destructuring pattern like this: const { products } = getSdk().unified.getProducts({ skus });, you should first assign the resolved sdk to a variable:

const sdk = await getSdk();
const { products } = await sdk.unified.getProducts({ skus });
  • Step 4: Update storefront-unified-nextjs/components/providers.tsx:
-  sdk={getSdk()}
+  sdk={getSdk({
+    getLocale: () => locale,
+  })}
  1. Update your Nuxt application to use the new x-alokai-locale header instead of the vsf-locale cookie.

The changes below are only relevant for Nuxt apps. If you are using Next.js, you can skip this section.

  • Step 1: Remove unused cookie name from storefront-unified-nuxt/nuxt.config.ts:
  cookieNames: {
    currency: 'vsf-currency',
-      locale: 'vsf-locale',
  },
  • Step 2: Update storefront-unified-nuxt/localization.ts to stop setting locale cookie:
import type { SfLocale } from '~/types';
-import { type H3Event, parseCookies, setCookie as setResponseCookie } from 'h3';
-
-function setRequestCookie(event: H3Event, name: string, value: string) {
-  const { headers } = event.node.req;
-  const cookiesObject = {
-    ...parseCookies(event),
-    [name]: value,
-  };
-
-  try {
-    headers.cookie = Object.entries(cookiesObject)
-      .map((item) => `${encodeURIComponent(item[0])}=${encodeURIComponent(item[1])}`)
-      .join('; ');
-  } catch {
-    throw new Error(`Failed to set cookie ${name}=${value}`);
-  }
-}
-function setCookie(event: H3Event, name: string, value: string) {
-  setRequestCookie(event, name, value);
-  setResponseCookie(event, name, value, {
-    sameSite: 'strict',
-    secure: true,
-  });
-}

export default defineNuxtPlugin((nuxtApp) => {
if (import.meta.client) {
  return;
}

const { locale: i18nLocale, locales: i18nLocales } = (nuxtApp as unknown as { $i18n: Composer }).$i18n;
-  const { cookieNames } = useAppConfig();
const event = useRequestEvent();
const { locale, locales } = storeToRefs(useSfState());

if (!event) {
  return;
}

-  setCookie(event, cookieNames.locale, i18nLocale.value as SfLocale);
-
locale.value = i18nLocale.value as SfLocale;

// ...
});
  • Step 3: Update storefront-unified-nuxt/composables/useLocation/useLocation.ts to stop using locale cookie:
export const useLocation: UseLocationReturn = () => {
-  const { cookieNames } = useAppConfig();
const { locale } = storeToRefs(useSfState());
const { locale: i18nLocale } = useI18n();
-  const cookie = useCookie(cookieNames.locale, {
-    default: () => i18nLocale.value,
-    sameSite: 'strict',
-    secure: true,
-  });

whenever(i18nLocale, () => {
  locale.value = i18nLocale.value as SfLocale;
-    cookie.value = i18nLocale.value;
});

// ...
};
  1. Add jw-paginate to the optimizeDeps.include config in nuxt.config.ts:

This step is only relevant for Nuxt storefront in dev mode. If you are using Next.js, you can skip this step.

nuxt.config.ts
optimizeDeps: {
  include: [
    '@storefront-ui/vue',
    '@storefront-ui/shared',
    '@alokai/connect/logger',
    'vue3-lazy-hydration',
+    'jw-paginate',
  ],
},
  1. Use @alokai/connect package instead of @vue-storefront/middleware, @vue-storefront/sdk, vue-storefront/logger, vue-storefront/unified-data-model, @vue-storefront/multistore packages.

In this guide, we'll walk you through the process of migrating from the legacy packages to the new @alokai/connect package. This migration guide is designed to help you transition smoothly and take advantage of the new features and improvements in the @alokai/connect package.

  1. Update packages/tailwind-config/src/nuxt.ts. Please remember to run yarn build:packages after modifying packages dir.
packages/tailwind-config/src/nuxt.ts
import { tailwindConfig } from "@storefront-ui/react/tailwind-config";
import sfTypography from "@storefront-ui/typography";
import type { Config } from "tailwindcss";

export default {
  content: [],
  corePlugins: {
    preflight: true,
  },
  plugins: [sfTypography],
  presets: [tailwindConfig],
  theme: {
    extend: {
      screens: {
        "2xl": "1366px",
        "2xs": "360px",
        "3xl": "1536px",
        "4xl": "1920px",
        lg: "1024px",
        md: "768px",
        sm: "640px",
        xl: "1280px",
        xs: "376px",
      },
    },
  },
} as Config;

Important notes:

  • Interfaces of packages did not change, so you can expect the same names, methods, and behavior as before.
  • The @vue-storefront/multistore package has been renamed to @alokai/connect/config-switcher. You can use the new package to switch between different store configurations at runtime.
  • Some functions were moved to the @alokai/connect/integration-kit package. Be sure to import them from the correct package. You can think about integration-kit as a place for all utilities related to creating new integrations.
  • Functions moved from @vue-storefront/middleware:
    • apiClientFactory
  • Functions moved from @vue-storefront/unified-data-model:
    • validatePassword
    • unifiedExtensionFactory
    • createUnifiedCmsExtension
    • getNormalizers
    • assignToNormalizerContext
    • mergeNormalizers
    • getApiDefinitions
    • defineAddCustomFieldsFactory
    • toContextualizedNormalizers
  • All other functions remain in their respective packages.
  • All types related with moved functions are also moved to the @alokai/connect/integration-kit package.
  • Data models and unified methods declarations are now part of the root @alokai/connect package.

Migration steps:

  • Step 1: Install the new package.

Navigate to your storefront-unified-<framework> and storefront-middleware apps and install the new package:

# Using yarn
yarn add @alokai/connect

# Using pnpm
pnpm add @alokai/connect

# Using npm
npm install @alokai/connect
  • Step 2: Remove the legacy packages

Navigate to your storefront-unified-<framework> remove the legacy packages:

yarn remove @vue-storefront/sdk

Then, navigate to your storefront-middleware app and remove the legacy packages:

yarn remove @vue-storefront/middleware

If you are using @vue-storefront/unified-data-model or @vue-storefront/logger in your project, you need to remove them as well.

yarn remove @vue-storefront/multistore
yarn remove @vue-storefront/unified-data-model
yarn remove @vue-storefront/logger
  • Step 3: Update your imports

Find all imports of the legacy packages in your project and update them to import from the new @alokai/connect package. For example:

- import { createApiClient } from "@vue-storefront/middleware";
+ import { createApiClient } from "@alokai/connect/integration-kit";

- import { createLogger } from "@vue-storefront/logger";
+ import { createLogger } from "@alokai/connect/logger";
  • Step 4: Update your code

Review your codebase and update any references to the legacy packages. Make sure to test your application thoroughly to ensure that everything works as expected. Because of the functional equivalence between the legacy and new packages, you should not encounter any breaking changes.

  1. Migrate from @vue-storefront/multistore to @alokai/connect/config-switcher

This section is only relevant if you were using the @vue-storefront/multistore package in your project. If you weren't using multistore functionality, you can skip this section.

  • Step 1: Update your imports
- import { createMultistoreExtension } from "@vue-storefront/multistore";
+ import { createConfigSwitcherExtension } from "@alokai/connect/config-switcher";
  • Step 2: Update your configuration file

Rename the multistore.config.ts file to configSwitcher.config.ts and update the imports to import from the new @alokai/connect/config-switcher package.

configSwitcher.ts
+ import { createConfigSwitcherExtension } from "@alokai/connect/config-switcher";

- export const multistoreConfig = {
-   async fetchConfiguration(/* { domain } */) {
-     return {
-       "my-apparel-domain.io": {
-         baseSiteId: "apparel-uk",
-         defaultCurrency: "GBP",
-         // ...
-       },
-       "my-electronics-domain.io": {
-         baseSiteId: "electronics",
-         defaultCurrency: "USD",
-         // ...
-       },
-     };
-   },
-   mergeConfigurations({ baseConfig, storeConfig }) {
-     // ...
-   },
-   cacheManagerFactory() {
-     // ...
-   },
- };

+ export const configSwitcherExtension = createConfigSwitcherExtension({
+   // Static configuration
+   configuration: {
+     "my-apparel-domain.io": {
+       api: {
+         baseSiteId: "apparel-uk",
+         defaultCurrency: "GBP",
+         // ...
+       },
+     },
+     "my-electronics-domain.io": {
+       api: {
+         baseSiteId: "electronics",
+         defaultCurrency: "USD",
+         // ...
+       },
+     },
+   },
+   // Use domain strategy to match the previous behavior
+   // The old multistore package only supported domain-based switching
+   switchStrategy: "domain",
+   // Set cache TTL (in seconds) - default is 10
+   cacheTTL: 10,
+ });

Then move the file to the integrations/<integrationName>/extensions/configSwitcher.ts directory.

For dynamic configurations that were previously fetched in the fetchConfiguration method, you can use an async function:

export const configSwitcherExtension = createConfigSwitcherExtension({
  // Asynchronously fetch configurations from an external source
  // Returns a Record<ConfigId, Configuration> mapping config IDs to their settings
  configuration: async () => {
    const response = await fetch(`https://api.example.com/configs`);
    return await response.json();
  },
  switchStrategy: "domain",
  cacheTTL: 10,
});
  • Step 3: Update your integration configuration

This example uses the SAPCC integration, but the same principles apply to all other integrations like Magento, BigCommerce, Commercetools, etc.

integrations/sapcc/config.ts
import { AUTH_USER_TOKEN_COOKIE_NAME, type MiddlewareConfig } from '@vsf-enterprise/sapcc-api';
import type { ApiClientExtension, Integration } from '@vue-storefront/middleware';

- import { multistoreExtensionFactory } from '../../multistore/utils';
+ import { configSwitcherExtension } from './extensions/configSwitcher';
import { cdnExtension, customExtension, unifiedApiExtension } from './extensions';

const {
- IS_MULTISTORE_ENABLED,
  NODE_ENV,
  SAPCC_API_URI,
  SAPCC_OAUTH_CLIENT_ID,
  SAPCC_OAUTH_CLIENT_SECRET,
  SAPCC_OAUTH_TOKEN_ENDPOINT,
  SAPCC_OAUTH_TOKEN_REVOKE_ENDPOINT,
  SAPCC_OAUTH_URI,
} = process.env;

export const config = {
  configuration: {
    // integration config 
  },
  extensions: (extensions: ApiClientExtension[]) => [
    ...extensions,
    unifiedApiExtension,
    cdnExtension,
-   ...(IS_MULTISTORE_ENABLED === 'true' ? [multistoreExtensionFactory()] : []),
+   configSwitcherExtension,
    customExtension,
  ],

  location: '@vsf-enterprise/sapcc-api/server',
} satisfies Integration<Config>;

Configuration Merging

The new package automatically handles configuration merging, so you no longer need to implement the mergeConfigurations method. The base configuration for your integration is automatically deep-merged with the store-specific configuration.

  • Step 4: Remove old files
  1. You can now remove the apps/storefront-middleware/multistore directory, as it won't be needed anymore.
  2. Update the app bootstrapping in apps/storefront-middleware/src/index.ts
apps/storefront-middleware/src/index.ts
import { createServer, type CreateServerOptions } from '@alokai/connect/middleware';

import { config } from '../middleware.config';

const developmentCorsConfig: CreateServerOptions['cors'] = {
  credentials: true,
  origin: true,
};
const port = Number(process.env.API_PORT) || 4000;

runApp();

async function runApp() {
  const app = await createServer(config, {
    cors: process.env.NODE_ENV === 'production' ? undefined : developmentCorsConfig,
  });

  app.listen(port, '', () => {
    console.log(`API server listening on port ${port}`);
  });
}
  1. Remove multistore:dev script from apps/storefront-middleware/package.json.
  • Step 5: (Optional) Set up caching

The new package includes built-in caching with a configurable TTL, so you no longer need to implement the cacheManagerFactory method. By default, configurations are cached for 10 seconds, but you can adjust this by setting the cacheTTL parameter:

createConfigSwitcherExtension({
  configuration: {
    /* ... */
  },
  cacheTTL: 60, // Cache for 60 seconds
});
  1. Use Node.js version 22.14.0 or higher

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.

  • Step 1: Update your .nvmrc or .node-version file to 22.14.0
- 18.17.1
+ 22.14.0
  • Step 2: Upgrade @types/node to version ^22.13.17 for compatibility with the latest Node.js features.
- "@types/node": "18.x",
+ "@types/node": "22.13.17",
  • Step 3: Update CI pipeline to use Node.js version 22.14.0 or higher.
  1. (Optional) Separate SDK modules to separate files
  • Step 1: Create new directory modules in the sdk directory of the storefront app.
  • Step 2: Create new file for each module.
apps/storefront-unified-nextjs/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,
    }),
);
  • Step 3: Create a new file sdk/modules/index.ts that exports all modules.
apps/storefront-unified-nextjs/sdk/modules/index.ts
export * from "./unified";
  • Step 4: Update your SDK configuration file to import the modules.
apps/storefront-unified-nextjs/sdk/config.ts
+ import * as modules from "./modules";

+ import * as modules from '@/sdk/modules';

export function getSdkConfig() {
-  return defineSdkConfig(({ buildModule, config, getRequestHeaders, middlewareModule }) => ({
-    // ...
-  }));
+  return defineSdkConfig(modules);
}

0.2.0

Minor Changes

  • CHANGED In both @vue-storefront/next and @vue-storefront/nuxt, 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. Read the migration guides for this Storefront version to see examples of using apiUrl and ssrApiUrl in your SDK configuration files. This change is necessary to support custom domain setup OOTB.
  • CHANGED Storefronts has been update to be compliant with the European Accessibility Act (EAA) and Web Content Accessibility Guidelines (WCAG) 2.1 AA.
  • ADDED Multistore capabilities with shared configuration packages
  • ADDED File-based inheritance system for efficient code sharing across stores
  • ADDED Centralized configuration management for ESLint, Prettier, Tailwind, and lint-staged
  • CHANGED Project structure to support multiple stores with shared packages
  • CHANGED Turbo configuration updated to version 2.4.4 with new tasks format
  • ADDED Alokai CLI integration for store management
  • ADDED CI/CD pipeline setup for multistore deployments

Migration guide (Multistore)

To migrate your existing project to the new multistore setup, follow the multistore migration guide. Your Alokai Solution Architect can help you with the migration process.

Migration guide (Custom domains setup OOTB - Next.js)

The changes below are only relevant for Next apps. If you are using Nuxt, you can skip this section.

  1. Update environment variables

In the apps/storefront-unified-nextjs/sdk/options.ts file, verify the NEXT_PUBLIC_ALOKAI_MIDDLEWARE_SSR_API_URL environment variable exists:

const ssrApiUrl = env('NEXT_PUBLIC_ALOKAI_MIDDLEWARE_SSR_API_URL');

+ if (!ssrApiUrl) {
+   throw new Error('NEXT_PUBLIC_ALOKAI_MIDDLEWARE_SSR_API_URL is required to run the app');
+ }

See our guide on initializing the SDK for a complete version of the file.

Also, make sure the environment variable is added to the apps/storefront-unified-nextjs/.env.example file and - if it exists - the apps/storefront-unified-nextjs/.env file:

+ NEXT_PUBLIC_ALOKAI_MIDDLEWARE_SSR_API_URL="http://localhost:4000"
  1. Update @vue-storefront/next version

In apps/storefront-unified-nextjs/package.json, upgrade the version of @vue-storefront/next package to 5.1.0.

{
"dependencies": {
-   "@vue-storefront/next": "4.3.2",
+   "@vue-storefront/next": "5.1.0",
}
}

remember to reinstall the dependencies of your project with the yarn install command afterwards.

  1. Update SDK configuration file

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

import { defineSdkConfig } from '@vue-storefront/next';

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

Migration guide (Custom domains setup OOTB - Nuxt)

  1. Update environment variables

Make sure the NUXT_PUBLIC_ALOKAI_MIDDLEWARE_SSR_API_URL environment variable is added to the apps/storefront-unified-nuxt/.env.example file and - if it exists - the apps/storefront-unified-nuxt/.env file:

+ NUXT_PUBLIC_ALOKAI_MIDDLEWARE_SSR_API_URL="http://localhost:4000"
  1. Update @vue-storefront/nuxt version

In apps/storefront-unified-nuxt/package.json, upgrade the version of @vue-storefront/nuxt package to 8.1.0.

{
"dependencies": {
-   "@vue-storefront/nuxt": "7.0.0",
+   "@vue-storefront/nuxt": "8.1.0",
}
}

remember to reinstall the dependencies of your project with the yarn install command afterwards.

  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`,
}),
}));

0.1.0

Minor Changes

  • ADDED Alokai ecosystem versioning: Each release of a core package now includes a version bump for the entire ecosystem, simplifying tracking of changes and ensuring compatibility between packages. Core packages include:
  • @vue-storefront/middleware
  • @vue-storefront/multistore
  • @vue-storefront/unified-data-model
  • @vue-storefront/sdk
  • @vue-storefront/nuxt
  • @vue-storefront/next Compatibility matrix for the entire ecosystem is available here.
  • CHANGED @vue-storefront/nuxt version updated to v7.0.0.
  • CHANGED from now on getSdk is available instead of sdk property on global NuxtApp.$alokai object.
  • CHANGED You should now ensure that environment variables NEXT_PUBLIC_ALOKAI_MIDDLEWARE_SSR_API_URL (for Next.js apps) and NUXT_PUBLIC_ALOKAI_MIDDLEWARE_SSR_API_URL (for Nuxt apps) are set in your file both locally and in your deployed application.

Patch Changes

  • FIXED Nuxt App - useLazyProduct composable merged product data wrongly.
  • FIXED Nuxt App - localization plugin need to set locale cookie directly in the plugin initialization.
  • FIXED Next App - the initial page load with a locale in the URL, different from the previously set one, now correctly fetches data in the right language from the server.

Migration guide (Next.js)

The changes below are only relevant for Next apps. If you are using Nuxt, you can skip this section.

  1. Set the NEXT_PUBLIC_ALOKAI_MIDDLEWARE_SSR_API_URL environment variable in your .env file.
+ NEXT_PUBLIC_ALOKAI_MIDDLEWARE_SSR_API_URL=http://localhost:4000
  1. Set the NEXT_PUBLIC_ALOKAI_MIDDLEWARE_SSR_API_URL environment variable to http://additional-app-middleware:4000 in your deployed application.
  2. Use cookies from next/headers in your getSdk function to fix the issue with the initial page load with a locale in the URL, different from the previously set one.
import {
headers,
+  cookies,
} from 'next/headers';
import { getSdk } from './sdk.server';

// ...

getSdk({
-  getRequestHeaders: () => headers
+  getRequestHeaders: () => ({
+    headers: headers(),
+    cookies: cookies(),
+  }),
});

Migration guide (Nuxt)

The changes below are only relevant for Nuxt apps. If you are using Next.js, you can skip this section.

  1. Set the NUXT_PUBLIC_ALOKAI_MIDDLEWARE_SSR_API_URL environment variable in your .env file.
+ NUXT_PUBLIC_ALOKAI_MIDDLEWARE_SSR_API_URL=http://localhost:4000
  1. Set the NUXT_PUBLIC_ALOKAI_MIDDLEWARE_SSR_API_URL environment variable to http://additional-app-middleware:4000 in your deployed application.
  2. Modify localization plugin to set locale cookie directly in the plugin initialization.
apps/storefront-unified-nuxt/plugins/localization.ts
+ import type { Composer } from '#i18n';
// ...
- nuxtApp.hook('vue:setup', () => {
-  const { locale: i18nLocale, locales: i18nLocales } = useI18n();
+ const { locale: i18nLocale, locales: i18nLocales } = (nuxtApp as unknown as { $i18n: Composer }).$i18n;
// ...
- });
  1. Update @vue-storefront/nuxt package to v7.0.0.
- "@vue-storefront/nuxt": "6.x.x",
+ "@vue-storefront/nuxt": "7.0.0",
  1. Update the way you get the SDK instance.
// get sdk instance
- const { sdk } = useNuxtApp().$alokai;
+ const sdk = useNuxtApp().$alokai.getSdk();

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

Common issues

Despite following this migration guide, you might still experience issues in several areas of your project.

Nuxt Checkout module linting errors

Running the yarn lint command might result in errors caused by the Checkout module in the Nuxt Storefront. If that is the case in your project:

  1. In the apps/storefront-unified-nuxt/sf-modules/checkout/components/Checkout/Checkout.vue file disable the following eslint rule on line 1:
+ <!-- eslint-disable vue/multi-word-component-names -->
<template>
...
</template>

and the following eslint rule on line 151:

if (!termsAndConditions.value) {
validationMessages.push('validation.missingTermsAndConditions');
+ // eslint-disable-next-line vue/no-side-effects-in-computed-properties
invalidTermsAndConditions.value = true;
}
  1. In the apps/storefront-unified-nuxt/sf-modules/checkout/pages/checkout.vue file disable the following eslint rule on line 1:
+ <!-- eslint-disable vue/multi-word-component-names -->
<template>
...
</template>

Custom extension linting errors

Running the yarn lint command might result in errors caused by the custom extension in the Storefront Middleware app. If that is the case in your project, in the apps/storefront-middleware/api/custom-methods/custom.ts file disable the following eslint rule on line 1:

+ /* eslint-disable @typescript-eslint/no-unused-vars */
import { type IntegrationContext } from '../../types';
import type { CustomMethodArgs, CustomMethodResponse } from './types';

Nuxt and Middleware tsconfig.json linting errors

Running the yarn lint command might result in errors caused by the Typescript configuration files in the Nuxt Storefront and Storefront Middleware apps. If that is the case in your project, add new lines at the end of the apps/storefront-unified-nuxt/tsconfig.json and apps/storefront-middleware/tsconfig.json files.