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

Setup for Alokai Storefront

This documentation explains how to get started with Contentful 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 a Contentful space yet, we suggest you request a demo from the Contentful team.

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.

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/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.

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

Good to know

Information on where to get your Contentful access token from can be found here.

Keep your tokens safe

We recommend keeping your Contentful access token in the .env file and referencing it through process.env in middleware.config.ts.

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.

Key concept - SDK

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

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.