Setup for Alokai Storefront

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

Requirements

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

Quick setup

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

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

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

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

If you prefer a more hands-on approach and would like to have a full understanding of the process, follow the Step by step guide.

Step-by-step setup

Installing the Contentful integration in an Alokai Storefront project requires:

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

This chapter will describe all of those steps in more detail.

Importing integration components

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

npx @vsf-enterprise/cms-cli contentful: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
          │   └── ContentfulLayout.tsx
          └── pages
              └── [[...slug]].tsx

Installing dependencies

The integration requires a few additional dependencies to run. That includes supplementary packages related to Storefront UI or agnostic 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/contentful-sdk

Second, in the middleware directory

cd ../storefront-middleware

install the following packages:

yarn add @vsf-enterprise/contentful-api

Configuring Server Middleware

The next step is configuring the Contentful integration in the Server Middleware.

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

module.exports = {
  integrations: {
    // ...
    cntf: {
      location: '@vsf-enterprise/contentful-api/server',
      configuration: {
        space: '<contentful_space_id>',
        token: '<contentful_access_token>',
      },
    },
  },
};

Configuring the SDK

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

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

import { contentfulModule } from '@vsf-enterprise/contentful-sdk';
import type { Endpoints as ContentfulEndpoints } from "@vsf-enterprise/contentful-api";

export const { getSdk } = createSdk(options, ({ buildModule, middlewareUrl, getRequestHeaders }) => ({
  // ...
  contentful: buildModule(contentfulModule<ContentfulEndpoints>, {
    apiUrl: `${middlewareUrl}/cntf`,
  }),
}));

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

What next?

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