Setup for Alokai Storefront

This documentation explains how to get started with Amplience in a Alokai Storefront application.

Requirements

• Alokai Storefront project,
• Amplience environment,
• Node.js version 18.x,
• @vsf-enterprise NPM registry access.

Quick setup

Our CMS CLI allows you to connect Amplience to your Alokai Storefront by executing a single command combination from the root of your project:

npx @vsf-enterprise/cms-cli amplience:components -u -f next && npx @vsf-enterprise/cms-cli amplience:storefront -f next

For a full list and detailed descriptions of available arguments and flags, run:

npx @vsf-enterprise/cms-cli amplience --help

If quick setups are not your thing and you would like to have a full understanding of the process, follow the Step by step guide.

Step-by-step setup

Installing the Amplience integration in an Alokai Storefront project requires:

• importing integration components,
• installing integration dependencies,
• adding Amplience module to the SDK,
• adding Amplience API Client to the Server Middleware

This chapter will describe all these steps in more detail.

Importing integration components

From the root of your project, run the following command:

npx @vsf-enterprise/cms-cli amplience:components -u -f next

This will create (or overwrite) the following files in your project:

└── apps
      └── storefront-unified-nextjs
          ├── components
          │   └── cms
          │       ├── layout
          │       │   ├── Footer.tsx
          │       │   └── MegaMenu.tsx
          │       ├── page
          │       │   ├── Accordion.tsx
          │       │   ├── Banner.tsx
          │       │   ├── Card.tsx
          |       |   ├── CategoryCard.tsx
          │       │   ├── Editorial.tsx
          │       │   ├── Gallery.tsx
          │       │   ├── Grid.tsx
          │       │   ├── Hero.tsx
          │       │   ├── NewsletterBox.tsx
          │       │   ├── ProductCard.tsx
          │       │   └── Scrollable.tsx
          │       └── wrappers
          │           └── RenderComponent.tsx
          ├── layouts
          │   └── AmplienceLayout.tsx
          └── pages
              ├── [[...slug]].tsx
              ├── _app.tsx
              └── amplience-visualization.tsx

Installing dependencies

The integration requires a few additional dependencies to function, including extra packages for Storefront UI and general CMS components.

First, navigate to the frontend directory

cd apps/storefront-unified-nextjs

and install the following packages:

yarn add @vsf-enterprise/cms-components-utils @vsf-enterprise/amplience-sdk dc-visualization-sdk

Second, in the /apps/storefront-middleware directory, install the following packages:

yarn add @vsf-enterprise/amplience-api

Configuring the SDK

The next step is adding the Amplience module to Alokai SDK. It ships with functions responsible for fetching and resolving raw data from Amplience.

In the /apps/storefront-unified-nextjs/sdk directory, find the sdk.config.ts file and initialize the Amplience module with the following lines:

import { amplienceModule } from '@vsf-enterprise/amplience-sdk';
import type { Endpoints as AmplienceEndpoints } from "@vsf-enterprise/amplience-api";

export const { getSdk } = createSdk(options, ({ buildModule, middlewareUrl, getRequestHeaders }) => ({
  // ...
  amplience: buildModule(amplienceModule<AmplienceEndpoints>, {
    apiUrl: `${middlewareUrl}/ampl`,
  }),
}));

Now your Amplience SDK is ready for take off. To see a full list of available methods, check out the API Reference.

Configuring Server Middleware

The last step is configuring the Amplience integration in the Server Middleware.

In the /apps/storefront-middleware directory, find the middleware.config.ts file. Add the following integration configuration, replacing <amplience_hubname> and <amplience_staging_env> with your environment's credentials:

module.exports = {
  integrations: {
    ampl: {
      location: '@vsf-enterprise/amplience-api/server',
      configuration: {
        hubName: '<amplience_hubname>',
        stagingEnvironment: '<amplience_staging_env>',
      },
    },
  },
};

What next?

With your frontend application ready, it's time to prepare a corresponding setup in Amplience. Fortunately, Alokai ships with a pre-defined set of Content Types matching your frontend components. Proceed to the Bootstrapping Amplience guide to find out how you can import them into your space.