Quick start

Your Alokai application has two parts:

Server Middleware - an Express.js application that can connect to your various third-party services (like Magento).
Front-end application - any application using JavaScript or TypeScript that can connect to the server middleware. Popular choices include Nuxt and Next.js.

The Open Source version of Magento integration does not come out of the box with ready storefront. This is an Enterprise-only feature. Read more about Alokai Enterprise

In this section, we will explain in a step-by-step guide how to use Magento 2 integration in each part of your Alokai application.

Learn more about the Alokai middleware layer in our Key concepts: Middleware docs.

Learn more about the SDK in our Key concepts: SDK docs.

Prerequisites

Magento configured - if you don't have your Magento 2 configured, see our Magento Installation guide.
Install Node.js version >=16.0

Server Middleware

The first step to setup your integration is to create and configure your server middleware layer to connect to your Magento 2 backend.

For an example of a generic server middleware configuration, check out one of our boilerplates.

Already have the server middleware configured?

If you have the server middleware configured, you can move directly to the SDK preparation part.

Install the dependencies needed to create your server middleware and to create a server-to-server connection with the Magento 2 backend and the server middleware.

yarn add @vue-storefront/middleware @vue-storefront/magento-api

# npm install @vue-storefront/middleware @vue-storefront/magento-api

# pnpm install @vue-storefront/middleware @vue-storefront/magento-api

Create a file middleware.config.js with server middleware configuration.

// middleware.config.js

import { config } from "dotenv";

config();

const cookieNames = {
  currencyCookieName: "vsf-currency",
  countryCookieName: "vsf-country",
  localeCookieName: "vsf-locale",
  cartCookieName: "vsf-cart",
  customerCookieName: "vsf-customer",
  storeCookieName: "vsf-store",
  messageCookieName: "vsf-message",
};

export const integrations = {
  magento: {
    location: "@vue-storefront/magento-api/server",
    configuration: {
      api: process.env.VSF_MAGENTO_GRAPHQL_URL,
      cookies: {
        ...cookieNames,
      },
      cookiesDefaultOpts: {
        httpOnly: process.env.VSF_COOKIE_HTTP_ONLY || false,
        secure: process.env.VSF_COOKIE_SECURE || false,
        sameSite: process.env.VSF_COOKIE_SAME_SITE || "lax",
        path: process.env.VSF_COOKIE_PATH || "/",
      },
      defaultStore: "default",
      customApolloHttpLinkOptions: {
        useGETForQueries: true,
      },
      magentoBaseUrl: process.env.VSF_MAGENTO_BASE_URL,
      magentoApiEndpoint: process.env.VSF_MAGENTO_GRAPHQL_URL,
      imageProvider: process.env.NUXT_IMAGE_PROVIDER,
      recaptcha: {
        isEnabled: process.env.VSF_RECAPTCHA_ENABLED === "true",
        sitekey: process.env.VSF_RECAPTCHA_SITE_KEY,
        secretkey: process.env.VSF_RECAPTCHA_SECRET_KEY,
        version: process.env.VSF_RECAPTCHA_VERSION,
        score: process.env.VSF_RECAPTCHA_MIN_SCORE,
      },
      customer: {
        customer_create_account_confirm: true,
      },
    },
  },
};

Configure environment variables in your .env file.

# .env

VSF_NUXT_APP_ENV=production
VSF_NUXT_APP_PORT=3000
VSF_NUXT_APP_HOST=0.0.0.0

VSF_STORE_URL=
API_BASE_URL=
API_SSR_BASE_URL=

VSF_MAGENTO_BASE_URL=
VSF_MAGENTO_GRAPHQL_URL=

NUXT_IMAGE_PROVIDER=ipx

Create a middleware.js file. This script is used to run the server middleware.

// middleware.js

import { createServer } from "@vue-storefront/middleware";
import { integrations } from "./middleware.config.js";
import cors from "cors";

(async () => {
  const app = await createServer({ integrations });
  const host = process.argv[2] ?? "0.0.0.0";
  const port = process.argv[3] ?? 8181;
  const CORS_MIDDLEWARE_NAME = "corsMiddleware";

  const corsMiddleware = app._router.stack.find(
    (middleware) => middleware.name === CORS_MIDDLEWARE_NAME
  );

  corsMiddleware.handle = cors({
    origin: [
      "http://localhost:3000",
      ...(process.env.MIDDLEWARE_ALLOWED_ORIGINS?.split(",") ?? []),
    ],
    credentials: true,
  });

  app.listen(port, host, () => {
    console.log(`Middleware started: ${host}:${port}`);
  });
})();

Your middleware is ready. You can start it by running node middleware.js. Most likely, you'll want to setup this command as a script in your package.json file.

{
  // ...
  "scripts": {
    "start": "node middleware.js"
  }
  // ...
}

Configuring the SDK

Now, let's configure the SDK in the frontend part of your application to communicate with the server middleware.

Initialize the SDK. Configure middlewareModule with apiUrl that points to the Magento 2 integration in the Alokai Middleware.

import { buildModule, initSDK, middlewareModule } from "@vue-storefront/sdk";
import { Endpoints } from "@vue-storefront/magento-api";

const sdkConfig = {
  magento: buildModule(middlewareModule<Endpoints>, {
    apiUrl: "http://localhost:8181/magento",
  }),
};

export const sdk = initSDK(sdkConfig);

Your SDK is ready! You can now import it in the different parts of your frontend application and call methods with sdk.magento.<METHOD_NAME>. To see a full list of methods offered by the Magento 2 integration, check out the API Reference.

For example, we can call the products method to fetch products from Magento 2.

import { sdk } from "./sdk";
const products = await sdk.magento.products({});
// returns ProductInterface[]