Vue Storefront is now Alokai! Learn More
Setup for Alokai Storefront

Setup for Alokai Storefront

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

Requirements

Something's missing?

If you don't have an Alokai Storefront project yet, request a demo from our Sales team. If you don't have an Amplience space yet, we suggest you request a demo from the Amplience team.

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.

Check out our compatibility matrix for the integration before installing the dependencies described in this guide.

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.

Key concept - SDK

SDK is described in detail in our Key concepts: SDK docs. Also, read about middlewareModule used by our Amplience SDK module under the hood.

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.

Key concept: Server Middleware

Middleware concept is described in detail in our Key concepts: Server Middleware docs.

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>',
      },
    },
  },
};

Good to know

Read the Amplience docs to find out where to get your hubName and stagingEnvironment.

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.