Getting Started

This guide covers how to set up and use the Alokai SDK in Next.js, Nuxt, and plain JavaScript applications. The SDK provides a type-safe interface to communicate with your Server Middleware.

The Alokai Storefront comes with the SDK already configured. The Installation and Initializing sections below are only relevant if you're setting up the SDK from scratch. If you just want to use the SDK, skip to Usage.

In the examples below, we assume that you have an Alokai app with the Unified Data Model. However, the approach for non-unified Alokai applications is similar.

Installation

To get started with the SDK within Next.js, first you have to install the @vue-storefront/next package. In the root of your Storefront project run:

Next.js

# Using yarn
yarn add @vue-storefront/next

# Using pnpm
pnpm add @vue-storefront/next

# Using npm
npm install @vue-storefront/next

Initializing the SDK

To use the SDK in your application, you need to initialize it first. Create an sdk directory in the root of your project and follow these steps:

Create SDK Options

Create sdk/options.ts to configure the middleware address for both client and SSR mode, cache busting, and multistore settings.

The env() helper from @vue-storefront/next reads environment variables at runtime instead of build time. It is a built-in replacement for the next-runtime-env package — no additional configuration or extra packages required. It works on both server and client, and NEXT_PUBLIC_* variables are automatically injected into the client-side by AlokaiProvider.

sdk/options.ts

import { env, resolveSdkOptions } from "@vue-storefront/next";

export function getSdkOptions() {
  const apiUrl = env("NEXT_PUBLIC_ALOKAI_MIDDLEWARE_API_URL");
  const ssrApiUrl = env("NEXT_PUBLIC_ALOKAI_MIDDLEWARE_SSR_API_URL");
  const cdnCacheBustingId =
    env("NEXT_PUBLIC_ALOKAI_MIDDLEWARE_CDN_CACHE_BUSTING_ID") ??
    env("GIT_SHA") ??
    "no-cache-busting-id-set";
  const isMultiStoreEnabled =
    env("NEXT_PUBLIC_ALOKAI_MULTISTORE_ENABLED") === "true";

  if (!apiUrl) {
    throw new Error(
      "NEXT_PUBLIC_ALOKAI_MIDDLEWARE_API_URL is required to run the app"
    );
  }

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

  return resolveSdkOptions({
    middleware: {
      apiUrl,
      cdnCacheBustingId,
      ssrApiUrl,
    },
    multistore: {
      enabled: isMultiStoreEnabled,
    },
  });
}

Create SDK Config

Create sdk/config.ts to define which modules the SDK uses. This is a separate file so it can be imported on both the server and the client.

sdk/config.ts

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

import * as modules from "@/sdk/modules";

export function getSdkConfig() {
  return defineSdkConfig(modules);
}

Define SDK Modules

Create your SDK modules under sdk/modules/. Each module is a separate file that uses defineSdkModule to configure how it communicates with the middleware.

sdk/modules/unified.ts

import { defineSdkModule } from "@vue-storefront/next";
import type { UnifiedEndpoints } from "storefront-middleware/types";

export const unified = defineSdkModule(
  ({ buildModule, config, getRequestHeaders, middlewareModule }) =>
    buildModule(middlewareModule<UnifiedEndpoints>, {
      apiUrl: `${config.apiUrl}/commerce/unified`,
      cdnCacheBustingId: config.cdnCacheBustingId,
      defaultRequestConfig: {
        headers: async () => getRequestHeaders(),
      },
      ssrApiUrl: `${config.ssrApiUrl}/commerce/unified`,
    }),
);

sdk/modules/commerce.ts

import { defineSdkModule } from "@vue-storefront/next";
import type { CommerceEndpoints } from "storefront-middleware/types";

export const commerce = defineSdkModule(
  ({ buildModule, config, getRequestHeaders, middlewareModule }) =>
    buildModule(middlewareModule<CommerceEndpoints>, {
      apiUrl: `${config.apiUrl}/commerce`,
      cdnCacheBustingId: config.cdnCacheBustingId,
      defaultRequestConfig: {
        headers: async () => getRequestHeaders(),
      },
      ssrApiUrl: `${config.ssrApiUrl}/commerce`,
    }),
);

sdk/modules/index.ts

export * from "./unified";
export * from "./commerce";

The factory function receives a context object with these key properties:

buildModule — builds the module from a module definition and its configuration.
middlewareModule — the default SDK module for communicating with your Server Middleware. Pass your endpoint types as a generic parameter (e.g. middlewareModule<CommerceEndpoints>).
config — contains apiUrl, ssrApiUrl, and cdnCacheBustingId resolved from your SDK options.
getRequestHeaders — proxies incoming request headers (cookies, etc.) to SDK requests during SSR. Returns an empty object in the browser.

Create the Universal SDK Instance

Create sdk/sdk.server.ts. The createSdk function takes your options and config, and returns a getSdk function for creating SDK instances.

sdk/sdk.server.ts

import { createSdk } from "@vue-storefront/next";

import { getSdkConfig } from "@/sdk/config";
import { getSdkOptions } from "@/sdk/options";

