Installation

This documentation covers the standalone Amplience integration and does not describe all the capabilities the Alokai ↔ Amplience setup offers. If your project is using Alokai Amplience Module, we recommend visiting its documentation instead - it provides information on unified data structure, ready-made components, and a more streamlined developer experience.

By default, Alokai integration for Amplience is meant to be used as a Storefront module. However, it can also be installed in any Next or Nuxt application.

Requirements

Next or Nuxt frontend with Alokai SDK installed (latest version),
Server Middleware application (latest version),
Amplience environment,
Node.js version 20.x or >= 22.14.0,
@vsf-enterprise NPM registry access.

Bootstrapping Amplience Before you start using our Amplience integration, you need to bootstrap your Amplience hub with Alokai schemas. These schemas include content type schemas and example content items that are aligned with our out-of-the-box frontend components.

The bootstrapping process includes setting up prerequisites (locales and repository), importing integration schemas using Amplience CLI, and enabling visualizations. For detailed instructions, please refer to our Bootstrapping Amplience guide.

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

Installing dependencies

In your frontend application, install the following dependencies:

yarn add @vsf-enterprise/amplience-sdk

npm install @vsf-enterprise/amplience-sdk

pnpm add @vsf-enterprise/amplience-sdk

In your Server Middleware application, install the following dependencies:

yarn add @vsf-enterprise/amplience-api

npm install @vsf-enterprise/amplience-api

pnpm add @vsf-enterprise/amplience-api

Adding environment variables

In the .env file of your Server Middleware application, add the following environment variables:

AMPL_HUB_NAME=<YOUR_AMPL_HUB_NAME>
AMPL_STAGING_ENV=<YOUR_AMPL_STAGING_ENV>

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

Configuring Server Middleware

The next 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.

Add the following configuration to your Server Middleware configuration file.

middleware.config.ts

import type { Integration } from "@alokai/connect/middleware";
import type { MiddlewareConfig as AmplienceMiddlewareConfig } from "@vsf-enterprise/amplience-api";

const { AMPL_HUB_NAME, AMPL_STAGING_ENV } = process.env;

if (!AMPL_HUB_NAME) throw new Error("Missing env var: AMPL_HUB_NAME");
if (!AMPL_STAGING_ENV) throw new Error("Missing env var: AMPL_STAGING_ENV");

export default {
  integrations: {
    amplience: {
      location: "@vsf-enterprise/amplience-api/server",
      configuration: {
        hubName: AMPL_HUB_NAME,
        stagingEnvironment: AMPL_STAGING_ENV,
        unified: {
          resolvePages: () => ({
            "/*": {},
          }),
          resolveFallbackPage: () => ({
            path: "fallback-page",
          }),
        },
      },
    } satisfies Integration<AmplienceMiddlewareConfig>,
  },
};

Configuring Alokai SDK

The last step in the process is configuring Alokai SDK for Amplience in your frontend application.

Key concept - SDK SDK core is described in detail in our SDK docs.

Add the following configuration to your SDK modules:

sdk/modules/amplience.ts

import { defineSdkModule } from '@vue-storefront/next';
import { amplienceModule } from '@vsf-enterprise/amplience-sdk';

export const amplience = defineSdkModule(({ buildModule, config, getRequestHeaders }) =>
  buildModule(amplienceModule, {
    apiUrl: `${config.apiUrl}/amplience`,
    ssrApiUrl: `${config.ssrApiUrl}/amplience`,
    defaultRequestConfig: {
      headers: getRequestHeaders(),
    },
  }),
);

sdk/modules/index.ts

export * from './amplience';
// ... other module exports

sdk-modules/amplience.ts

import { amplienceModule } from '@vsf-enterprise/amplience-sdk';

export const amplience = defineSdkModule(({ buildModule, config, getRequestHeaders }) =>
  buildModule(amplienceModule, {
    apiUrl: `${config.apiUrl}/amplience`,
    ssrApiUrl: `${config.ssrApiUrl}/amplience`,
    defaultRequestConfig: {
      headers: getRequestHeaders(),
    },
  }),
);

sdk-modules/index.ts

export * from './amplience';
// ... other module exports

Requirements

Installing dependencies

Adding environment variables

Configuring Server Middleware

Configuring Alokai SDK

On this page