export const { getSdk } = createSdk(getSdkOptions(), getSdkConfig());

export type Sdk = ReturnType<typeof getSdk>;

Create the Server-Side Wrapper

Create sdk/index.ts — the entry point that your server components import from. It wraps getSdk with locale resolution and request headers (cookies, headers) from the incoming request.

sdk/index.ts

import { cookies, headers } from "next/headers";
import { getLocale } from "next-intl/server";

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

export const getSdk = async () => {
  const locale = await getLocale();
  return getUniversalSdk({
    getLocale: () => locale,
    getRequestHeaders: async () => ({
      cookies: await cookies(),
      headers: await headers(),
    }),
  });
};

Create the Client-Side Context

Create sdk/alokai-context.tsx. The createAlokaiContext function provides the AlokaiProvider, the useSdk hook, and state management hooks for your application.

sdk/alokai-context.tsx

"use client";

import { createAlokaiContext } from "@vue-storefront/next/client";
import type { SfContract } from "storefront-middleware/types";

import type { Sdk } from "@/sdk/sdk.server";

export const {
  AlokaiProvider,
  useSdk,
  useSfCartState,
  useSfCurrenciesState,
  useSfCurrencyState,
  useSfCustomerState,
  useSfLocaleState,
  useSfLocalesState,
} = createAlokaiContext<Sdk, SfContract>();

The SfContract generic tells the state management hooks which types your middleware uses for cart (SfCart), customer (SfCustomer), currency (SfCurrency), and locale (SfLocale). You can read more in the State Management page.

Wire Up the AlokaiProvider

Fetch initial data (like currencies) on the server in your layout and pass both the SDK options and initial data to a client Providers component.

app/[locale

import type { ReactNode } from "react";
import { NextIntlClientProvider } from "next-intl";
import { getMessages } from "next-intl/server";

import Providers from "@/components/providers";
import { getSdk } from "@/sdk";
import { getSdkOptions } from "@/sdk/options";

export default async function RootLayout({
  children,
}: {
  children: ReactNode;
}) {
  const sdk = await getSdk();
  const currencies = await sdk.unified.getCurrencies();
  const sdkOptions = getSdkOptions();
  const messages = await getMessages();

  return (
    <html lang="en">
      <body>
        <NextIntlClientProvider messages={messages}>
          <Providers initialCurrency={currencies} sdkOptions={sdkOptions}>
            {children}
          </Providers>
        </NextIntlClientProvider>
      </body>
    </html>
  );
}

components/providers.tsx

"use client";

import type { CreateSdkOptions } from "@vue-storefront/next";
import { createSdk } from "@vue-storefront/next";
import { useLocale } from "next-intl";
import type { ReactNode } from "react";

import { AlokaiProvider } from "@/sdk/alokai-context";
import { getSdkConfig } from "@/sdk/config";

export default function Providers({
  children,
  initialCurrency,
  sdkOptions,
}: {
  children: ReactNode;
  initialCurrency: { currencies: string[]; currentCurrency: string };
  sdkOptions: CreateSdkOptions;
}) {
  const { getSdk } = createSdk(sdkOptions, getSdkConfig());
  const locale = useLocale();

  return (
    <AlokaiProvider
      initialData={{
        currencies: initialCurrency.currencies,
        currency: initialCurrency.currentCurrency,
        locale,
      }}
      sdk={getSdk({ getLocale: () => locale })}
    >
      {children}
    </AlokaiProvider>
  );
}

Don't be alarmed by the "use client" directive in providers.tsx. It doesn't turn your application into a client-side rendered app — all children inside the provider are still rendered on the server by default. Read more about "use client" in the React Documentation.

Usage

Once you've registered the SDK in your application, you can start using it. For more information about available methods, refer to the respective Integration's documentation.

Server Components — use getSdk to create a new SDK instance. It has access to request headers and cookies, making it ideal for SSR data fetching.

import { getSdk } from "@/sdk";

export default async function SearchPage() {
  const sdk = await getSdk();
  const productCatalog = await sdk.unified.searchProducts({});

  return (
    <ul>
      {productCatalog.products.map((product) => (
        <li key={product.id}>{product.name}</li>
      ))}
    </ul>
  );
}

Client Components — use the useSdk hook to access the shared SDK instance provided by AlokaiProvider. Pair it with TanStack Query for caching and state management.

"use client";

import { useSdk } from "@/sdk/alokai-context";
import { useQuery } from "@tanstack/react-query";

export function Products() {
  const sdk = useSdk();
  const { data } = useQuery({
    queryFn: () => sdk.unified.searchProducts({}),
    queryKey: ["products"],
  });

  return (
    <ul>
      {data?.products?.map((product) => (
        <li key={product.id}>{product.name}</li>
      ))}
    </ul>
  );
}

That's it! You can now use Alokai SDK Module in your NextJS app ✨

Next Steps

State Management

Learn how to use built in State Manager

Extending the SDK

Learn how to customize, override, or extend any default functionality in the SDK

The middlewareModule

Understand how to use the default SDK module

Create a custom SDK module

Create your own custom SDK module

View all Integrations

View our ready-to-use integrations for popular e-commerce services